使用 Helm charts

1. 了解 Helm

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

1.1. 主要功能

Helm 提供以下能力：

在 chart 仓库中搜索大量 charts
修改已有的 charts
使用 Kubernetes 资源创建自定义 charts
打包应用并以 charts 形式共享

1.2. 目录

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

术语定义

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

1.3 了解 HelmRequest

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

HelmRequest 与 Helm 的区别

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

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

HelmRequest 与 Application 集成

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

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

alauda.io/create-app: "true"

启用此功能后，平台 UI 会显示额外字段，并提供跳转到对应 Application 页面的链接。

部署工作流

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

用户创建或更新 HelmRequest 资源
HelmRequest 包含 chart 引用及应用的 values
Captain 处理 HelmRequest 并创建 Helm Release
Release 包含已部署的资源
Metis 监控带有应用注解的 HelmRequest 并同步到 Application
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 以 Application 形式部署 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 令牌

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

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 上传相关镜像

拉取镜像：podman pull nginx
保存为 tar 包：podman save nginx > nginx.latest.tar

加载并推送到私有仓库：

podman load -i nginx.latest.tar
podman tag nginx:latest 192.168.80.8:30050/nginx:latest
podman 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 以 Application 形式部署 Helm Charts

3.1 工作流概览

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

3.2 前提条件

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

3.3 将模板添加到可管理仓库

进入 Catalog。
在左侧导航栏点击 Helm Charts。

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

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

点击 Upload Template，上传本地模板到仓库。
点击 Confirm。模板上传过程可能需要几分钟，请耐心等待。

注意：当模板状态从 Uploading 变为 Upload Successful，表示模板上传成功。
若上传失败，请根据提示排查。

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

3.4 删除模板的特定版本

当某个模板版本不再适用时，可以删除该版本。

操作步骤

进入 Catalog。
在左侧导航栏点击 Helm Charts。
点击 Chart 卡片查看详情。
点击 Manage Versions。
找到不再适用的模板版本，点击 Delete 并确认。

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

#使用 Helm charts

#目录

#1. 了解 Helm

#1.1. 主要功能

#1.2. 目录

#术语定义

#1.3 了解 HelmRequest

#HelmRequest 与 Helm 的区别

#HelmRequest 与 Application 集成

#部署工作流

#组件定义

#2 通过 CLI 以 Application 形式部署 Helm Charts

#2.1 工作流概览

#2.2 准备 Chart

#2.3 打包 Chart

#2.4 获取 API 令牌

#2.5 创建 Chart 仓库

#2.6 上传 Chart

#2.7 上传相关镜像

#2.8 部署应用

#2.9 更新应用

#2.10 卸载应用

#2.11 删除 Chart 仓库

#3 通过 UI 以 Application 形式部署 Helm Charts

#3.1 工作流概览

#3.2 前提条件

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

#3.4 删除模板的特定版本

#操作步骤