Add documentation on registries (#5754)

Signed-off-by: Josh Dolitsky <jdolitsky@gmail.com>
5 years ago · 1d0b983081
parent 7d3693bd56
commit 1d0b983081
2 changed files with 177 additions and 0 deletions
--- 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
--- a/docs/registries.md
+++ b/docs/registries.md
@ -0,0 +1,175 @@
+# Registries
+
+Helm 3 uses <a href="https://www.opencontainers.org/" target="_blank">OCI</a> 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`.