Working with OCI Registries
1. Understanding OCI Registry Support
| Feature | Description | Support Status |
|---|---|---|
| OCI Artifact Support | Helm charts can be stored and retrieved as OCI artifacts in registries | NEW |
| Registry Authentication | Supports authentication via username/password or token-based access | NEW |
| Chart Storage | Charts are stored as OCI artifacts with metadata and layers | NEW |
| Versioning | OCI artifacts support semantic versioning and tags | NEW |
Example: Pushing a Chart to OCI Registry
helm push my-chart-1.0.0.tgz oci://my-registry.example.com/my-repo
Note: OCI registry support is available in Helm v3.12+.
2. Logging into Registry
| Command | Description | Notes |
|---|---|---|
| helm registry login | Log in to a registry | Supports OCI registries and Helm repositories |
Example: Logging into an OCI registry
helm registry login my-oci-registry.com/my-repo \
--username <user> \
--password <password>
Note: For registries supporting token authentication, you can also use
--password-stdin to provide the password securely.
3. Logging out of Registry
| Command | Description | Notes |
|---|---|---|
| helm registry logout | Logs out of a registry | Removes stored credentials for the specified registry |
Note: This command removes the stored credentials for the specified registry from the local Helm configuration.
4. Pushing Chart to OCI
| Command | Description | Notes |
|---|---|---|
| helm registry login | Log in to an OCI registry | Required before pushing charts |
| helm push | Push a chart to an OCI registry | Uses helm package internally |
Example: Pushing a Chart to OCI Registry
helm registry login my-oci-registry.com --username "user" --password "pass"
helm push my-chart-1.0.0.tgz my-oci-registry.com/myrepo/my-chart:1.0.0
Note: The chart must be packaged first using
helm package or directly pushed via helm push.
Warning: Ensure the registry URL and chart reference are correctly formatted to avoid push failures.
5. Pulling Chart from OCI
| Command | Description | Example |
|---|---|---|
| helm pull | Downloads a chart from an OCI registry | helm pull oci://registry.example.com/mychart --version 1.2.3 |
Note: Ensure the OCI registry is properly configured in your Helm client using
helm registry login if authentication is required.
Warning: Helm charts pulled from OCI registries must be compatible with the Helm version installed on your system.
6. Installing from OCI
| Command | Description | Example |
|---|---|---|
| helm install | Installs a chart from an OCI registry | helm install my-release oci://registry.example.com/my-chart --version 1.0.0 |
Example: Installing a Chart from OCI Registry
helm install my-release oci://ghcr.io/myorg/my-chart --version 2.1.0
Note: Ensure the OCI registry is accessible and the chart is properly tagged.
Warning: Helm must be configured to allow OCI registry access. Use
helm registry login if authentication is required.
7. Using OCI References
| Reference Type | Format | Description |
|---|---|---|
| Image Reference | registry.example.com/myrepo/mychart:1.2.3 |
Standard OCI image reference for Helm chart |
| Digest Reference | registry.example.com/myrepo/mychart@sha256:a1b2c3d4... |
Content-addressable reference to a specific chart version |
| Tagged Reference | registry.example.com/myrepo/mychart:latest |
Reference to a chart with a specific tag |
Example: Installing Chart via OCI Reference
helm install my-release registry.example.com/myrepo/mychart@sha256:a1b2c3d4...
Note: OCI references must be valid image names and follow the
registry/namespace/chart:tag or registry/namespace/chart@digest format.
Warning: Using
latest tags can lead to unpredictable behavior in production environments.
8. Listing OCI Chart Tags
| Command | Description | Notes |
|---|---|---|
| helm registry tag list | List all tags for a chart in an OCI registry | Requires helm registry login to be run first |
Example: Listing OCI Chart Tags
helm registry login my-oci-registry.com
helm registry tag list my-oci-registry.com/my-chart
Note: The
helm registry tag list command requires Helm 3.12+ and an OCI-compatible registry.
9. Setting OCI Credentials
| Method | Description | Example |
|---|---|---|
| helm registry login | Log in to an OCI registry using username and password | helm registry login <registry-url> -u <username> -p <password> |
| helm registry login (with token) | Log in using an access token instead of password | helm registry login <registry-url> -u <username> -p <token> |
| helm registry login (with kubeconfig) | Use Kubernetes credentials for registry authentication | helm registry login <registry-url> --kubeconfig <path-to-kubeconfig> |
Example: Using Helm Registry Login with Token
helm registry login https://my-registry.com -u myuser -p eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Note: Tokens should be treated as sensitive information and not stored in plain text.
10. Using Docker Config
Example: Configure Docker Registry Access
helm registry login my-registry.com --username myuser --password mypass
| Configuration | Description | Value |
|---|---|---|
| auth | Authentication method for registry | basic |
| username | Registry username | myuser |
| password | Registry password or token | mypass |
Note: Helm uses the Docker CLI configuration to manage registry credentials. Ensure your
~/.docker/config.json is properly set up for secure access.
Warning: Storing passwords in plain text is insecure. Use tokens or environment variables for production environments.
11. Working with Private OCI Registries
| Registry Type | Authentication Method | Notes |
|---|---|---|
| Helm Registry | helm registry login |
Use Helm's built-in registry support for private registries |
| Docker Registry | helm registry login --username <user> --password <pass> |
Authenticate using Docker credentials |
| Azure Container Registry (ACR) | helm registry login --username <user> --password <pass> |
Use Azure CLI or service principal for authentication |
| Amazon ECR | helm registry login --username <user> --password <pass> |
Use AWS CLI or IAM roles for authentication |
Example: Login to Private OCI Registry
helm registry login my-private-registry.com:5000 --username <user> --password <pass>
Example: Push Chart to Private Registry
helm package my-chart --destination ./my-chart-1.0.0.tgz
helm registry push my-private-registry.com:5000/my-chart-1.0.0.tgz
Note: Ensure the registry URL is accessible and the chart is properly packaged before pushing.
Warning: Private registry credentials should be stored securely and not hardcoded in scripts.