📚 课程目录第4章 Helm仓库搭建

4. Helm仓库搭建：使用ChartMuseum搭建私有仓库、配置持久化存储、启用TLS

在生产环境中，团队通常需要私有Helm Chart仓库来存储内部开发的Chart包，避免直接依赖公共仓库。ChartMuseum是一个轻量级、可自托管的Helm Chart仓库服务器，支持多种存储后端、API操作和TLS加密。本节将完整演示从部署到安全加固的全流程。

4.1 ChartMuseum架构概览

ChartMuseum采用无状态API服务+后端存储的架构设计，客户端通过RESTful API上传、查询和下载Chart包。下图展示了核心组件与交互流程：

4.2 部署ChartMuseum到Kubernetes集群

推荐使用Helm Chart部署ChartMuseum，官方Chart已托管在ChartMuseum仓库中。以下是部署步骤：

4.2.1 添加Chart仓库并获取默认配置

# 添加 ChartMuseum 官方 Helm 仓库
helm repo add chartmuseum https://chartmuseum.github.io/charts
helm repo update

# 查看默认 values.yaml
helm show values chartmuseum/chartmuseum > chartmuseum-values.yaml

4.2.2 核心配置参数说明

参数路径	默认值	说明
`env.open.DISABLE_API`	`false`	是否禁用API操作（上传/删除）
`env.open.STORAGE`	`local`	存储后端类型：local / amazon / google / microsoft / alibaba
`persistence.enabled`	`false`	是否启用持久化存储卷
`persistence.size`	`10Gi`	持久化存储容量
`ingress.enabled`	`false`	是否启用Ingress暴露服务
`ingress.tls`	`[]`	Ingress TLS证书配置

4.2.3 使用本地存储部署（测试环境）

cat <<EOF > chartmuseum-local.yaml
persistence:
  enabled: true
  size: 5Gi
  storageClass: "standard"  # 根据集群调整

env:
  open:
    DISABLE_API: false
    STORAGE: local
    STORAGE_LOCAL_ROOTDIR: /charts

service:
  type: ClusterIP
  port: 8080

ingress:
  enabled: true
  hosts:
    - host: chartmuseum.example.com
      paths:
        - /
  tls:
    - secretName: chartmuseum-tls
      hosts:
        - chartmuseum.example.com
EOF

helm install chartmuseum chartmuseum/chartmuseum \
  -f chartmuseum-local.yaml \
  --namespace helm-system \
  --create-namespace

4.3 配置持久化存储

生产环境必须使用持久化存储，确保Pod重启或迁移后Chart数据不丢失。ChartMuseum支持多种存储后端，以下列出最常用的两种方案：

4.3.1 方案一：Kubernetes PVC + NFS/Ceph

适用于自建Kubernetes集群，通过PVC挂载共享存储：

persistence:
  enabled: true
  existingClaim: ""          # 使用已有PVC时填写名称
  storageClass: "nfs-client" # 使用动态存储类
  accessMode: ReadWriteMany  # 多Pod共享读写
  size: 20Gi
  annotations: {}            # 可选PVC注解

# 如果使用已有PVC，需提前创建
# kubectl create -f - <<EOF
# apiVersion: v1
# kind: PersistentVolumeClaim
# metadata:
#   name: chartmuseum-data
#   namespace: helm-system
# spec:
#   storageClassName: nfs-client
#   accessModes:
#     - ReadWriteMany
#   resources:
#     requests:
#       storage: 20Gi
# EOF

4.3.2 方案二：对象存储（S3兼容）

适用于云原生环境，对象存储天然具备高可用和无限扩展能力：

env:
  open:
    STORAGE: amazon
    STORAGE_AMAZON_BUCKET: my-helm-charts
    STORAGE_AMAZON_PREFIX: ""
    STORAGE_AMAZON_REGION: us-east-1
    STORAGE_AMAZON_ENDPOINT: https://s3.custom-domain.com  # 兼容S3的存储
    STORAGE_AMAZON_SSE: AES256

# 通过Secret传递AWS凭证
secret:
  AWS_ACCESS_KEY_ID: "YOUR_ACCESS_KEY"
  AWS_SECRET_ACCESS_KEY: "YOUR_SECRET_KEY"

