Merge pull request #2936 from buildkite/PKG-6375-helm-docs

[PKG-6375] Helm docs (standard and includes OCI based)

data/nav.yml

@@ -487,6 +487,13 @@
           path: "packages/debian"
         - name: "Files"
           path: "packages/files"
+        - name: "Helm"
+          start_expanded: true
+          children:
+            - name: "OCI-based"
+              path: "packages/helm-oci"
+            - name: "Standard"
+              path: "packages/helm"
         - name: "Java"
           start_expanded: true
           children:

pages/packages.md

@@ -27,6 +27,8 @@ If you're familiar with the basics, explore how to use registries for each of Bu
   <%= button ":alpine: Alpine (apk)", "/docs/packages/alpine" %>
   <%= button ":docker: Container (Docker)", "/docs/packages/container" %>
   <%= button ":debian: Debian/Ubuntu (deb)", "/docs/packages/debian" %>
+  <%= button ":helm: Helm (OCI)", "/docs/packages/helm-oci" %>
+  <%= button ":helm: Helm", "/docs/packages/helm" %>
   <%= button ":maven: Java (Maven)", "/docs/packages/maven" %>
   <%= button ":gradle: Java (Gradle)", "/docs/packages/gradle" %>
   <%= button ":node: JavaScript (npm)", "/docs/packages/javascript" %>

pages/packages/_helm_registry_slug.md

