chartpress

Chartpress 自动化基本的 Helm 图表开发工作。它在 JupyterHub 和 BinderHub Helm 图表的开发中紧密使用。

特性

Chartpress 在一些配置的帮助下可以执行以下操作。

• 适当更新 Chart.yaml 的版本
• 构建 Docker 镜像并适当地标记它们
• 将构建的镜像推送到 Docker 镜像仓库
• 更新 values.yaml 以引用构建的镜像
• 基于 GitHub 页面发布图表到 Helm 图表仓库
• 重置 Chart.yaml 和 values.yaml 的更改

图表版本和镜像标签的确定方式

Chartpress 将使用一些关键信息推断图表版本和镜像标签。

1. tag：如果没有直接使用 --tag 设置，它将根据 git describe 确定的 当前分支 中最近标记的提交进行推断，或者如果没有提交被标记，则设置为 0.0.1。
   1. 如果 tag 以 v 开头但其他方面是有效的 SemVer2 版本，则 v 将在将其设置为 Helm 3 要求 Helm 图表版本必须符合 SemVer2 规范之前从 Chart.yaml 中删除。
2. 自 tag 以来修改 相关路径 内容的最新提交。
   1. n：自分支上最新标记提交以来的提交数，作为整数。
   2. hash：最新提交的缩写哈希值，通常是 7-8 个字符，前面加 h。
3. 如果 tag（如 0.10.0 或 0.10.0-beta.1）包含 -，则使用 tag.git.n.hash 格式，否则使用 tag-0.dev.git.n.hash 格式。
4. 如果指定了 --long 或未指定。如果指定了 --long，则带有 .git.n.hash 部分的标记提交始终会以类似 1.0.0-0.dev.git.0.habcd123 的方式写出。

当生成开发版本（在末尾带有 .git.n.hash）时，基本版本 可以来自配置中的两个位置之一。有关更多信息，请参阅 控制 chart.yaml 中的开发版本。

示例图表版本和镜像标签

这是一个按时间顺序排列的、可能来自使用 chartpress 的真实图表版本和/或镜像标签的列表。

0.8.0
0.8.0-0.dev.git.4.hasdf123
0.8.0-0.dev.git.10.hsdfg234
0.9.0-beta.1
0.9.0-beta.1.git.12.hdfgh345
0.9.0-beta.1.git.15.hfghj456
0.9.0-beta.2
0.9.0-beta.2.git.20.hghjk567
0.9.0-beta.3
0.9.0

要求

以下二进制文件必须在您的 PATH 中

• git
• docker
• helm

如果您要将图表发布到 GitHub Pages，则在目标仓库中创建一个 gh-pages 分支。

安装

pip install chartpress

用法

在包含 chartpress.yaml 的目录中运行

chartpress

以构建您的图表和镜像。添加 --push 以将镜像发布到 Docker Hub，并添加 --publish-chart 以发布图表和索引到 gh-pages。

usage: chartpress [-h] [--push] [--force-push] [--publish-chart]
                  [--force-publish-chart] [--extra-message EXTRA_MESSAGE]
                  [--tag TAG | --long] [--image-prefix IMAGE_PREFIX] [--reset]
                  [--no-build | --force-build]
                  [--builder {docker-build,docker-buildx}]
                  [--platform PLATFORM] [--list-images] [--version]

Automate building and publishing helm charts and associated images. This is
used as part of the JupyterHub and Binder projects.

optional arguments:
  -h, --help            show this help message and exit
  --push                Push built images to their image registries, but not
                        if it would replace an existing image.
  --force-push          Push built images to their image registries,
                        regardless if it would replace an existing image.
  --publish-chart       Package a Helm chart and publish it to a Helm chart
                        registry constructed with a GitHub git repository and
                        GitHub pages, but not if it would replace an existing
                        chart version.
  --force-publish-chart
                        Package a Helm chart and publish it to a Helm chart
                        registry constructed with a GitHub git repository and
                        GitHub pages, regardless if it would replace an
                        existing chart version
  --extra-message EXTRA_MESSAGE
                        Extra message to add to the commit message when
                        publishing charts.
  --tag TAG             Explicitly set the image tags and chart version.
  --long                Use this to always get a build suffix for the
                        generated tag and chart version, even when the
                        specific commit has a tag.
  --image-prefix IMAGE_PREFIX
                        Override the configured image prefix with this value.
  --reset               Skip image build step and reset Chart.yaml's version
                        field and values.yaml's image tags. What it resets to
                        can be configured in chartpress.yaml with the resetTag
                        and resetVersion configurations.
  --no-build, --skip-build
                        Skip the image build step.
  --force-build         Enforce the image build step, regardless of if the
                        image already is available either locally or remotely.
  --builder {docker-build,docker-buildx}
                        Container build engine to use, docker-build is the
                        standard Docker build command.
  --platform PLATFORM   Build the image for this platform, e.g. linux/amd64 or
                        linux/arm64. This argument can be used multiple times
                        to build multiple platforms under the same tag. Only
                        supported for docker buildx. If --push is set or if
                        multiple platforms are passed the image will not be
                        loaded into the local docker engine.
  --list-images         print list of images to stdout. Images will not be
                        built.
  --version             show program's version number and exit

