Helm

Buildkite Package Registries provides Helm registry support for distributing Helm charts.

This page is for standard Helm publishing instructions, alternatively you can also publish to an OCI-based registry.

Once your Helm registry has been created, you can publish/upload charts (generated from helm package to create the package) to this registry via the relevant curl command presented on your Helm registry's details page.

To view and copy this curl command:

  1. Select Packages in the global navigation to access the Registries page.
  2. Select your Helm registry on this page.
  3. Select Publish a Helm Chart and in the resulting dialog, use the copy icon at the top-right of the code box to copy this curl command and run it to publish your chart to your Helm registry.

This command provides:

  • The specific URL to publish a package to your specific Helm registry in Buildkite.
  • The API access token required to publish packages to your Helm registry.
  • The Helm package (.tgz) to be published.

Publish a chart

The following curl command (which you'll need to modify as required before submitting) describes the process above to publish a Helm chart to your Helm registry:

curl -X POST https://api.buildkite.com/v2/packages/organizations/{org.slug}/registries/{registry.slug}/packages \
  -H "Authorization: Bearer $REGISTRY_WRITE_TOKEN" \
  -F "file=@<path_to_file>"

where:

  • {org.slug} can be obtained from the end of your Buildkite URL, after accessing Packages or Pipelines in the global navigation of your organization in Buildkite.
  • {registry.slug} is the slug of your Helm registry, which is the kebab-case version of your Helm registry name, and can be obtained after accessing Packages in the global navigation > your Helm registry from the Registries page.
  • <path_to_file> is the full path required to the package file. If the file is located in the same directory that this command is running from, then no path is required.

For example, to upload the file my-helm-chart-0.1.2.tgz from the current directory to the My Helm Charts registry in the My organization Buildkite organization, run the curl command:

curl -X POST https://api.buildkite.com/v2/packages/organizations/my-organization/registries/my-helm-charts/packages \
  -H "Authorization: Bearer $REPLACE_WITH_YOUR_REGISTRY_WRITE_TOKEN" \
  -F "file=@my-helm-chart-0.1.2.tgz"

Access a chart's details

A Helm chart's details can be accessed from this registry using the Packages section of your Helm registry page.

To access your Helm chart's details page:

  1. Select Packages in the global navigation to access the Registries page.
  2. Select your Helm registry on this page.
  3. On your Helm registry page, select the chart to display its details page.

The chart's details page provides the following information in the following sections:

  • Installation (tab): the installation instructions.

  • Details: details about:

    • the name of the chart (typically the file name excluding any version details and extension).
    • the chart version.
    • the registry type the chart is located in.
    • the chart's visibility (based on its registry's visibility)—whether the chart is Private and requires authentication to access, or is publicly accessible.

  • Pushed: the date when the last chart was uploaded to the registry.

  • Package size: the storage size (in bytes) of this chart.

  • Downloads: the number of times this chart has been downloaded.

Downloading a chart

A Helm (tgz) package can be downloaded from the package's details page. To do this:

  1. Access the chart's details.
  2. Select Download.

Registry configuration

If your registry is private (that is, the default registry configuration), configure your Helm registry locally for repeated use:

helm repo add {registry.slug} https://packages.buildkite.com/{org.slug}/{registry.slug}/helm \
    --username buildkite \
    --password registry-read-token

where:

  • {org.slug} can be obtained from the end of your Buildkite URL, after accessing Packages or Pipelines in the global navigation of your organization in Buildkite.
  • {registry.slug} is the slug of your Helm registry, which is the kebab-case version of your Helm registry name, and can be obtained after accessing Packages in the global navigation > your Helm registry from the Registries page.
  • registry-read-token is your API access token or registry token used to download charts from your Helm registry. Ensure this access token has the Read Packages REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.

This step is not required for public Helm registries.

Chart installation

Use the following helm install command to download the chart:

helm install "chart-release" "{registry.slug}/{chart-name}" --version {version}

where:

  • {registry.slug} is the slug of your Helm registry, which is the kebab-case version of your Helm registry name, and can be obtained after accessing Packages in the global navigation > your Helm registry from the Registries page.

  • chart-release is the unique release name for the Helm chart - must have no . in name and be in lowercase. General conventions.

  • chart-name is the name of your chart.

  • version (optional) the version you wish to download. Without this flag it will download the latest version.