> For the complete documentation index, see [llms.txt](https://wiki.opskumu.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.opskumu.com/kubernetes/helm/helm-using.md). # Helm 使用 这份指南介绍在 Kubernetes 集群中使用 Helm 管理包的基础知识。假设你已经安装了 Helm client。 如果你仅对运行一些快捷命令感兴趣，那么可以从 [Quickstart Guide](https://helm.sh/docs/intro/quickstart/) 开始入手。这个章节覆盖了 Helm 命令的细节，并解释如何使用 Helm。 ## 三大概念 `Chart` 是 Helm 的包。它包含了在 Kubernetes 集群中运行一个应用、工具或者服务的所有资源的必要定义。好比 Homebrew 的 formula，Apt 的 apkg ，或者 Yum 的 RPM 文件。 `Repository` 是存放收集和共享 charts 的地方。好比 Perl 的 [CPAN archive](https://www.cpan.org/) 或者 Fedora 的 [Package Database](https://admin.fedoraproject.org/pkgdb/)，只是它是针对 Kubernetes 的包。 `Release` 是 chart 运行在 Kubernetes 集群的对应实例。一个 chart 可以在一个相同的集群俺逐行多次。每次安装都创建一个新的 release。以 MySQL chart 为例，如果你想在集群中运行两个数据库，你可以安装这个 chart 两次。每次安装对应一个 release，每个 release 都有对应的名称。 伴随这几个概念，我们现在可以这样解释 Helm： > Helm 安装 charts 到 Kubernetes 中，每次安装创建一个新的 release。如果要找新的 charts，你可以通过搜索 Helm chart repositories。 ## 'HELM SEARCH': 搜索 CHARTS Helm 拥有强大的搜索命名，它可以搜索两种不同类型的源： * `helm search hub` 搜索 [the Helm Hub](https://hub.helm.sh/)，其中包括来自数十个不同 helm charts repositories * `helm search repo` 搜索本地 helm client 添加过的 repositories。该搜索是通过本地数据库完成的，不需要访问公网连接。 你可以通过运行 `helm search hub` 发现公共可用的 charts： ``` $ helm search hub wordpress URL CHART VERSION APP VERSION DESCRIPTION https://hub.helm.sh/charts/bitnami/wordpress 7.6.7 5.2.4 Web publishing platform for building blogs and ... https://hub.helm.sh/charts/presslabs/wordpress-... v0.6.3 v0.6.3 Presslabs WordPress Operator Helm Chart https://hub.helm.sh/charts/presslabs/wordpress-... v0.7.1 v0.7.1 A Helm chart for deploying a WordPress site on ... ``` 以上列出了在 Helm Hub 上所有 `wordpress` charts。 在没有过滤的情况下，`helm search hub` 会展示所有可用的 charts。 使用 `helm search repo`，你可以在已经添加过的 repositories 中找到 charts 的名称： ``` $ helm repo add brigade https://brigadecore.github.io/charts "brigade" has been added to your repositories $ helm search repo brigade NAME CHART VERSION APP VERSION DESCRIPTION brigade/brigade 1.3.2 v1.2.1 Brigade provides event-driven scripting of Kube... brigade/brigade-github-app 0.4.1 v0.2.1 The Brigade GitHub App, an advanced gateway for... brigade/brigade-github-oauth 0.2.0 v0.20.0 The legacy OAuth GitHub Gateway for Brigade brigade/brigade-k8s-gateway 0.1.0 A Helm chart for Kubernetes brigade/brigade-project 1.0.0 v1.0.0 Create a Brigade project brigade/kashti 0.4.0 v0.4.0 A Helm chart for Kubernetes ``` Helm 搜索使用模糊字匹配算法，因此你可以输入单词或者短语的一部分： ``` $ helm search repo kash NAME CHART VERSION APP VERSION DESCRIPTION brigade/kashti 0.4.0 v0.4.0 A Helm chart for Kubernetes ``` 搜索是一种发现可用包的好方法，当你寻找到想要安装的包后，你可以使用 `helm install` 来安装它。 ## 'HELM INSTALL'：安装一个包 使用 `helm install` 命令来安装一个新包。简单来说，它包含两个参数：你选择的 release 名称和你需要安装 chart 的名称。 ``` $ helm install happy-panda stable/mariadb ``` 当前 `mariadb` chart 已经安装了。注意安装一个 chart 创建了一个新的 `release` object。release 名称是 `happy-panda`。（如果你想让 Helm 生成随机名称，删除自定义名并添加 `--generate-name` 选项。） 在安装过程中，`helm` 客户端会打印出有用的信息，包括什么资源被创建了，release 的状态信息，以及一些需要你介入的附加配置项。 Helm 不会等所有的资源都运行后才推出。许多 charts 需要超过 600M 大小的镜像，并且需要很长时间才能安装到集群。 为了跟踪 release 的状态，或者重新读取配置信息，你可以使用 `helm status`: ``` $ helm status happy-panda Last Deployed: Wed Sep 28 12:32:28 2016 Namespace: default Status: DEPLOYED ... ``` 以上展示了你的 release 当前的状态。 ### 安装前自定义 Chart 刚刚安装的方式，只是使用 chart 的默认选项。很多时候，你需要自定义 chart 为你的首选配置。 可以通过 `helm show values` 查看一个 chart 的配置项： ``` $ helm show values stable/mariadb ``` 你可以覆盖 YAML 格式文件中的任意配置，在安装的时候传递到文件中。 ``` $ echo '{mariadbUser: user0, mariadbDatabase: user0db}' > config.yaml $ helm install -f config.yaml stable/mariadb --generate-name ``` 上面将会创建一个默认的 MariaDB 用户 `user0`，并把该用户赋权给新创建的 `user0db` 数据库，其他项都是用 chart 的默认值。 这里有两个方式在安装时传递配置数据： * `--values` （或者 `-f`）：指定替换的 YAML 文件。可多次指定选项，最右边的文件优先 * `--set`：命令行上指定替代 如果同时使用，`--set` 值会以更高的优先级合并到 `--values` 中。通过 `--set` 覆盖值将保存在 ConfigMap 中。给定 release `--set` 的值可以通过 `helm get values ` 查看。`--set` 设置的值可以通过运行 `helm upgrade` 指定 `--reset-values` 来清理。 ### `--set` 格式和限制 `--set` 选项采用零个或多个 name/value 对。最简单的用法是： `--set name=value`。相当于 YAML： ``` name: value ``` 多个值通过 `,` 分隔，因此 `--set a=b,c=d` 等价于： ``` a: b c: d ``` 复杂的表达式也支持。如，`--set outer.inner=value` 被翻译成： ``` outer: inner: value ``` 可以通过 `{` 和 `}` 来表示列表。如，`--set name={a, b, c}` 翻译成： ``` name: - a - b - c ``` 从 Helm 2.5.0 开始，可以使用数组索引语法访问列表项。如，`--set servers[0].port=80`： ``` servers: - port: 80 ``` `--set servers[0].port=80,servers[0].host=example` 设置多个值： ``` servers: - port: 80 host: example ``` 有时候你需要在 `--set` 上使用特殊的字符。你可以通过 `\` 转义，`--set name=value1\,value2`： ``` name: "value1,value2" ``` 同样，你可以转义点序列，这会给使用 `toYaml` 函数解析 annotations，labels 和 node selectors 时带来便利。`--set nodeSelector."kubernetes\.io/role"=master`： ``` nodeSelector: kubernetes.io/role: master ``` 使用 `--set` 很难表达深层嵌套的数据结构。鼓励 Chart 设计人员在设计 `values.yaml` 文件的时候考虑 `--set` 用法。 ### 更多安装的方法 `helm install` 命令可以从多个源安装： * chart repository（和上面提到的一样） * 本地 chart 归档（`helm install foo foo-0.1.1.tgz`） * 解包的 chart 目录（`helm install foopath/to/foo`） * 完整的 URL（`helm install foo https://example.com/charts/foo-1.2.3.tgz`） ## 'HELM UPGRADE' 和 'HELM ROLLBACK': 升级和失败恢复 RELEASE 当 chart 的新版本发布了，或者当你想修改你的 release 的时候，你可以使用 `helm upgrade` 命令。 升级针对当前存在的 release 通过你提供的信息升级。因为 Kubernetes charts 可能很大并且复杂，因此 Helm 尝试执行侵入性最小的升级。它将只更新自上一个 release 以来已经变更的内容。 ``` $ helm upgrade -f panda.yaml happy-panda stable/mariadb Fetched stable/mariadb-0.3.0.tgz to /Users/mattbutcher/Code/Go/src/helm.sh/helm/mariadb-0.3.0.tgz happy-panda has been upgraded. Happy Helming! Last Deployed: Wed Sep 28 12:47:54 2016 Namespace: default Status: DEPLOYED ... ``` 上面的例子，`happy-panda` release 通过新的 YAML 文件，使用同一个 chart 升级： ``` mariadbUser: user1 ``` 我们可以使用 `helm get values` 查看新的设置是否生效。 ``` $ helm get values happy-panda mariadbUser: user1 ``` `helm get` 命令是集群中获取 release 的非常有用的工具。从上面我们可以看到，它展示了已经部署到集群的 `panda.yaml` 新的值。 现在，如果当一个 release 没有按照计划的方式运行，通过 `helm rollback [RELEASE] [REVISION]` 可以很容易回滚到之前的版本。 ``` $ helm rollback happy-panda 1 ``` 上面回滚我们的 happy-panda 到它的第一个 release 版本。release 版本是一个递增的修订。每一次安装，升级或者回滚发生时，修订号递增 1。第一个修订号总是 1。我们可以通过 `helm history [RELEASE]` 查看某个 release 修订号 ## INSTALL/UPGRADE/ROLLBACK 帮助项 这里有几个其他有用的选项，以便当使用 Helm 执行 install/upgrade/rollback 时自定义操作。请注意这不是一个完整的客户端参数。查看所有参数的描述，运行 `helm --help`。 * `--timeout`：指定等待 Kubernetes 命令完成时间，默认 5m0s * `--wait`：等待直到所有的 Pods 处于 Ready 状态，PVCs bound，Deployments 达到最低限度（Desired - maxUnavailable）的 Pods 处于 Ready 状态以及 Service 有一个 IP 地址（并且 Ingress 如果需要 `LoadBalancer`）时，才标记 release 成功。等待的时间受 `--timeout` 值限制。如果超时了，则 release 会被标记为 `FAILED`。注意：在 Deployment `replicas` 设置为 1，滚动更新策略 `maxUnavailable` 没有被设置为 0 时，`--wait` 会返回 ready，因为它已经满足 ready 条件中的最小 Pod 数。 * `--no-hooks`：跳过执行钩子 ## 'HELM UNINSTALL'：卸载一个 RELEASE 通过 `helm uninstall` 命令从集群卸载 release： ``` $ helm uninstall happy-panda ``` 这将从集群中移除 release，你可以通过 `helm list` 命令列出当前所有已经部署的 releases： ``` $ helm list NAME VERSION UPDATED STATUS CHART inky-cat 1 Wed Sep 28 12:59:46 2016 ``` 从上面的输出，你可以看到 `happy-panda` release 已经卸载了。 在之前的 Helm 版本中，当一个 release 已经被删除了，它的删除记录会被保留。Helm3 中，删除 release 也会删除其记录。如果你想保留删除 release 的记录，使用 `helm uninstall --keep-history`。使用 `helm list --uninstalled` 只展示卸载是使用 `--keep-history` 参数的 releases。 `helm list --all` 参数会展示 Helm 保留的所有 release 记录，包括失败的或者删除项（如果 `--keep-history` 指定了）： ``` $ helm list --all NAME VERSION UPDATED STATUS CHART happy-panda 2 Wed Sep 28 12:47:54 2016 UNINSTALLED mariadb-0.3.0 inky-cat 1 Wed Sep 28 12:59:46 2016 DEPLOYED alpine-0.1.0 kindred-angelf 2 Tue Sep 27 16:16:10 2016 ``` 注意因为当前默认 releases 删除了，针对已卸载的资源是不能再回滚的。 ## 'HELM REPO' Helm3 不再附带默认的 chart 仓库了。`helm repo` 命令集提供添加，列表和移除仓库。 你可以通过 `helm repo list` 查看配置了哪些仓库： ``` $ helm repo list NAME URL stable https://kubernetes-charts.storage.googleapis.com mumoshu https://mumoshu.github.io/charts ``` 新的仓库可以通过 `helm repo add` 添加： ``` $ helm repo add dev https://example.com/dev-charts ``` 因为 chart 仓库变化比较频繁，可以通过 `helm repo update` 确保 Helm 客户端更新到最新版本。 仓库可以通过 `helm repo remove` 移除。 ## 创建你自己的 CHARTS [Chart Development Guide](https://helm.sh/docs/topics/charts/) 说明了如何开发你自己的 charts。但是你可以通过 `helm create` 命令快速入门： ``` $ helm create deis-workflow Creating deis-workflow ``` 现在在 `./deis-workflow` 有一个 chart。你可以编辑和创建属于你自己的模板。 在编辑 chart 时，可以通过运行 `helm lint` 验证格式是否正确。 当需要打包 chart 以进行分发时，可以运行 `helm package` 命令： ``` $ helm package deis-workflow deis-workflow-0.1.0.tgz ``` 然后现在就可以通过 `helm install` 轻松安装了： ``` $ helm install deis-workflow ./deis-workflow-0.1.0.tgz ... ``` 打包的 Charts 可以加载到 chart 仓库。具体参见你的 chart 仓库服务器以学习怎么上传。 注意：`stable` 仓库管理在 [Kubernetes Charts GitHub repository](https://github.com/helm/charts)。这个项目接受 chart 源码，并（审核后）为你打包。 ## 结束 这个章节覆盖了 `helm` 客户端基本的使用方式，包括搜索，安装，升级和卸载。它还覆盖了类似 `helm status`，`helm get` 以及 `helm repo` 这样的实用命令。 获取更多的信息，可以通过 `helm help` 获取 Helm 内建的帮助。