配置

chartpress.yaml 文件包含对每个图表要构建的图表和镜像的规范。以下是一个示例 chartpress.yaml 文件。

charts:
  # list of charts by name
  # each name should be the name of a Helm chart
  - name: binderhub
    # Directory containing the chart, relative to chartpress.yaml.
    # Can be omitted if the directory is the same as the chart name.
    chartPath: helm-charts/binderhub

    # the prefix to use for built images
    imagePrefix: jupyterhub/k8s-
    # tag to use when resetting the chart values
    # with the --reset flag. It defaults to "set-by-chartpress".
    resetTag: latest
    # version to use when resetting the Chart.yaml's version field with the
    # --reset flag. It defaults to "0.0.1-set.by.chartpress". This is a valid
    # SemVer 2 version, which is required for a helm lint command to succeed.
    resetVersion: 1.2.3-dev

    # baseVersion sets the base version for development tags,
    # instead of using the latest tag from `git describe`.
    # This gives you more control over development version tags
    # and lets you ensure prerelease tags are always sorted in the right order.
    # Only useful when publishing development releases.
    # Recommended together with a version-bumping tool like `tbump`.
    # if baseVersion is not a prerelease version (no -suffix),
    # the suffix `-0.dev` will be appended.
    #
    # Alternatively baseVersion can be set to "major", "minor", or "patch", then
    # baseVersion will be calculated based on the latest version tag from `git
    # describe`, but have its "major", "minor", or "patch" version increment if
    # the version isn't a pre-release.
    baseVersion: 3.2.1-0.dev

    # The git repo whose gh-pages contains the charts. This can be a local
    # path such as "." as well but if matching <organization>/<repo> will be
    # assumed to be a separate GitHub repository.
    repo:
      git: jupyterhub/helm-chart
      published: https://jupyterhub.github.io/helm-chart
    # Additional paths that when modified should lead to an updated Chart.yaml
    # version, other than the chart directory in <chart name> or any path that
    # influence the images of the chart. These paths should be set relative to
    # chartpress.yaml's directory.
    paths:
      - ../setup.py
      - ../binderhub
    # images to build for this chart (optional)
    images:
      binderhub:
        # imageName overrides the default name of the image. The default name
        # is the imagePrefix augmented with the key of this configuration. It
        # would be jupyterhub/k8s-binderhub in this case.
        imageName: jupyterhub/k8s-custom-image-name
        # Build arguments to be passed using docker's --build-arg flag as
        # --build-arg <key>=<value>. TAG and LAST_COMMIT are expandable.
        buildArgs:
          MY_STATIC_BUILD_ARG: "hello world"
          MY_DYNAMIC_BUILD_ARG: "{TAG}-{LAST_COMMIT}"
        # Build options to be passed to the docker build command. Pass a list
        # of strings to be appended to the end of the build command. These are
        # passed directly to the command line, so prepend each option with "--"
        # like in the examples below. TAG and LAST_COMMIT are expandable.
        extraBuildCommandOptions:
          - --label=maintainer=octocat
          - --label=ref={TAG}-{LAST_COMMIT}
          - --rm
        # contextPath is the path to the directory that is to be considered the
        # current working directory during the build process of the Dockerfile.
        # This is by default the folder of the Dockerfile. This path should be
        # set relative to chartpress.yaml.
        contextPath: ..
        # By default, changes to the contextPath will make chartpress rebuild
        # the image, but this option make that configurable.
        rebuildOnContextPathChanges: false
        # Path to the Dockerfile, relative to chartpress.yaml. Defaults to
        # "images/<image name>/Dockerfile".
        dockerfilePath: images/binderhub/Dockerfile
        # Path(s) in <chart name>/values.yaml to be updated with image name and
        # tag.
        valuesPath:
          - singleuser.image
          - singleuser.profileList.0.kubespawner_override.image
        # Additional paths, relative to chartpress.yaml's directory, that should
        # be used to indicate that a new tag of the image is required, aside
        # from the contextPath and dockerfilePath for building the image itself.
        paths:
          - assets
        # If chartpress is used to build images for multiple architectures but
        # not all of those architectures are supported by an image they can be
        # skipped
        skipPlatforms:
          - linux/arm64