@@ -0,0 +1 @@
+- `{registry.slug}` is the slug of your Helm registry, which is the [kebab-case](https://en.wikipedia.org/wiki/Letter_case#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.

pages/packages/container.md

@@ -8,7 +8,7 @@ To view and copy these `docker` commands:
 
 1. Select **Packages** in the global navigation to access the **Registries** page.
 1. Select your container registry on this page.
-1. Select **Publish a Container Package** and in the resulting dialog, for each required `docker` command set in the relevant code snippets, copy the relevant code snippet (using the icon at the top-right of its code box), paste it into your terminal, and run it.
+1. Select **Publish a Container Image** and in the resulting dialog, for each required `docker` command set in the relevant code snippets, copy the relevant code snippet (using the icon at the top-right of its code box), paste it into your terminal, and run it.
 
 These Docker commands are used to:
 
@@ -27,7 +27,7 @@ The following steps describe the process above:
     ```
 
     where:
-    * `registry-write-token` is your [API access token](https://buildkite.com/user/api-access-tokens) used to publish/upload packages to your container registry. Ensure this access token has the **Write Packages** REST API scope, which allows this token to publish packages to any registry your user account has access to within your Buildkite organization.
+    * `registry-write-token` is your [API access token](https://buildkite.com/user/api-access-tokens) used to publish/upload packages to your container registry. Ensure this access token has the **Read Packages** and **Write Packages** REST API scopes, which allows this token to publish packages to any registry your user account has access to within your Buildkite organization.
 
     <%= render_markdown partial: 'packages/org_slug' %>
     <%= render_markdown partial: 'packages/container_registry_slug' %>

pages/packages/helm.md

@@ -0,0 +1,116 @@
+# Helm
+
+Buildkite Packages 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](/docs/packages/helm-oci).
+
+Once your Helm registry has been [created](/docs/packages/manage-registries#create-a-registry), 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.
+1. Select your Helm registry on this page.
+1. 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.
+
+## Publishing 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:
+
+```bash
+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:
+
+<%= render_markdown partial: 'packages/org_slug' %>
+
+<%= render_markdown partial: 'packages/helm_registry_slug' %>
+
+<%= render_markdown partial: 'packages/path_to_file' %>
+
+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:
+
+```bash
+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 "[email protected]"
+```
+
+## 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.
+1. Select your Helm  registry on this page.
+1. 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](#access-a-charts-details-downloading-a-chart).
+- **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](#access-a-charts-details).
+1. Select **Download**.
+
+#### Registry configuration
+
+If your registry is _private_ (that is, the default registry configuration), configure your Helm registry locally for repeated use:
+
+```bash
+helm repo add {registry.slug} https://packages.buildkite.com/{org.slug}/{registry.slug}/helm \
+    --username buildkite \
+    --password registry-read-token
+```
+
+where:
+
+<%= render_markdown partial: 'packages/org_slug' %>
+
+<%= render_markdown partial: 'packages/helm_registry_slug' %>
+
+- `registry-read-token` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/packages/manage-registries#update-a-registry-configure-registry-tokens) 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:
+
+```bash
+helm install "chart-release" "{registry.slug}/{chart-name}" --version {version}
+```
+
+where:
+
+<%= render_markdown partial: 'packages/helm_registry_slug' %>
+
+- `chart-release` is the unique release name for the Helm chart - must have no `.` in name and be in lowercase. [General conventions](https://helm.sh/docs/chart_best_practices/conventions/#chart-names).
+
+- `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.

pages/packages/helm_oci.md

@@ -0,0 +1,119 @@
+# Helm OCI
+
+Buildkite Packages provides Helm OCI based registry support for distributing Helm charts. Note, this requires [Helm version 3.8.0](https://helm.sh/docs/topics/registries/) or newer.
+
+Once your Helm OCI registry has been [created](/docs/packages/manage-registries#create-a-registry), you can publish/upload charts (generated from your application's build) to this registry via relevant `helm` commands presented on your registry's details page.
+
+To view and copy these `helm` commands:
+
+1. Select **Packages** in the global navigation to access the **Registries** page.
+1. Select your Helm OCI registry on this page.
+1. Select **Publish a Helm Chart** and in the resulting dialog, for each required `helm` command set in the relevant code snippets, copy the relevant code snippet (using the icon at the top-right of its code box), paste it into your terminal, and run it.
+
+These Helm commands are used to:
+
+- Log in to your Buildkite Helm OCI registry with an API access token.
+- Publish a Helm chart to your registry.
+
+## Publishing a chart
+
+The following steps describe the process above:
+
+1. Copy the following `helm login` command, paste it into your terminal, and modify as required before running to log in to your registry:
+
+    ```bash
+    helm registry login packages.buildkite.com/{org.slug}/{registry.slug} -u buildkite -p registry-write-token
+    ```
+
+    where:
+    * `registry-write-token` is your [API access token](https://buildkite.com/user/api-access-tokens) used to publish/upload charts to your Helm registry. Ensure this access token has the **Read Packages** and **Write Packages** REST API scopes, which allows this token to publish packages to any registry your user account has access to within your Buildkite organization.
+
+    <%= render_markdown partial: 'packages/org_slug' %>
+    <%= render_markdown partial: 'packages/helm_registry_slug' %>
+
+1. Copy the following `helm push` command, paste it into your terminal, and modify as required before running to push your Helm chart:
+
+    ```bash
+    helm push {chart-filename.tgz} packages.buildkite.com/{org.slug}/{registry.slug}
+    ```
+
+    where `{chart-filename.tgz}` is the filename of the chart you wish to push.
+
+## 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.
+1. Select your Helm  registry on this page.
+1. 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](#access-a-charts-details-downloading-a-chart).
+- **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's manifest
+
+The charts OCI manifest can be downloaded from the details page. To do this:
+
+1. [Access the chart's details](#access-a-charts-details).
+1. Select **Download**.
+
+### Downloading a chart
+
+A Helm chart can be obtained using code snippet details provided on the chart's details page. To do this:
+
+1. [Access the chart's details](#access-a-charts-details).
+1. Ensure the **Installation** > **Instructions** section is displayed.
+1. For each required command in the relevant code snippets, copy the relevant code snippet, paste it into your terminal, and run it.
+
+The following set of code snippets are descriptions of what each code snippet does and where applicable, its format:
+
+#### Registry configuration
+
+If your registry is _private_ (that is, the default registry configuration), log in to the Helm registry containing the chart to obtain with the following `helm login` command:
+
+```bash
+helm registry login packages.buildkite.com/{org.slug}/{registry.slug} -u buildkite -p registry-read-token
+```
+
+where:
+
+<%= render_markdown partial: 'packages/org_slug' %>
+
+<%= render_markdown partial: 'packages/helm_registry_slug' %>
+
+- `registry-read-token` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/packages/manage-registries#update-a-registry-configure-registry-tokens) 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 download
+
+Use the following `helm pull` command to download the chart:
+
+```bash
+helm pull oci://packages.buildkite.com/{org.slug}/{registry.slug}/chart-name --version {version}
+```
+
+where:
+
+<%= render_markdown partial: 'packages/org_slug' %>
+
+<%= render_markdown partial: 'packages/helm_registry_slug' %>
+
+- `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.

pages/packages/manage_registries.md

@@ -29,6 +29,7 @@ Once a [registry is created](#create-a-registry), packages can then be uploaded
 - [Container (Docker)](/docs/packages/container) images
 - [Debian/Ubuntu (deb)](/docs/packages/debian)
 - [Files (generic)](/docs/packages/files)
+- Helm ([OCI](/docs/packages/helm-oci) or [Standard](/docs/packages/helm))
 - Java ([Maven](/docs/packages/maven) or [Gradle leveraging the Maven Publish Plugin](/docs/packages/gradle))
 - [JavaScript (npm)](/docs/packages/javascript)
 - [Python (PyPI)](/docs/packages/python)

vale/styles/vocab.txt

@@ -207,6 +207,7 @@ svg
 swiftformat
 systemd
 templated
+tgz
 timeframe
 tmp
 tmux