Skip to content

Helm Integration Guide

OrbitRepos provides a robust Helm chart repository interface compatible with the ChartMuseum API. It allows you to manage Kubernetes application packages with ease, supporting hosted private charts, proxying upstream repositories, and aggregating multiple sources into virtual groups.

Overview

By using OrbitRepos as your Helm chart repository, you gain a centralized hub for your Kubernetes deployments. Key features include:

  • Hosted Repositories: Securely store and version your internal Helm charts.
  • Proxy Repositories: Cache charts from public repositories (e.g., Bitnami) to improve build speeds and reliability.
  • Group Repositories: Combine multiple repositories under a single URL for simplified client configuration.
  • Automatic Indexing: OrbitRepos automatically maintains the index.yaml file as charts are uploaded or deleted.

The Helm handler is served at the /helm/{repoName}/ route.

Prerequisites

Before you begin, ensure you have the following:

  • Helm CLI installed (v3.0+ recommended).
  • An active OrbitRepos instance. See the Quick Start for setup instructions.
  • Network access to http://localhost:8080.
  • The helm-push plugin for uploading charts (optional but recommended): 
    helm plugin install https://github.com/chartmuseum/helm-push

Create a Repository

You can create a Helm repository via the Web UI or the Management API.

  1. Log in to OrbitRepos (default: admin/admin).
  2. Navigate to Repositories > Create Repository.
  3. Select Helm as the format.
  4. Choose a type: hosted, proxy, or group.
  5. Name it my-charts (for this guide).
  6. Click Create.
curl -u admin:admin -X POST http://localhost:8080/api/v1/repositories \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-charts",
    "format": "helm",
    "type": "hosted"
  }'

Push / Publish Artifacts

To publish charts to a hosted repository, you first package your chart and then upload the resulting .tgz file.

1. Package the Chart

Navigate to your chart's directory and run: 

helm package ./my-app
This creates a file like my-app-0.1.0.tgz.

2. Upload the Chart

OrbitRepos supports multiple ways to upload charts.

The easiest way to upload is using the helm push plugin: 

helm repo add my-charts http://localhost:8080/helm/my-charts/ --username admin --password admin
helm push my-app-0.1.0.tgz my-charts

You can also use a simple POST request to the repository endpoint: 

curl -u admin:admin --data-binary "@my-app-0.1.0.tgz" http://localhost:8080/helm/my-charts/api/charts

Metadata Extraction

Upon upload, OrbitRepos automatically extracts the Chart.yaml metadata to populate the repository index and UI.

Pull / Install Artifacts

To install charts from OrbitRepos, add the repository to your Helm configuration.

1. Add the Repository

helm repo add orbit-hosted http://localhost:8080/helm/my-charts/ --username admin --password admin
helm repo update

2. Search and Install

# Search for charts
helm search repo orbit-hosted

# Install a chart
helm install my-release orbit-hosted/my-app

Proxy Setup

A proxy repository allows you to cache charts from an upstream repository locally. This is highly recommended for public repositories to ensure availability during upstream outages.

  1. Create a new repository with type proxy.
  2. Set the Remote URL to an upstream repository (e.g., https://charts.bitnami.com/bitnami).
  3. Add the proxy repository to your Helm CLI: 
    helm repo add orbit-bitnami http://localhost:8080/helm/bitnami-proxy/
  4. When you pull a chart through this URL, OrbitRepos fetches it from Bitnami, stores it in the local cache, and serves it to you.

Aggregation

Use a group repository to merge your my-charts (hosted) and bitnami-proxy (proxy). This allows you to use a single URL for all your Kubernetes deployment needs.

Troubleshooting

Issue Cause Resolution
401 Unauthorized Missing or incorrect credentials. Verify your username and password or API token.
404 Not Found Repository name or chart name misspelled. Verify the URL and repository name in the Web UI.
helm push fails helm-push plugin not installed. Install the plugin using helm plugin install.
index.yaml out of date Background indexing task delayed. Wait a few seconds or trigger a manual re-index via API.
Connection Refused OrbitRepos is not reachable. Ensure the service is running and localhost:8080 is accessible.

Plugin Compatibility

OrbitRepos implements the ChartMuseum API. While standard helm commands work for installation, the helm push command specifically requires the helm-push (also known as chartmuseum-push) plugin.