{"id":37182358,"url":"https://github.com/vmware-labs/distribution-tooling-for-helm","last_synced_at":"2026-04-01T19:44:58.344Z","repository":{"id":189929207,"uuid":"671151851","full_name":"vmware-labs/distribution-tooling-for-helm","owner":"vmware-labs","description":"Helm Distribution plugin is is a set of utilities and Helm Plugin for making offline work with Helm Charts easier. It is meant to be used for creating reproducible and relocatable packages for Helm Charts that can be moved around registries without hassles. This is particularly useful for distributing Helm Charts into airgapped environments.","archived":false,"fork":false,"pushed_at":"2026-03-17T15:22:08.000Z","size":2012,"stargazers_count":102,"open_issues_count":10,"forks_count":18,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-03-18T03:41:25.859Z","etag":null,"topics":["helm","helm-charts","helm-plugin","helm-plugins"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vmware-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING_CLA.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.MD","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-07-26T16:51:59.000Z","updated_at":"2026-03-17T15:01:35.000Z","dependencies_parsed_at":"2023-08-22T13:28:19.508Z","dependency_job_id":"5c915bd1-2303-42f6-b813-df0181da062c","html_url":"https://github.com/vmware-labs/distribution-tooling-for-helm","commit_stats":null,"previous_names":["vmware-labs/distribution-tooling-for-helm"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/vmware-labs/distribution-tooling-for-helm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-labs%2Fdistribution-tooling-for-helm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-labs%2Fdistribution-tooling-for-helm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-labs%2Fdistribution-tooling-for-helm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-labs%2Fdistribution-tooling-for-helm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vmware-labs","download_url":"https://codeload.github.com/vmware-labs/distribution-tooling-for-helm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-labs%2Fdistribution-tooling-for-helm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291206,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["helm","helm-charts","helm-plugin","helm-plugins"],"created_at":"2026-01-14T21:01:35.757Z","updated_at":"2026-04-01T19:44:58.317Z","avatar_url":"https://github.com/vmware-labs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Distribution Tooling for Helm\n\n`dt`, is a set of utilities available in a standalone mode and as a Helm Plugin for making offline work with Helm charts easier. It is meant to be used for creating reproducible and relocatable packages for Helm charts that can be easily moved across registries without hassles. This is particularly useful for distributing Helm charts into air-gapped environments like those used by Federal governments.\n\n\u003e [!IMPORTANT]  \n\u003e Starting in 2026, this project is licensed under a Broadcom license. For details, see the [_LICENSE_](https://raw.githubusercontent.com/vmware-labs/distribution-tooling-for-helm/refs/heads/main/LICENSE) file\n\n## TL;DR\n\nDistribute your Helm charts with two easy commands\n\n```console\n# Wrap\n$ helm dt wrap oci://docker.io/bitnamicharts/kibana\n  ...\n  🎉  Helm chart wrapped into \"/tmp/workspace/kibana/kibana-10.4.8.wrap.tgz\"\n\n# Unwrap\n$ helm dt unwrap kibana-10.4.8.wrap.tgz demo.goharbor.io/helm-plugin/ --yes\n  ...\n  🎉  Helm chart unwrapped successfully: You can use it now by running \"helm install oci://demo.goharbor.io/helm-plugin/kibana --generate-name\"\n```\n\n![Helm distribution tooling demo](demo.gif)\n\nThis tool builds on [HIP-15](https://github.com/helm/community/blob/main/hips/hip-0015.md) and the, currently proposed, [images lock file HIP (PR)](https://github.com/helm/community/pull/281) as a foundation. Hence, it does require Helm charts to contain an annotation that provides the full list of container images that a Helm chart might need for its usage independently of the bootstrapping configuration.\n\n[Bitnami Helm charts](https://github.com/bitnami/charts) are now fully annotated to support this tooling, but you can also use this set of utilities with any other Helm charts that might use any other alternative image listing annotation, like for example, Helm charts relying on [artifact.io/images](https://artifacthub.io/docs/topics/annotations/helm/).\n\n## Installation\n\n### Installing as a Helm plugin\n\nProvided you have [Helm](https://helm.sh) then you can install this tool as a plugin:\n\n```console\n$ helm plugin install https://github.com/vmware-labs/distribution-tooling-for-helm\n```\n\n\u003e **Note:** Windows installation\n\u003e\n\u003e If installing on Windows, the above command must be run in a bash emulator such as Git Bash.\n\n### Downloading and using standalone\n\nFetch the latest available release from the [Releases](https://github.com/vmware-labs/distribution-tooling-for-helm/releases) section.\n\nNote that all the examples below use this tool as a Helm plugin but you can just run it as standalone. Just remove the `helm` command from all those examples.\n\n### Building from Source\n\nYou can build this tool with the following command. Golang 1.20 or above is needed to compile. [golangci-lint](https://golangci-lint.run/usage/install/) is used for linting.\n\n```console\n$ make build\n```\n\nYou can also verify the build by running the unit tests:\n\n```console\n$ make test\n```\n\n## Basic Usage\n\nThe following sections list the most common commands and their usage. This tool can be used either standalone or through the Helm plugin.\n\nFor the sake of following this guide, let's pull one of the Bitnami Helm charts into an examples folder:\n\n```console\n$ git clone git@github.com:vmware-labs/distribution-tooling-for-helm.git\n$ cd distribution-tooling-for-helm\n$ bash -c \"mkdir examples \u0026 helm pull oci://docker.io/bitnamicharts/mariadb -d examples --untar\"\n```\n\nThe two simplest and most powerful commands on this tool are `wrap` and `unwrap`. With these two commands **you can relocate any Helm chart to any OCI registry in two steps**.\n\n### Wrapping Helm charts\n\nWrapping a chart consists of packaging the chart into a tar.gz, including all container images that this chart depends on, independently of values. Everything gets wrapped together into a single file. This will include also all the subcharts and their container images. That new file, the wrap, can be distributed around in whatever way you want (e.g. USB stick) to then later be unwrapped into a destination OCI registry. This process is commonly referred to as relocating a Helm chart.\n\nEven more exciting, we don't need to download the Helm chart for wrapping it. We can point the tool to any reachable Helm chart and the tool will take care of packaging and downloading everything for us. For example:\n\n```console\n$ helm dt wrap oci://docker.io/bitnamicharts/kibana\n »  Wrapping Helm chart \"oci://docker.io/bitnamicharts/kibana\"\n    ✔  Helm chart downloaded to \"/var/folders/mn/j41xvgsx7l90_hn0hlwj9p180000gp/T/chart-1177363375/chart-1516625348/kibana\"\n    ✔  Images.lock file \"/var/folders/mn/j41xvgsx7l90_hn0hlwj9p180000gp/T/chart-1177363375/chart-1516625348/kibana/Images.lock\" does not exist\n    ✔  Images.lock file written to \"/var/folders/mn/j41xvgsx7l90_hn0hlwj9p180000gp/T/chart-1177363375/chart-1516625348/kibana/Images.lock\"\n    »  Pulling images into \"/var/folders/mn/j41xvgsx7l90_hn0hlwj9p180000gp/T/chart-1177363375/chart-1516625348/kibana/images\"\n       ✔  All images pulled successfully\n    ✔  Helm chart wrapped to \"/tmp/workspace/kibana/kibana-10.4.8.wrap.tgz\"\n 🎉  Helm chart wrapped into \"/tmp/workspace/kibana/kibana-10.4.8.wrap.tgz\"\n```\n\nNote that depending on the number of images needed by the Helm chart (remember, a wrap has the full set of image dependencies, not only the ones set on _values.yaml_) the size of the generated wrap might be considerably large:\n\n```console\n$ ls -l kibana-10.4.8.wrap.tgz\n-rw-r--r--  1 martinpe  staff  731200979 Aug  4 15:17 kibana-10.4.8.wrap.tgz\n```\n\nIf you want to make changes on the Helm chart, you can pass a directory to the wrap command. For example, if we wanted to wrap the previously pulled mariadb Helm chart, we could just do:\n\n```console\n$ helm dt wrap examples/mariadb/\n »  Wrapping Helm chart \"examples/mariadb/\"\n    ✔  Images.lock file \"/tmp/workspace/distribution-tooling-for-helm/examples/mariadb/Images.lock\" does not exist\n    ✔  Images.lock file written to \"/tmp/workspace/distribution-tooling-for-helm/examples/mariadb/Images.lock\"\n    »  Pulling images into \"/tmp/workspace/distribution-tooling-for-helm/examples/mariadb/images\"\n       ✔  All images pulled successfully\n    ✔  Helm chart wrapped to \"/tmp/workspace/distribution-tooling-for-helm/mariadb-13.0.0.wrap.tgz\"\n 🎉  Helm chart wrapped into \"/tmp/workspace/distribution-tooling-for-helm/mariadb-13.0.0.wrap.tgz\"\n```\n\nIf your chart and docker images include artifacts such as signatures or metadata, you can also include them in the wrap using the `--fetch-artifacts` flag.\n\nCurrently, `dt` supports moving artifacts that follow certain conventions. That is:\n\n- Cosign keys that are associated to the digest with a .sig suffix\n- Metadata entries stored in a `sha256-digest.metadata` OCI entry\n\nFor example:\n\n```console\n$ helm dt wrap --fetch-artifacts oci://docker.io/bitnamicharts/kibana\n ...\n 🎉  Helm chart wrapped into \"/tmp/workspace/distribution-tooling-for-helm/kibana-10.4.8.wrap.tgz\"\n\n$ tar -tzf \"/tmp/workspace/distribution-tooling-for-helm/kibana-10.4.8.wrap.tgz\" | grep artifacts\nkibana-10.4.8/artifacts/images/kibana/kibana/8.10.4-debian-11-r0.sig\nkibana-10.4.8/artifacts/images/kibana/kibana/8.10.4-debian-11-r0.metadata\nkibana-10.4.8/artifacts/images/kibana/kibana/8.10.4-debian-11-r0.metadata.sig\n...\n```\n\n\u003e **Note:** Signatures\n\u003e\n\u003e Chart signatures are not bundled as they would be invalidated at chart unwrap because of the relocation. All the container images wrapped will maintain their signatures and metadata.\n\n#### Light wraps\n\nSometimes you might actually want to wrap your Helm charts without fetching the container images. This is not exactly a wrap from the point of view of the initial conception of this tool but we acknowledge that this case can be useful when you already know that the Helm charts exist in the target registry. Hence you can skip wrapping the container images by using the `--skip-pull-images` flag:\n\n```console\n$ helm dt wrap oci://docker.io/bitnamicharts/magento --skip-pull-images\n »  Wrapping Helm chart \"oci://docker.io/bitnamicharts/magento\"\n    ✔  Helm chart downloaded to \"/var/folders/cr/jn5532p51390yx_6ctd7c6_40000gn/T/chart-2437949055/chart-1972871498/magento\"\n    ✔  Images.lock file written to \"/var/folders/cr/jn5532p51390yx_6ctd7c6_40000gn/T/chart-2437949055/wrap/chart/Images.lock\"\n    ✔  Compressed into \"/tmp/workspace/distribution-tooling-for-helm/magento-28.0.4.wrap.tgz\"\n\n 🎉  Helm chart wrapped into \"/tmp/workspace/distribution-tooling-for-helm/magento-28.0.4.wrap.tgz\"\n ```\n\n### Unwrapping Helm charts\n\nUnwrapping a Helm chart can be done either to a local folder or to a target OCI registry, being the latter the most powerful option. By unwrapping the Helm chart to a target OCI registry the `dt` tool will unwrap the wrapped file, proceed to push the container images into the target registry that you have specified, relocate the references from the Helm chart to the provided registry and finally push the relocated Helm chart to the registry as well.\n\nAt that moment your Helm chart will be ready to be used from the target registry without any dependencies to the source. By default, the tool will run in dry-run mode and require you to confirm actions but you can speed everything up with the `--yes` parameter.\n\n```console\n$ helm dt unwrap kibana-10.4.8.wrap.tgz demo.goharbor.io/helm-plugin/ --yes\n »  Unwrapping Helm chart \"kibana-10.4.8.wrap.tgz\"\n    ✔  Helm chart uncompressed to \"/var/folders/mn/j41xvgsx7l90_hn0hlwj9p180000gp/T/chart-586072428/at-wrap2428431258\"\n    ✔  Helm chart relocated successfully\n    »  The wrap includes the following 2 images:\n\n       demo.goharbor.io/helm-plugin/bitnami/kibana:8.9.0-debian-11-r9\n       demo.goharbor.io/helm-plugin/bitnami/os-shell:11-debian-11-r25\n\n    »  Pushing Images\n       ✔  All images pushed successfully\n       ✔  Chart \"/var/folders/mn/j41xvgsx7l90_hn0hlwj9p180000gp/T/chart-586072428/at-wrap2428431258\" lock is valid\n\n    ⠋ Pushing Helm chart \"/var/folders/mn/j41xvgsx7l90_hn0hlwj9p180000gp/T/chart-586072428/at-wrap2428431258\" to \"oci://demo.goharbor.io/helm-plugin/\" (0    ⠙ Pushing Helm chart \"/var/folders/mn/j41xvgsx7l90_hn0hlwj9p180000gp/T/chart-586072428/at-wrap2428431258\" to \"oci://demo.goharbor.io/helm-plugin/\" (0    ⠹ Pushing Helm chart \"/var/folders/mn/j41xvgsx7l90_hn0hlwj9p180000gp/T/chart-586072428/at-wrap2428431258\" to \"oci://demo.goharbor.io/helm-plugin/\" (0    ⠸ Pushing Helm chart \"/var/folders/mn/j41xvgsx7l90_hn0hlwj9p180000gp/T/chart-586072428/at-wrap2428431258\" to \"oci://demo.goharbor.io/helm-plugin/\" (1    ⠼ Pushing Helm chart \"/var/folders/mn/j41xvgsx7l90_hn0hlwj9p180000gp/T/chart-586072428/at-wrap2428431258\" to \"oci://demo.goharbor.io/helm-plugin/\" (1    ⠴ Pushing Helm chart \"/var/folders/mn/j41xvgsx7l90_hn0hlwj9p180000gp/T/chart-586072428/at-wrap2428431258\" to \"oci://demo.goharbor.io/helm-plugin/\" (1    ⠦ Pushing Helm chart \"/var/folders/mn/j41xvgsx7l90_hn0hlwj9p180000gp/T/chart-586072428/at-wrap2428431258\" to \"oci://demo.goharbor.io/helm-plugin/\" (1    ⠧ Pushing Helm chart \"/var/folders/mn/j41xvgsx7l90_hn0hlwj9p180000gp/T/chart-586072428/at-wrap2428431258\" to \"oci://demo.goharbor.io/helm-plugin/\" (1    ⠇ Pushing Helm chart \"/var/folders/mn/j41xvgsx7l90_hn0hlwj9p180000gp/T/chart-586072428/at-wrap2428431258\" to \"oci://demo.goharbor.io/helm-plugin/\" (2    ⠏ Pushing Helm chart \"/var/folders/mn/j41xvgsx7l90_hn0hlwj9p180000gp/T/chart-586072428/at-wrap2428431258\" to \"oci://demo.goharbor.io/helm-plugin/\" (2    ✔  Helm chart successfully pushed\n\n 🎉  Helm chart unwrapped successfully: You can use it now by running \"helm install oci://demo.goharbor.io/helm-plugin/kibana --generate-name\"\n```\n\nIf your wrap includes bundled artifacts (if you wrapped it using the `--fetch-artifacts` flag), they will be also pushed to the remote registry.\n\n## Advanced Usage\n\nThat was all as per the basic most basic and powerful usage. If you're interested in some other additional goodies then we will dig next into some specific finer-grained commands.\n\n### Creating an images lock\n\nAn images lock file, a.k.a. `Images.lock` is a new file that gets created inside the directory as per [this HIP submission](https://github.com/helm/community/pull/281) to Helm community. The `Images.lock` file contains the list of all the container images annotated within a Helm chart's `Chart.yaml` manifest, including also all the images from its subchart dependencies. Along with the images, some other metadata useful for automating processing and relocation is also added.\n\nSo, for example, the mariadb Helm chart that we downloaded earlier, has an `images` annotation like this:\n\n```console\n$ cat examples/mariadb/Chart.yaml | head -n 10\n```\n\n```yaml\nannotations:\n    category: Database\n    images: |\n        - image: docker.io/bitnami/mariadb:11.0.2-debian-11-r2\n          name: mariadb\n        - image: docker.io/bitnami/mysqld-exporter:0.15.0-debian-11-r5\n          name: mysqld-exporter\n        - image: docker.io/bitnami/os-shell:11-debian-11-r22\n          name: os-shell\n    licenses: Apache-2.0\n```\n\nWe can run the following command to create the `Images.lock` for the above Helm chart:\n\n```console\n$ helm dt images lock examples/mariadb\nINFO[0005] Images.lock file written to \"/tmp/workspace/distribution-tooling-for-helm/examples/mariadb/Images.lock\"\n```\n\nAnd it should look similar to this:\n\n```console\n$ cat examples/mariadb/Images.lock\n```\n\n```yaml\napiVersion: v0\nkind: ImagesLock\nmetadata:\n  generatedAt: \"2023-08-04T13:36:09.398772Z\"\n  generatedBy: Distribution Tooling for Helm\nchart:\n  name: mariadb\n  version: 13.0.0\nimages:\n  - name: mariadb\n    image: docker.io/bitnami/mariadb:11.0.2-debian-11-r2\n    chart: mariadb\n    digests:\n      - digest: sha256:d3006a4d980d82a28f433ae7af316c698738ba29a5a598d527751cb9139ab7ff\n        arch: linux/amd64\n      - digest: sha256:3ec78b7c97020ca2340189b75eba4a92ccb0d858ee62dd89c6a9826fb20048c9\n        arch: linux/arm64\n  - name: mysqld-exporter\n    image: docker.io/bitnami/mysqld-exporter:0.15.0-debian-11-r5\n    chart: mariadb\n    digests:\n      - digest: sha256:6f257cc719f5bbde118c15ad610dc27d773f80216adabf10e315fbcaff078615\n        arch: linux/amd64\n      - digest: sha256:e0c141706fd1ce9ec5276627ae53994343ec2719aba606c1dc228f9290698fc1\n        arch: linux/arm64\n  - name: os-shell\n    image: docker.io/bitnami/os-shell:11-debian-11-r22\n    chart: mariadb\n    digests:\n      - digest: sha256:7082ebf5644cf4968ac635986ded132dd308c0b9c13138f093834f343cd47d7b\n        arch: linux/amd64\n      - digest: sha256:232ca2da59e508978543c8b113675c239a581938c88cbfa1ff17e9b6e504dc1a\n        arch: linux/arm64\n```\n\nBy default `Images.lock` creation expects an `images` annotation in your Helm chart. However, this can be overridden by the `annotations-key` flag. This is useful for example when dealing with Helm charts that rely on a different annotation like `artifacthub.io/images` which has existed for a while. You can use this flag with most of the commands in this guide.\n\n```console\n$ helm dt images lock ../charts/jenkins --annotations-key artifacthub.io/images\n```\n\n### Targetting specific architectures\n\nThe above `lock` command can be constrained to specific architectures. This is pretty useful to create lighter wraps as many of the images will be dropped when wrapping.\n\n```console\n$ helm dt images lock ../charts/jenkins --platforms linux/amd64\n```\n\nIf we now look at generated `Images.lock` we will notice that it contains only `linux/amd64` digests:\n\n```yaml\napiVersion: v0\nkind: ImagesLock\nmetadata:\n  generatedAt: \"2023-08-04T14:24:18.515082Z\"\n  generatedBy: Distribution Tooling for Helm\nchart:\n  name: mariadb\n  version: 13.0.0\nimages:\n  - name: mariadb\n    image: docker.io/bitnami/mariadb:11.0.2-debian-11-r2\n    chart: mariadb\n    digests:\n      - digest: sha256:d3006a4d980d82a28f433ae7af316c698738ba29a5a598d527751cb9139ab7ff\n        arch: linux/amd64\n  - name: mysqld-exporter\n    image: docker.io/bitnami/mysqld-exporter:0.15.0-debian-11-r5\n    chart: mariadb\n    digests:\n      - digest: sha256:6f257cc719f5bbde118c15ad610dc27d773f80216adabf10e315fbcaff078615\n        arch: linux/amd64\n  - name: os-shell\n    image: docker.io/bitnami/os-shell:11-debian-11-r22\n    chart: mariadb\n    digests:\n      - digest: sha256:7082ebf5644cf4968ac635986ded132dd308c0b9c13138f093834f343cd47d7b\n        arch: linux/amd64\n```\n\n### Verifying an images lock\n\nThe `verify` command can be used to validate the integrity of an `Images.lock` file in a given Helm chart. This command will try to validate that all upstream container images that will be pulled from the Helm chart match actually the image digests that exist in the actual lock file.\n\nWith this command, you can make sure that when you distribute a Helm chart with its corresponding `Images.lock` then any customer will be able to validate that just exactly the images defined in the lock will be pulled. Note that this is exactly part of what the `unwrap` command does, to make sure that only exactly what was wrapped gets into the target registry. Signing and other types of provenance are out of the scope of this tool for the time being and need to be added manually with external tooling. This is an area that we are very eager to improve soon.\n\n```console\n$ helm dt images verify examples/mariadb\nINFO[0004] Helm chart \"examples/mariadb\" lock is valid\n```\n\n### Pulling Helm chart images\n\nBased on the `Images.lock` file, this command downloads all listed images into the `images/` subfolder.\n\n```console\n$ helm dt images pull examples/mariadb\nINFO[0000] Pulling images into \"/tmp/workspace/distribution-tooling-for-helm/examples/mariadb/images\"\nINFO[0022] All images pulled successfully\nINFO[0022] Success\n```\n\nThen, in the `images` folder we should have something like\n\n```console\n$ ls -1 examples/mariadb/images\n232ca2da59e508978543c8b113675c239a581938c88cbfa1ff17e9b6e504dc1a.tar\n3ec78b7c97020ca2340189b75eba4a92ccb0d858ee62dd89c6a9826fb20048c9.tar\n6f257cc719f5bbde118c15ad610dc27d773f80216adabf10e315fbcaff078615.tar\n7082ebf5644cf4968ac635986ded132dd308c0b9c13138f093834f343cd47d7b.tar\nd3006a4d980d82a28f433ae7af316c698738ba29a5a598d527751cb9139ab7ff.tar\ne0c141706fd1ce9ec5276627ae53994343ec2719aba606c1dc228f9290698fc1.tar\n```\n\n### Relocating a chart\n\nThis command will relocate a Helm chart rewriting the `Images.lock` and all of its subchart dependencies locks as well. Additionally, it will change the `Chart.yaml` annotations, and any images used inside `values.yaml` (and all those on subchart dependencies as well).\n\nFor example\n\n```console\n$ helm dt charts relocate examples/mariadb acme.com/federal\nINFO[0000] Helm chart relocated successfully\n```\n\nAnd we can check that references have indeed changed:\n\n```console\n$ cat examples/mariadb/Images.lock |grep image\n```\n\n```yaml\nimages:\n    image: acme.com/federal/bitnami/mariadb:11.0.2-debian-11-r2\n    image: acme.com/federal/bitnami/mysqld-exporter:0.15.0-debian-11-r5\n    image: acme.com/federal/bitnami/os-shell:11-debian-11-r22\n```\n\nNote that in some scenarios one might actually not be interested in relocating the images. Perhaps one is only interested in pushing the Helm chart to a different registry but retaining the images. For such scenarios the `--skip-relocation` flag can be used when unwrapping the chart.\n\n### Pushing images\n\nBased on the `Images.lock` file, this command pushes all images (that must have been previously pulled into the `images/` folder) into their respective registries. Note that this command does not relocate anything. It will simply try to push the images to wherever they are pointing.\n\nObviously, this command only makes sense when used after having pulled the images and executed the `relocate` command.\n\n```console\n# .. should have pulled images first ..\n# .. then relocate to a target registry ..\n# and now...\n$ helm dt images push examples/mariadb\nINFO[0033] All images pushed successfully\n```\n\n### Getting information about a wrapped chart\n\nIt is sometimes useful to obtain information about a wrapped chart before unwrapping it. For this purpose, you can use the info command:\n\n```console\n$ helm dt info wordpress-16.1.24.wrap.tgz\n »  Wrap Information\n       Chart: wordpress\n       Version: 16.1.24\n    »  Metadata\n          - generatedBy: Distribution Tooling for Helm\n          - generatedAt: 2023-08-18T12:52:55.824345304Z\n    »  Images\n          docker.io/bitnami/apache-exporter:0.13.4-debian-11-r12 (linux/amd64, linux/arm64)\n          docker.io/bitnami/bitnami-shell:11-debian-11-r132 (linux/amd64, linux/arm64)\n          docker.io/bitnami/wordpress:6.2.2-debian-11-r26 (linux/amd64, linux/arm64)\n          docker.io/bitnami/bitnami-shell:11-debian-11-r123 (linux/amd64, linux/arm64)\n          docker.io/bitnami/mariadb:10.11.4-debian-11-r0 (linux/amd64, linux/arm64)\n          docker.io/bitnami/mysqld-exporter:0.14.0-debian-11-r125 (linux/amd64, linux/arm64)\n          docker.io/bitnami/bitnami-shell:11-debian-11-r130 (linux/amd64, linux/arm64)\n          docker.io/bitnami/memcached:1.6.21-debian-11-r4 (linux/amd64, linux/arm64)\n          docker.io/bitnami/memcached-exporter:0.13.0-debian-11-r8 (linux/amd64, linux/arm64)\n```\n\nIf you are interested in getting the image digests, you can use the `--detailed` flag:\n\n```console\n$ helm dt info --detailed wordpress-16.1.24.wrap.tgz\n »  Wrap Information\n       Chart: wordpress\n       Version: 16.1.24\n    »  Metadata\n          - generatedBy: Distribution Tooling for Helm\n          - generatedAt: 2023-08-18T12:52:55.824345304Z\n    »  Images\n       »  wordpress/apache-exporter\n             Image: docker.io/bitnami/apache-exporter:0.13.4-debian-11-r12\n             Digests\n             - Arch: linux/amd64\n               Digest: sha256:0b4373c3571d5640320b68f8d296c0a4eaf7704947214640b77528bb4d79d23c\n             - Arch: linux/arm64\n               Digest: sha256:895ba569e4db3188798e445fe3be2e4da89fd85cb8ae0c5ef0bd2a67cfe4305c\n...\n       »  mariadb/bitnami-shell\n             Image: docker.io/bitnami/bitnami-shell:11-debian-11-r123\n             Digests\n             - Arch: linux/amd64\n               Digest: sha256:13d8883d4f40612e8a231c5d9fa8c4efa74d2a62f0a1991f20fc32c5debdd2b1\n             - Arch: linux/arm64\n               Digest: sha256:74579dc63b3ae7d8ec21a6ffcd47d16781582fef8dd5a28e77844fcbcb1072c1\n...\n```\n\nIt is also possible to get a YAML dump if the `Images.lock` in case you need to feed it to another process:\n\n```console\n$ helm dt info --yaml wordpress-16.1.24.wrap.tgz\n```\n\n```yaml\napiVersion: v0\nkind: ImagesLock\nmetadata:\n  generatedAt: \"2023-08-18T12:52:55.824345304Z\"\n  generatedBy: Distribution Tooling for Helm\nchart:\n  name: wordpress\n  version: 16.1.24\nimages:\n  - name: apache-exporter\n    image: docker.io/bitnami/apache-exporter:0.13.4-debian-11-r12\n    chart: wordpress\n    digests:\n      - digest: sha256:0b4373c3571d5640320b68f8d296c0a4eaf7704947214640b77528bb4d79d23c\n        arch: linux/amd64\n      - digest: sha256:895ba569e4db3188798e445fe3be2e4da89fd85cb8ae0c5ef0bd2a67cfe4305c\n        arch: linux/arm64\n...\n```\n\n### Annotating a Helm chart (EXPERIMENTAL)\n\n`Images.lock` creation relies on the existence of the special images annotation inside `Chart.yaml`. If you have a Helm chart that does not contain any annotations, this command can be used to guess and generate an annotation with a tentative list of images. It's important to note that this list is a **best-effort** as the list of images is obtained from the `values.yaml` file and this is always an unreliable, often incomplete, and error-prone source as the configuration in `values.yaml` is very variable.\n\n```console\n$ helm dt charts annotate examples/mariadb\nINFO[0000] Helm chart annotated successfully\n```\n\n### Converting a Helm chart into a Carvel bundle (EXPERIMENTAL)\n\nFrom `dt` v0.2.0 we have introduced a new command to create a [Carvel bundle](https://carvel.dev/imgpkg/docs/v0.37.x/resources/#bundle) from any Helm chart.\n\n\n```console\n$ helm dt charts carvelize examples/postgresql\n ✔  Helm chart \"examples/postgresql\" lock is valid\n »  Generating Carvel bundle for Helm chart \"examples/postgresql\"\n    ✔  Validating Carvel images lock\n    ✔  Carvel images lock written to \"examples/postgresql/.imgpkg/images.yml\"\n    ✔  Carvel metadata written to \"examples/postgresql/.imgpkg/bundle.yml\"\n 🎉  Carvel bundle created successfully\n```\n\n### Login and logout from OCI registries (EXPERIMENTAL)\n\nIt is also possible to login and logout from OCI registries using the `dt` command. For example:\n\n```console\n$ helm dt auth login 127.0.0.1:5000 -u testuser -p testpassword\n ✔  log in to 127.0.0.1:5000 as user testuser\n 🎉  logged in via /Users/home/.docker/config.json\n```\n\n```console\n$ helm dt auth logout 127.0.0.1:5000\n ✔  logout from 127.0.0.1:5000\n 🎉  logged out via /Users/home/.docker/config.json\n```\n\n## Frequently Asked Questions\n\n### I cannot install the plugin due to `Error: Unable to update repository: exit status 1`\n\nThis can happen when somehow the plugin process installation or removal breaks and the Helm plugin's cache gets corrupted. Try removing the plugin from the cache and reinstalling it. For example on MAC OSX it would be:\n\n```console\n$ rm -rf $HOME/Library/Caches/helm/plugins/https-github.com-vmware-labs-distribution-tooling-for-helm\n$ helm plugin install https://github.com/vmware-labs/distribution-tooling-for-helm\n```\n\n### How does this project relate to the [relok8s](https://github.com/vmware-tanzu/asset-relocation-tool-for-kubernetes)? Does it replace it?\n\nGood question. Both projects come from VMware and should be able to continue using [relok8s](https://github.com/vmware-tanzu/asset-relocation-tool-for-kubernetes) if you want to. Although, our expectation is to gradually build more and more tooling around the [HIP-15](https://github.com/helm/community/blob/main/hips/hip-0015.md) proposal as it does have a substantial number of benefits when compared to the relocation approach followed by relok8s.\n\nSo as the community adopts this new proposal and this plugin becomes more mature we would suggest anyone using relok8s to move its platform scripts to start using this helm plugin. We expect this move to be pretty much straightforward, and actually a great simplification for anyone using relok8s or even chart-syncer.\n\n### What about chart-syncer? Will it continue to work?\n\nYes, still support [chart-syncer](https://github.com/bitnami-labs/charts-syncer) and we don't have any short-term plans right now about it. But as this tool gains adoption, it becomes natural to think that it should be fairly straightforward to implement Helm chart syncing on top of it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmware-labs%2Fdistribution-tooling-for-helm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvmware-labs%2Fdistribution-tooling-for-helm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmware-labs%2Fdistribution-tooling-for-helm/lists"}