#使用 Helm charts

#1. 了解 Helm

Helm 是一个包管理器，简化了在 Alauda Container Platform 集群上部署应用和服务的流程。
Helm 使用一种称为 charts 的打包格式。Helm chart 是一组描述 Kubernetes 资源的文件集合。
在集群中创建 chart 会生成一个运行中的 chart 实例，称为 release。
每次创建 chart，或升级、回滚 release 时，都会创建一个递增的修订版本。

#1.1. 主要特性

Helm 提供以下功能：

• 在 chart 仓库中搜索大量 charts
• 修改现有的 charts
• 使用 Kubernetes 资源创建自己的 charts
• 打包应用并以 charts 形式分享

#1.2. 目录

Catalog 基于 Helm 构建，提供了一个全面的 Chart 分发管理平台，突破了 Helm CLI 工具的限制。该平台通过用户友好的界面，使开发者更便捷地管理、部署和使用 charts。

#术语定义

#1.3 了解 HelmRequest

在 Alauda Container Platform 中，Helm 部署主要通过自定义资源 HelmRequest 管理。此方法扩展了标准 Helm 功能，并无缝集成到 Kubernetes 原生资源模型中。

#HelmRequest 与 Helm 的区别

标准 Helm 使用 CLI 命令管理 releases，而 Alauda Container Platform 使用 HelmRequest 资源定义、部署和管理 Helm charts。主要区别包括：

1. 声明式 vs 命令式：HelmRequest 提供声明式的 Helm 部署方式，传统 Helm CLI 是命令式的。
2. Kubernetes 原生：HelmRequest 是直接集成 Kubernetes API 的自定义资源。
3. 持续调和：Captain 持续监控并调和 HelmRequest 资源与其期望状态。
4. 多集群支持：HelmRequest 支持通过平台跨多个集群部署。
5. 平台功能集成：HelmRequest 可与其他平台功能（如 Application 资源）集成。

#HelmRequest 与 Application 集成

HelmRequest 和 Application 资源在概念上相似，用户可能希望统一查看。平台提供机制将 HelmRequest 同步为 Application 资源。

用户可通过添加以下注解，将 HelmRequest 标记为以 Application 方式部署：

alauda.io/create-app: "true"

启用此功能后，平台 UI 会显示额外字段及链接至对应的 Application 页面。

#部署工作流

通过 HelmRequest 部署 charts 的工作流包括：

1. 用户 创建或更新 HelmRequest 资源
2. HelmRequest 包含 chart 引用及应用的 values
3. Captain 处理 HelmRequest 并创建 Helm Release
4. Release 包含已部署的资源
5. Metis 监控带有应用注解的 HelmRequest 并同步至 Applications
6. Application 提供已部署资源的统一视图

#组件定义

• HelmRequest：描述期望 Helm chart 部署的自定义资源定义
• Captain：处理 HelmRequest 资源并管理 Helm releases 的控制器（源码地址：https://github.com/alauda/captain）
• Release：Helm chart 的已部署实例
• Charon：监控 HelmRequest 并创建对应 Application 资源的组件
• Application：已部署资源的统一表示，提供额外管理能力
• Archon-api：平台内负责特定高级 API 功能的组件

#2 通过 CLI 将 Helm Charts 部署为 Applications

#2.1 工作流概览

准备 chart → 打包 chart → 获取 API 令牌 → 创建 chart 仓库 → 上传 chart → 上传相关镜像 → 部署应用 → 更新应用 → 卸载应用 → 删除 chart 仓库

#2.2 准备 Chart

Helm 使用称为 charts 的打包格式。chart 是一组描述 Kubernetes 资源的文件集合。单个 chart 可用于部署从简单 Pod 到复杂应用栈的任何内容。

参考官方文档：Helm Charts Documentation

示例 chart 目录结构：

nginx/
├── Chart.lock
├── Chart.yaml
├── README.md
├── charts/
│   └── common/
│       ├── Chart.yaml
│       ├── README.md
│       ├── templates/
│       │   ├── _affinities.tpl
│       │   ├── _capabilities.tpl
│       │   ├── _errors.tpl
│       │   ├── _images.tpl
│       │   ├── _ingress.tpl
│       │   ├── _labels.tpl
│       │   ├── _names.tpl
│       │   ├── _secrets.tpl
│       │   ├── _storage.tpl
│       │   ├── _tplvalues.tpl
│       │   ├── _utils.tpl
│       │   ├── _warnings.tpl
│       │   └── validations/
│       │       ├── _cassandra.tpl
│       │       ├── _mariadb.tpl
│       │       ├── _mongodb.tpl
│       │       ├── _postgresql.tpl
│       │       ├── _redis.tpl
│       │       └── _validations.tpl
│       └── values.yaml
├── ci/
│   ├── ct-values.yaml
│   └── values-with-ingress-metrics-and-serverblock.yaml
├── templates/
│   ├── NOTES.txt
│   ├── _helpers.tpl
│   ├── deployment.yaml
│   ├── extra-list.yaml
│   ├── health-ingress.yaml
│   ├── hpa.yaml
│   ├── ingress.yaml
│   ├── ldap-daemon-secrets.yaml
│   ├── pdb.yaml
│   ├── server-block-configmap.yaml
│   ├── serviceaccount.yaml
│   ├── servicemonitor.yaml
│   ├── svc.yaml
│   └── tls-secrets.yaml
├── values.descriptor.yaml
├── values.schema.json
└── values.yaml

关键文件说明：

• values.descriptor.yaml（可选）：配合 ACP UI 显示用户友好表单
• values.schema.json（可选）：校验 values.yaml 内容并渲染简单 UI
• values.yaml（必需）：定义 chart 部署参数

