helm-oci

A Helm plugin that adds local bookmarking for OCI-based Helm charts.

Table of Contents

• Problem
• Solution
• Installation
• Commands
  • Managing Bookmarks
  • Inspecting Charts
  • Installing and Managing Releases
• Bookmark Storage
• Development
• License

Installation

helm plugin install https://github.com/esnet/helm-oci/releases/download/v1.0.0/oci-1.0.0.tgz

Problem

Helm's traditional repository system lets you add a repo once and reference charts by short name:

helm repo add bitnami https://charts.bitnami.com/bitnami
helm install my-release bitnami/nginx

OCI-based charts have no equivalent. Every install, upgrade, or inspect requires the full OCI URL:

helm install my-gateway oci://docker.io/envoyproxy/gateway-helm --version 1.3.0
helm show values oci://docker.io/envoyproxy/gateway-helm --version 1.3.0
helm upgrade my-gateway oci://docker.io/envoyproxy/gateway-helm --version 1.4.0

When managing multiple OCI charts across clusters, remembering and retyping these URLs becomes impractical.

Solution

helm-oci is a Helm plugin which solves this UX problem and lets you bookmark OCI chart URLs and reference them by name.

❯ helm oci
Manage local bookmarks for OCI-based Helm charts.

Add OCI chart URLs once, then reference them by name for install,
upgrade, pull, show, values, template, and version listing.

Usage:
  oci [command]

Available Commands:
  add         Bookmark an OCI chart reference
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  install     Install a bookmarked OCI chart
  list        List all bookmarked OCI chart references
  pull        Pull a bookmarked OCI chart
  remove      Remove a bookmarked OCI chart reference
  show        Show chart metadata for a bookmarked OCI chart
  template    Render templates for a bookmarked OCI chart
  upgrade     Upgrade a release using a bookmarked OCI chart
  values      Show values for a bookmarked OCI chart
  versions    List available versions for a bookmarked OCI chart

Usage

Managing Bookmarks

# Add a bookmark
helm oci add <name> <oci-url>
helm oci add envoy-gw oci://docker.io/envoyproxy/gateway-helm
helm oci add cert-manager oci://quay.io/jetstack/cert-manager

# List all bookmarks
helm oci list

# Remove a bookmark
helm oci remove <name>

Inspecting Charts

# List available versions (tags) from the OCI registry
helm oci versions <name>

# Show chart metadata
helm oci show <name> [--version <version>]

# Show default values
helm oci values <name> [--version <version>]

Installing and Managing Releases

# Install a chart
helm oci install <name> <release> [--version <version>] [helm flags...]
helm oci install envoy-gw my-gateway --version 1.3.0 --namespace envoy --create-namespace

# Upgrade a release
helm oci upgrade <name> <release> [--version <version>] [helm flags...]
helm oci upgrade envoy-gw my-gateway --version 1.4.0

# Render templates locally
helm oci template <name> <release> [--version <version>] [helm flags...]
helm oci template envoy-gw my-gateway --version 1.3.0 --set foo=bar

# Pull chart archive to local directory
helm oci pull <name> [--version <version>]

All flags after the bookmark name and release name are passed through directly to the underlying helm command. Any flag that helm install, helm upgrade, etc. accept will work — --set, --values, --namespace, --create-namespace, --wait, and so on.

Bookmark Storage

Bookmarks are stored in $HELM_DATA_HOME/oci-bookmarks.yaml. The default location is:

• macOS: ~/Library/helm/oci-bookmarks.yaml
• Linux: ~/.local/share/helm/oci-bookmarks.yaml

The file is plain YAML:

bookmarks:
  - name: envoy-gw
    url: oci://docker.io/envoyproxy/gateway-helm
  - name: cert-manager
    url: oci://quay.io/jetstack/cert-manager

Development

Requires Go 1.22+.

make build      # Build binary to bin/helm-oci
make test       # Run all tests with race detector
make install    # Build and install into Helm plugins directory
make uninstall  # Remove from Helm plugins directory
make dist       # Cross-compile release archives