告别手寫，一鍵生成 Helm Chart README

前言

随着雲原生應用的普及，Helm 的作用也日益凸顯，越來越多的雲原生應用以 Helm Chart 的形式釋出，可以說現在如果沒有一個 Helm Chart 都不好意思說自己是雲原生應用。

一個好的應用必定有一套好的文檔，文檔的品質往往和代碼的品質成正比。而 Helm Chart 中的

README.md

檔案就承擔了文檔的作用，該檔案會介紹這個 Helm Chart 的基本資訊、使用方式以及參數配置等，使用者可以通過該文檔的指引，配置符合自己需求的參數，最終完成雲原生應用的部署。

但這也給雲原生應用的開發者提出了挑戰，開發者不但需要把

value.yaml

和

Chart.yaml

等檔案的參數以 Markdown 的形式搬運到

README.md

檔案中，同時還要将參數的預設值，以及介紹填入表格中。但如果參數出現了變動，往往無法及時更新文檔。這就導緻了使用者明明根據文檔配置了參數，但是部署的效果就是無法達到預期。

Helm-docs

helm-docs 可以根據 charts 内容自動生成 markdown 檔案。該檔案會包含有關 charts 的中繼資料，以及

value.yaml

中的參數，同時還可以引用子模闆（預設為

README.md.gotmpl

），進一步定制生成的内容。

安裝

helm-docs

使用 golang 開發，支援多平台：

MacOS

可以使用 homebrew 安裝：

brew install norwoodj/tap/helm-docs           

下載下傳可執行檔案

到

release

頁面下載下傳對應平台的可執行檔案。

快速開始

直接使用可執行檔案

使用方法也很簡單，直接進入到 Chart 所在目錄，執行指令：

helm-docs
# 或者
helm-docs --dry-run # 不生成 README.md 檔案，而是将生成的内容列印到控制台           

使用 docker

如果不想安裝可執行檔案，也可以使用 docker，将 Chart 目錄挂載到 docker 鏡像中，實作相同的效果：

docker run -v "$(pwd):/helm-docs" jnorwood/helm-docs:latest
# 或者
docker run -v "$(pwd):/helm-docs" jnorwood/helm-docs:latest --dry-run           

進階實踐

下面就以我的開源項目

cms-grafana-builder

為例，講解 helm-docs 的一些進階使用。

添加參數說明

helm-docs 可以通過

value.yaml

中的注釋生成參數說明，注釋格式如下所示，

--

後的内容會自動填充到 Chart Values 的 Description 中：

# access_key_id -- Aliyun Access Key Id.
access_key_id: ""
# access_secret -- Aliyun Access Secret.
access_secret: ""
# region_id -- Aliyun Region Id.
region_id: "cn-shanghai"
# password -- Grafana admin password.
password: "admin"

image:
  # image.repository -- Image source repository name.
  repository: grafana/grafana
  # image.pullPolicy -- Image pull policy.
  pullPolicy: IfNotPresent           

自定義模闆

可以建立

README.md.gotmpl

模闆來進一步定制

README.md

的輸出樣式。

README.md.gotmpl

檔案的内容如下，可以在模闆中插入 Markdown 來充實

README.md

的内容，以及改變展示内容的順序：

{{ template "chart.header" . }}
{{ template "chart.description" . }}

{{ template "chart.versionLine" . }}

{{ template "chart.sourceLinkLine" . }}

## Introduction

This chart helps you run a grafana server that include aliyun cms dashboard.


{{ template "chart.requirementsSection" . }}

{{ template "chart.valuesSection" . }}           

總結

helm-docs 可以幫助很多像我這樣需要維護多個 Helm Chart 的開發者，在更新完或建立 Chart 以後，使用

helm-docs

來自動生成

README.md

檔案，無需逐個尋找和修改，甚至将其內建到 CI 流水線中，自動生成最新的

README.md

，保證文檔和代碼的一緻。

更多内容和示例，詳見

https://github.com/norwoodj/helm-docs