#2.3 打包 Chart

使用 helm package 命令打包 chart：

helm package nginx
# 输出: Successfully packaged chart and saved it to: /charts/nginx-8.8.0.tgz

#2.4 获取 API 令牌

1. 在 Alauda Container Platform 中，点击右上角头像 => Profile
2. 点击 Add Api Token
3. 输入合适的描述和剩余有效期
4. 保存显示的令牌信息（仅显示一次）

#2.5 创建 Chart 仓库

通过 API 创建本地 chart 仓库：

curl -k --request POST \
--url https://$ACP_DOMAIN/catalog/v1/chartrepos \
--header 'Authorization:Bearer $API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "apiVersion": "v1",
  "kind": "ChartRepoCreate",
  "metadata": {
    "name": "test",
    "namespace": "cpaas-system"
  },
  "spec": {
    "chartRepo": {
      "apiVersion": "app.alauda.io/v1beta1",
      "kind": "ChartRepo",
      "metadata": {
        "name": "test",
        "namespace": "cpaas-system",
        "labels": {
          "project.cpaas.io/catalog": "true"
        }
      },
      "spec": {
        "type": "Local",
        "url": null,
        "source": null
      }
    }
  }
}'

#2.6 上传 Chart

将打包好的 chart 上传至仓库：

curl -k --request POST \
--url https://$ACP_DOMAIN/catalog/v1/chartrepos/cpaas-system/test/charts \
--header 'Authorization:Bearer $API_TOKEN' \
--data-binary @"/root/charts/nginx-8.8.0.tgz"

#2.7 上传相关镜像

1. 拉取镜像：docker pull nginx

2. 保存为 tar 包：docker save nginx > nginx.latest.tar

3. 加载并推送至私有仓库：

   docker load -i nginx.latest.tar
   docker tag nginx:latest 192.168.80.8:30050/nginx:latest
   docker push 192.168.80.8:30050/nginx:latest

#2.8 部署应用

通过 API 创建 Application 资源：

curl -k --request POST \
--url https://$ACP_DOMAIN/acp/v1/kubernetes/$CLUSTER_NAME/namespaces/$NAMESPACE/applications \
--header 'Authorization:Bearer $API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "apiVersion": "app.k8s.io/v1beta1",
  "kind": "Application",
  "metadata": {
    "name": "test",
    "namespace": "catalog-ns",
    "annotations": {
      "app.cpaas.io/chart.source": "test/nginx",
      "app.cpaas.io/chart.version": "8.8.0",
      "app.cpaas.io/chart.values": "{\"image\":{\"pullPolicy\":\"IfNotPresent\"}}"
    },
    "labels": {
      "sync-from-helmrequest": "true"
    }
  }
}'

#2.9 更新应用

使用 PATCH 请求更新应用：

curl -k --request PATCH \
--url https://$ACP_DOMAIN/acp/v1/kubernetes/$CLUSTER_NAME/namespaces/$NAMESPACE/applications/test \
--header 'Authorization:Bearer $API_TOKEN' \
--header 'Content-Type: application/merge-patch+json' \
--data '{
  "apiVersion": "app.k8s.io/v1beta1",
  "kind": "Application",
  "metadata": {
    "annotations": {
      "app.cpaas.io/chart.values": "{\"image\":{\"pullPolicy\":\"Always\"}}"
    }
  }
}'

#2.10 卸载应用

删除 Application 资源：

curl -k --request DELETE \
--url https://$ACP_DOMAIN/acp/v1/kubernetes/$CLUSTER_NAME/namespaces/$NAMESPACE/applications/test \
--header 'Authorization:Bearer $API_TOKEN'

#2.11 删除 Chart 仓库

curl -k --request DELETE \
--url https://$ACP_DOMAIN/apis/app.alauda.io/v1beta1/namespaces/cpaas-system/chartrepos/test \
--header 'Authorization:Bearer $API_TOKEN'

#3 通过 UI 将 Helm Charts 部署为 Applications

#3.1 工作流概览

将模板添加至可管理仓库 → 上传模板 → 管理模板版本

#3.2 前提条件

模板仓库由平台管理员添加。请联系平台管理员获取具有 管理 权限的 Chart 或 OCI Chart 类型模板仓库名称。

#3.3 将模板添加至可管理仓库

1. 进入 Catalog。

2. 在左侧导航栏点击 Helm Charts。

3. 点击页面右上角的 Add Template，根据以下参数选择模板仓库。

   参数	说明
   模板仓库	直接同步模板到具有 管理 权限的 Chart 或 OCI Chart 类型模板仓库。分配给该 模板仓库 的项目所有者可直接使用该模板。
   模板目录	当选择的模板仓库类型为 OCI Chart 时，必须选择或手动输入存放 Helm Chart 的目录。 注意：手动输入新模板目录时，平台会在模板仓库中创建该目录，但存在创建失败风险。

4. 点击 Upload Template，上传本地模板至仓库。

5. 点击 Confirm。模板上传过程可能需要几分钟，请耐心等待。

   注意：当模板状态由 Uploading 变为 Upload Successful 时，表示模板上传成功。

6. 若上传失败，请根据提示进行排查。

   注意：非法文件格式表示上传的压缩包内文件存在问题，如内容缺失或格式错误。

#3.4 删除模板的特定版本

如果某版本模板不再适用，可删除该版本。

#操作步骤

1. 进入 Catalog。

2. 在左侧导航栏点击 Helm Charts。

3. 点击 Chart 卡片查看详情。

4. 点击 Manage Versions。

5. 找到不再适用的模板版本，点击 Delete 并确认。

   删除版本后，相关应用将无法更新。