> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Helm Registries

> Connect external Helm repositories and OCI registries to Ankra for deploying custom and third-party charts.

Helm registries let you connect external Helm chart repositories to Ankra. Once connected, all charts in the registry become available as add-ons that you can deploy to your clusters through stacks.

<Note>
  Registries you add are available to your organisation. Team members can browse and deploy charts from shared registries.
</Note>

***

## Supported Registry Types

Ankra supports two types of Helm registries:

<CardGroup cols={2}>
  <Card title="HTTP Registries" icon="globe">
    Traditional Helm repositories served over HTTP/HTTPS.

    <br />

    <br />

    Examples: ChartMuseum, Harbor, Nexus
  </Card>

  <Card title="OCI Registries" icon="box">
    Container registries that support Helm charts as OCI artifacts.

    <br />

    <br />

    Examples: GHCR, Google Artifact Registry, Amazon ECR
  </Card>
</CardGroup>

***

## Adding a Registry

<Steps>
  <Step title="Navigate to Charts">
    Go to **Charts** in the main navigation, then click the **Manage Registries** button.
  </Step>

  <Step title="Click Add">
    Click the **Add** button to open the registry dialog.
  </Step>

  <Step title="Enter Registry Details">
    * **Registry Name**: A friendly name for the registry (e.g., `my-charts`)
    * **Registry URL**: The full URL to your registry
    * **Credential** (optional): Select a credential if authentication is required
  </Step>

  <Step title="Save">
    Click **Add** to connect the registry. Ankra will fetch the chart index and display available charts.
  </Step>
</Steps>

***

## Registry URL Examples

### OCI Registries

| Provider                  | URL Format                                          |
| ------------------------- | --------------------------------------------------- |
| GitHub Container Registry | `oci://ghcr.io/YOUR_ORG/charts`                     |
| Google Artifact Registry  | `oci://REGION-docker.pkg.dev/PROJECT/REPO`          |
| Amazon ECR                | `oci://ACCOUNT.dkr.ecr.REGION.amazonaws.com/charts` |
| Azure Container Registry  | `oci://YOUR_REGISTRY.azurecr.io/charts`             |
| Docker Hub                | `oci://registry-1.docker.io/YOUR_ORG`               |

### HTTP Registries

| Provider          | URL Format                                               |
| ----------------- | -------------------------------------------------------- |
| ChartMuseum       | `https://charts.example.com`                             |
| Harbor            | `https://harbor.example.com/chartrepo/PROJECT`           |
| Nexus             | `https://nexus.example.com/repository/helm-hosted/`      |
| JFrog Artifactory | `https://artifactory.example.com/artifactory/helm-local` |

<Tip>
  OCI registries use the `oci://` prefix. Ankra automatically detects the registry type based on the URL.
</Tip>

***

## Authentication

Many registries require authentication. Create a registry credential first, then select it when adding the registry.

### Creating a Registry Credential

<Steps>
  <Step title="Go to Credentials">
    Navigate to **Credentials** in the Ankra dashboard.
  </Step>

  <Step title="Add New Credential">
    Click **Add** and select **Registry** as the provider.
  </Step>

  <Step title="Enter Credentials">
    * **Name**: A name for this credential (e.g., `ghcr-auth`)
    * **Username**: Your registry username
    * **Password**: Your registry password or access token
  </Step>

  <Step title="Save">
    Click **Create** to save the credential.
  </Step>
</Steps>

### Provider-Specific Authentication

<AccordionGroup>
  <Accordion title="GitHub Container Registry (GHCR)">
    1. Create a Personal Access Token with `read:packages` scope
    2. Username: Your GitHub username
    3. Password: The Personal Access Token
  </Accordion>

  <Accordion title="Google Artifact Registry">
    1. Create a service account with Artifact Registry Reader role
    2. Username: `_json_key`
    3. Password: The JSON key file contents
  </Accordion>

  <Accordion title="Amazon ECR">
    1. Get an auth token: `aws ecr get-login-password`
    2. Username: `AWS`
    3. Password: The token from the command above

    <Warning>ECR tokens expire after 12 hours. Consider using IAM roles for long-term access.</Warning>
  </Accordion>

  <Accordion title="Docker Hub">
    1. Create an Access Token in Docker Hub settings
    2. Username: Your Docker Hub username
    3. Password: The Access Token
  </Accordion>
</AccordionGroup>

***

## Managing Registries

### View Registry Charts

Click on a registry to browse all available charts. Each chart shows:

* Chart name and description
* Latest version
* Last updated timestamp
* Keywords and maintainers

### Delete a Registry

1. Go to **Charts** and click **Manage Registries**
2. Click on the registry you want to remove
3. Click the **More** menu (⋮) and select **Delete**

<Warning>
  Deleting a registry removes it from Ankra but doesn't affect deployed add-ons. Existing deployments will continue to work.
</Warning>

***

## How Registry Sync Works

Ankra automatically syncs your registries to keep chart listings up to date.

### Sync Schedule

* **Default interval**: Every 2 minutes
* **Configurable**: Set a custom sync interval per registry (10 seconds to 24 hours)
* **Disable sync**: Set interval to 0 to disable automatic sync

### Sync Process

<Steps>
  <Step title="Check for Updates">
    Ankra checks the registry's index.yaml (HTTP) or manifest (OCI) using ETag/Last-Modified headers to avoid unnecessary downloads.
  </Step>

  <Step title="Detect New Versions">
    New chart versions are identified by comparing the index against previously synced versions.
  </Step>

  <Step title="Download Charts">
    New versions are downloaded and stored securely. Ankra extracts README, values.yaml, and JSON schema files.
  </Step>

  <Step title="Update Index">
    The chart browser is updated with new versions available for deployment.
  </Step>
</Steps>

### Version Tracking

Ankra tracks every chart version with:

* **Version number** and semantic versioning
* **Digest** for integrity verification
* **Created date** from the chart metadata
* **Deprecation status** if marked in Chart.yaml

<Tip>
  Failed version syncs are automatically retried with exponential backoff. Check the registry details page to see sync status.
</Tip>

***

## Using Registry Charts

Once a registry is connected, its charts appear in the add-on browser:

1. **Create or edit a stack**
2. **Click Add Component** → **Add-on**
3. **Browse or search** for charts from your registries
4. **Select the chart** and configure values
5. **Deploy the stack** to your cluster

Charts from your registries work exactly like built-in add-ons-they support custom values, dependencies, and GitOps sync.

***

## Troubleshooting

### Registry Not Loading

| Issue                 | Solution                                                            |
| --------------------- | ------------------------------------------------------------------- |
| Connection timeout    | Check the registry URL is accessible from Ankra                     |
| Authentication failed | Verify credentials are correct and not expired                      |
| No charts found       | Ensure the registry contains Helm charts, not just container images |
| OCI not supported     | Some registries need OCI support enabled (e.g., Harbor)             |

### Sync Issues

| Issue                 | Solution                                                        |
| --------------------- | --------------------------------------------------------------- |
| Charts not updating   | Check the sync interval hasn't been disabled (set to 0)         |
| Some versions missing | Check registry details for failed versions and retry            |
| Stale data            | Registry may have an issue serving index.yaml-verify externally |

### Common Errors

**"invalid reference format"**

* The URL format is incorrect. OCI URLs must start with `oci://`

**"unauthorized: authentication required"**

* Add or update the registry credential

**"manifest unknown"**

* The chart doesn't exist at the specified path. Check the repository structure.