控制开发版本

类似于一些“版本控制中的软件包版本”工具，在 chartpress 中，您不需要管理版本，只需要通过标记提交。

然而，仅依赖于标记会导致“开发版本”（发布自发布之后的提交）的预发布版本有些令人困惑。

发布例如 1.2.3 之后，下一个版本将是 1.2.3-0.dev.git.10.habc。根据语义版本控制，这是一个“预发布版”（很好，它应该从默认安装中排除），但这意味着它来自 之前 1.2.3（错误！它是比 1.2.3 新的 1 个提交）。这是因为预发布版应该相对于 下一个 发布版来定义，而不是相对于 上一个 发布版。但是 git 标签只存储 上一个 发布版！

Chartpress 2.0 添加了一个选项 chart.baseVersion，允许明确设置开发标签的基本版本，而不是使用通过 git describe 找到的最后一个标签的版本。

这种方式的主要好处是

1. 确保已发布的预发布版本按照正确的顺序显示，并且
2. 让您控制预发布图表的版本（是2.0.0-0.dev还是1.3.1-0.dev？）

而不是发布以下序列

• 1.2.3
• 1.2.3-0.dev.git.10.habc（晚于1.2.3，但排序在1.2.3之前！）

您可以发布

• 1.2.3
• 1.3.0-0.dev.git.10.habc（基于下一个版本的预发布，而不是上一个版本）

其中chartpress将使用您的baseVersion配置中的版本作为基础版本，而不是分支上的最后一个标签。

这需要一些额外的配置，以及您发布过程中的步骤

1. 您必须在您的chartpress.yaml中将baseVersion: 1.2.3-0.dev设置为您的下一个预发布版本

   charts:
     - name: mychart
       baseVersion: 1.2.3-0.dev
   

2. 您必须更新baseVersion，特别是在发布后。我们建议使用版本升级工具，如tbump，以保持您的baseVersion配置和git标签同步。

发布过程通常如下所示

V=1.2.3
# tbump updates version, commits changes, tags commit, pushes branch and tag
tbump "$V"

# back to development
NEXT_V=1.2.4-0.dev
# bump version config, but no tag for starting development
tbump --no-tag "${NEXT_V}"

任何预发布字段（如上面的-0.dev或-alpha.1）将保持不变，并添加.git.n.hash后缀。如果没有预发布（例如，在标记发布的确切提交上），则将在基础版本上添加-0.dev。您必须在发布后更新baseVersion，否则chartpress --reset将因版本排序错误而失败。

tbump配置文件的示例可以在我们的测试中找到。

注意事项

浅克隆

Chartpress在确定用于图表和图像的版本和标签时，会检测到更改目录或文件的最新提交。这意味着不应使用浅克隆，因为如果更改相关文件的最后一个提交在浅克隆提交范围之外，将被分配错误的图表版本和图像标签。

避免GitHub Actions中的浅克隆

GitHub Workflow常用GitHub Action actions/checkout默认克隆深度为1，将其配置为进行完整克隆。

steps:
  - uses: actions/checkout@v2
    with:
      # chartpress need the git branch's tags and commits
      fetch-depth: 0

命令缓存

Chartpress缓存了一些命令的结果以改进性能。这意味着不应将chartpress用作可导入的库。

开发

可以使用pytest进行此Python包的测试。有关测试的更多详细信息，请参阅tests/README.md。

# install chartpress locally
pip install  -e .

# install dev dependencies
pip install -r dev-requirements.txt

# format and lint code
pre-commit run -a

# run tests
pytest --verbose --exitfirst
# some tests push to a local registry, you can skip these
pytest --verbose --exitfirst -m 'not registry'