diff --git a/docs/faq.md b/docs/faq.md index 08f565e65..6edeff773 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -132,6 +132,8 @@ battle-testing. Please have a look at `helm help chart` and `helm help registry` for more information on how to package a chart and push it to a Docker registry. +For more info, please see [this page](./registries.md). + ### Removal of helm serve `helm serve` ran a local Chart Repository on your machine for development purposes. However, it didn't receive much diff --git a/docs/registries.md b/docs/registries.md new file mode 100644 index 000000000..d9a824554 --- /dev/null +++ b/docs/registries.md @@ -0,0 +1,175 @@ +# Registries + +Helm 3 uses OCI for package distribution. Chart packages are stored and shared across OCI-based registries. + +## Running a registry + +Starting a registry for test purposes is trivial. As long as you have Docker installed, run the following command: +``` +docker run -dp 5000:5000 --restart=always --name registry registry +``` + +This will start a registry server at `localhost:5000`. + +Use `docker logs -f registry` to see the logs and `docker rm -f registry` to stop. + +If you wish to persist storage, you can add `-v $(pwd)/registry:/var/lib/registry` to the command above. + +For more configuration options, please see [the docs](https://docs.docker.com/registry/deploying/). + +### Auth + +If you wish to enable auth on the registry, you can do the following- + +First, create file `auth.htpasswd` with username and password combo: +``` +htpasswd -cB -b auth.htpasswd myuser mypass +``` + +Then, start the server, mounting that file and setting the `REGISTRY_AUTH` env var: +``` +docker run -dp 5000:5000 --restart=always --name registry \ + -v $(pwd)/auth.htpasswd:/etc/docker/registry/auth.htpasswd \ + -e REGISTRY_AUTH="{htpasswd: {realm: localhost, path: /etc/docker/registry/auth.htpasswd}}" \ + registry +``` + +## Commands for working with registries + +Commands are available under both `helm registry` and `helm chart` that allow you to work with registries and local cache. + +### The `registry` subcommand + +#### `login` + +login to a registry (with manual password entry) + +``` +$ helm registry login -u myuser localhost:5000 +Password: +Login succeeded +``` + +#### `logout` + +logout from a registry + +``` +$ helm registry logout localhost:5000 +Logout succeeded +``` + +### The `chart` subcommand + +#### `save` + +save a chart directory to local cache + +``` +$ helm chart save mychart/ localhost:5000/myrepo/mychart:2.7.0 +Name: mychart +Version: 2.7.0 +Meta: sha256:ca9588a9340fb83a62777cd177dae4ba5ab52061a1618ce2e21930b86c412d9e +Content: sha256:a66666c6b35ee25aa8ecd7d0e871389b5a2a0576295d6c366aefe836001cb90d +2.7.0: saved +``` + +#### `list` + +list all saved charts + +``` +$ helm chart list +REF NAME VERSION DIGEST SIZE CREATED +localhost:5000/myrepo/mychart:2.7.0 mychart 2.7.0 84059d7 454 B 27 seconds +localhost:5000/stable/acs-engine-autoscaler:2.2.2 acs-engine-autoscaler 2.2.2 d8d6762 4.3 KiB 2 hours +localhost:5000/stable/aerospike:0.2.1 aerospike 0.2.1 4aff638 3.7 KiB 2 hours +localhost:5000/stable/airflow:0.13.0 airflow 0.13.0 c46cc43 28.1 KiB 2 hours +localhost:5000/stable/anchore-engine:0.10.0 anchore-engine 0.10.0 3f3dcd7 34.3 KiB 2 hours +... +``` + +#### `export` + +export a chart to directory + +``` +$ helm chart export localhost:5000/myrepo/mychart:2.7.0 +Name: mychart +Version: 2.7.0 +Meta: sha256:3344059bb81c49cc6f2599a379da0a6c14313cf969f7b821aca18e489ba3991b +Content: sha256:84059d7403f496a1c63caf97fdc5e939ea39e561adbd98d0aa864d1b9fc9653f +Exported to mychart/ +``` + +#### `push` + +push a chart to remote + +``` +$ helm chart push localhost:5000/myrepo/mychart:2.7.0 +The push refers to repository [localhost:5000/myrepo/mychart] +Name: mychart +Version: 2.7.0 +Meta: sha256:ca9588a9340fb83a62777cd177dae4ba5ab52061a1618ce2e21930b86c412d9e +Content: sha256:a66666c6b35ee25aa8ecd7d0e871389b5a2a0576295d6c366aefe836001cb90d +2.7.0: pushed to remote (2 layers, 478 B total) +``` + +#### `remove` + +remove a chart from cache + +``` +$ helm chart remove localhost:5000/myrepo/mychart:2.7.0 +2.7.0: removed +``` + +#### `pull` + +pull a chart from remote + +``` +$ helm chart pull localhost:5000/myrepo/mychart:2.7.0 +2.7.0: Pulling from localhost:5000/myrepo/mychart +Name: mychart +Version: 2.7.0 +Meta: sha256:ca9588a9340fb83a62777cd177dae4ba5ab52061a1618ce2e21930b86c412d9e +Content: sha256:a66666c6b35ee25aa8ecd7d0e871389b5a2a0576295d6c366aefe836001cb90d +Status: Chart is up to date for localhost:5000/myrepo/mychart:2.7.0 +``` + +## Where are my charts? + +Charts stored using the commands above will be cached on disk at `~/.helm/registry` (or somewhere else depending on `$HELM_HOME`). + +Chart content (tarball) and chart metadata (json) are stored as separate content-addressable blobs. This prevents storing the same content twice when, for example, you are simply modifying some fields in `Chart.yaml`. They are joined together and converted back into regular chart format when using the `export` command. + +The chart name and chart version are treated as "first-class" properties and stored separately. They are extracted out of `Chart.yaml` prior to building the metadata blob. + +The following shows an example of a single chart stored in the cache (`localhost:5000/myrepo/mychart:2.7.0`): +``` +$ tree ~/.helm/registry +/Users/me/.helm/registry +├── blobs +│   └── sha256 +│   ├── 3344059bb81c49cc6f2599a379da0a6c14313cf969f7b821aca18e489ba3991b +│   └── 84059d7403f496a1c63caf97fdc5e939ea39e561adbd98d0aa864d1b9fc9653f +├── charts +│ └── mychart +│ └── versions +│ └── 2.7.0 +└── refs + └── localhost_5000 + └── myrepo + └── mychart + └── tags + └── 2.7.0 + ├── chart -> /Users/me/.helm/registry/charts/mychart/versions/2.7.0 + ├── content -> /Users/me/.helm/registry/blobs/sha256/3344059bb81c49cc6f2599a379da0a6c14313cf969f7b821aca18e489ba3991b + └── meta -> /Users/me/.helm/registry/blobs/sha256/84059d7403f496a1c63caf97fdc5e939ea39e561adbd98d0aa864d1b9fc9653f +``` + +## Migrating from chart repos + +Migrating from classic [chart repositories](./chart_repository.md) (index.yaml-based repos) is as simple as a `helm fetch` (Helm 2 CLI), `helm chart save`, `helm chart push`.