---
url: /zh/artifact/helm.md
description: |
  介绍如何登录和使用 CNB Helm 制品库（OCI 格式）， 包括制品路径规则、推送和拉取 Helm Chart 的方法。
---
## 登录 CNB Helm 制品库

CNB Helm 仅支持 OCI 格式的 Helm 制品，建议使用 Helm v3.8.0 以上版本，详情请查阅 Helm 文档。

登录命令如下。获取 `CNB_TOKEN` 的方式参考 [创建访问令牌](./intro.md#创建访问令牌)。

```bash
helm registry login helm.cnbprod.alpha.qq.com -u cnb -p ${CNB_TOKEN}
```

> **注意**：Helm 制品库仅接受 Helm Chart（OCI 格式）的推送。
> 容器镜像、Docker Model 等其它类型的制品推送到 Helm 地址会被拒绝，
> 请确认推送目标地址与制品类型匹配（详见 [制品类型准入限制](./intro.md#制品类型准入限制)）。

## Helm 制品路径规则

Helm 制品发布到仓库时，支持两种命名规则：

1. **同名制品**：制品路径与仓库路径一致，如：`helm.cnbprod.alpha.qq.com/${CNB_REPO_SLUG_LOWERCASE}`
2. **非同名制品**：以仓库路径作为命名空间，
   其制品路径 = 仓库路径/制品名称，如：`helm.cnbprod.alpha.qq.com/${CNB_REPO_SLUG_LOWERCASE}/<ARTIFACT_NAME>`

注意：使用 `helm push remote` 时，chart name 不出现在 remote-url 中，而是从 chart 中读取。
因此，同名制品的 remote-url 为 `helm.cnbprod.alpha.qq.com/${CNB_GROUP_SLUG_LOWERCASE}`，
非同名制品的 remote-url 为 `helm.cnbprod.alpha.qq.com/${CNB_REPO_SLUG_LOWERCASE}`。

## 推送制品

### 本地推送

同名制品

```bash
helm package chart-path
helm push chartname-version.tgz oci://helm.cnbprod.alpha.qq.com/${CNB_GROUP_SLUG_LOWERCASE}
```

非同名制品

```bash
helm package chart-path
helm push chartname-version.tgz oci://helm.cnbprod.alpha.qq.com/${CNB_REPO_SLUG_LOWERCASE}
```

### 云原生构建中推送

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: alpine/helm
      stages:
        - name: helm login
          script: helm registry login -u ${CNB_TOKEN_USER_NAME} -p "${CNB_TOKEN}" ${CNB_HELM_REGISTRY}
        - name: helm package
          script: helm package ${YOUR_CHART_PATH}
        - name: helm push
          script: helm push chartname-version.tgz oci://${CNB_HELM_REGISTRY}/${CNB_GROUP_SLUG_LOWERCASE}
```

### 云原生开发中推送

同本地推送一致，将 `${YOUR_CHART_PATH}`、`${CNB_GROUP_SLUG_LOWERCASE}`、
`${CNB_REPO_SLUG_LOWERCASE}` 替换为实际值即可，详见上方 [本地推送](#本地推送)。

## 使用制品

### 本地命令行拉取

```bash
helm pull oci://helm.cnbprod.alpha.qq.com/<ARTIFACT_PATH> --version <VERSION>

# ...
```

### 其他常用命令

#### 查看 Helm 信息

```bash
helm show all oci://helm.cnbprod.alpha.qq.com/<ARTIFACT_PATH> --version <VERSION>
```

#### 预览 manifest

```bash
helm template <RELEASE_NAME> oci://helm.cnbprod.alpha.qq.com/<ARTIFACT_PATH> --version <VERSION>
```

#### 安装 helm chart

```bash
helm install <RELEASE_NAME> oci://helm.cnbprod.alpha.qq.com/<ARTIFACT_PATH> --version <VERSION>
```

#### 升级 helm chart

```bash
helm upgrade <RELEASE_NAME> oci://helm.cnbprod.alpha.qq.com/<ARTIFACT_PATH> --version <VERSION>
```

## 直链下载

除 `helm pull` 等 OCI 协议命令外，CNB 还提供通过 HTTP 直链下载 `.tgz` 文件的接口。
该接口返回 `.tgz` 文件流（不会产生 302 重定向），适用于仅支持裸 tarball 的下游系统。

### URL 格式

直链 URL 格式如下：

```bash
# 同名制品
https://helm.cnbprod.alpha.qq.com/charts/<NAMESPACE>/v/<VERSION>.tgz

# 非同名制品
https://helm.cnbprod.alpha.qq.com/charts/<NAMESPACE>/<CHART_NAME>/v/<VERSION>.tgz
```

其中 `<NAMESPACE>` 为仓库路径（如 `${CNB_REPO_SLUG_LOWERCASE}`），
`<CHART_NAME>` 为非同名制品的 chart 名称，`<VERSION>` 为制品版本号。

### 鉴权与示例

* 公开仓库：直接访问即可下载。
* 私有仓库：通过 HTTP Basic 认证访问，用户名为 `cnb`，
  密码为 [访问令牌](./intro.md#创建访问令牌)。

```bash
# 私有仓库下载非同名制品
curl -u cnb:${CNB_TOKEN} -fOJ \
  "https://helm.cnbprod.alpha.qq.com/charts/${CNB_REPO_SLUG_LOWERCASE}/mychart/v/0.6.0.tgz"
```

接口返回 `.tgz` 文件流（HTTP 200），不会产生重定向。
响应头 `Content-Disposition` 携带规范化的下载文件名 `{CHART_NAME}-{VERSION}.tgz`。

## 更多信息

更多 Helm 用法，参阅 [Helm 官方文档](https://helm.sh/zh/docs/)。