Alauda Container Platform
简体中文

使用 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. 目录

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

术语定义

术语定义备注
Application CatalogHelm Charts 的一站式管理平台
Helm Charts一种应用打包格式
HelmRequestCRD。定义部署 Helm Chart 所需的配置模板应用
ChartRepoCRD。对应 Helm charts 仓库模板仓库
ChartCRD。对应 Helm Charts模板

1.3 了解 HelmRequest

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

HelmRequest 与 Helm 的区别

标准 Helm 使用 CLI 命令管理 release，而 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 并同步为 Application
  6. Application 提供已部署资源的统一视图

组件定义

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

2 通过 CLI 将 Helm Charts 作为应用部署

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 作为应用部署

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 并确认。

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