存储选型建议： 单集群小规模（Chart数 < 500）使用PVC+NFS；多集群或大规模使用对象存储，便于统一管理和跨集群同步。

4.4 启用TLS加密

生产环境必须启用TLS保护Chart传输安全。提供两种主流方案：

4.4.1 方案一：Ingress层TLS终止（推荐）

利用Ingress Controller处理TLS，ChartMuseum后端仍使用HTTP：

ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/proxy-body-size: "100m"  # 允许大Chart上传
  hosts:
    - host: chartmuseum.internal.company.com
      paths:
        - /
  tls:
    - secretName: chartmuseum-tls-secret
      hosts:
        - chartmuseum.internal.company.com

# 创建TLS Secret（使用自签名证书或Let's Encrypt）
# kubectl create secret tls chartmuseum-tls-secret \
#   --cert=path/to/tls.crt \
#   --key=path/to/tls.key \
#   --namespace helm-system

4.4.2 方案二：ChartMuseum直接启用TLS

适用于无Ingress或需要端到端加密的场景：

env:
  open:
    TLS_CERT: /etc/chartmuseum/certs/tls.crt
    TLS_KEY: /etc/chartmuseum/certs/tls.key

extraVolumes:
  - name: tls-certs
    secret:
      secretName: chartmuseum-tls-secret

extraVolumeMounts:
  - name: tls-certs
    mountPath: /etc/chartmuseum/certs
    readOnly: true

service:
  type: ClusterIP
  port: 443
  targetPort: 443

# 注意：直接启用TLS后，service端口需改为443

4.5 验证与测试

部署完成后，执行以下命令验证仓库可用性：

# 1. 添加仓库
helm repo add my-charts https://chartmuseum.internal.company.com
helm repo list

# 2. 推送Chart（需安装helm-push插件）
helm plugin install https://github.com/chartmuseum/helm-push
helm push my-app-1.0.0.tgz my-charts

# 3. 搜索Chart
helm search repo my-charts

# 4. 查看仓库索引
curl -k https://chartmuseum.internal.company.com/index.yaml | head -20

# 5. 查看API健康状态
curl -k https://chartmuseum.internal.company.com/health

4.6 生产环境配置清单

配置项	推荐值	说明
存储后端	S3 / MinIO / Ceph RGW	对象存储，支持多集群共享
持久化容量	20Gi ~ 100Gi	根据Chart数量和大小预估
TLS方案	Ingress + cert-manager	自动证书续期，运维成本低
API访问控制	启用Basic Auth或OIDC	防止未授权上传/删除
资源限制	CPU: 200m ~ 500m Memory: 256Mi ~ 512Mi	ChartMuseum资源消耗较低
副本数	2 ~ 3	保证高可用，共享同一存储

安全注意事项：

生产环境务必禁用 DISABLE_API=false 并配合认证机制
TLS证书使用受信任的CA签发，避免自签名证书导致的客户端报错
对象存储的访问密钥应通过Kubernetes Secret管理，禁止明文写在values中
定期备份存储后端数据，防止误删除或存储故障

4.7 多集群共享仓库配置

当多个Kubernetes集群需要共享同一个Chart仓库时，只需将存储后端指向同一位置：

多集群共享配置要点：

所有集群的ChartMuseum实例使用相同的对象存储Bucket和相同的访问凭证
每个集群的Ingress域名可以不同，但后端存储一致
任一集群推送Chart后，其他集群立即可见（无需手动同步）
建议为每个集群配置独立的STORAGE_AMAZON_PREFIX，便于审计和回滚

4.8 运维与监控

部署完成后，建议配置以下监控指标：

存储使用量：监控Bucket或PVC的容量使用率，设置告警阈值（如80%）
API请求量：通过ChartMuseum Prometheus指标（/metrics端点）监控
TLS证书过期：使用cert-manager自动续期，或设置证书过期前30天告警
Chart版本数：定期清理旧版本，避免存储膨胀

# 启用Prometheus指标
env:
  open:
    METRICS_ENABLED: "true"

# 配置PodMonitor（需安装Prometheus Operator）
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: chartmuseum-monitor
  namespace: helm-system
spec:
  selector:
    matchLabels:
      app: chartmuseum
  podMetricsEndpoints:
  - port: http
    path: /metrics