# Helm

## Overview

Helm artifacts let you deploy and manage Kubernetes applications using standard Helm charts while leveraging Bluebricks' orchestration and environment automation. By packaging your Helm chart as an artifact, you can centralize configuration, apply collection-specific values, and streamline release operations across clusters.

<table><thead><tr><th width="219.7265625">Feature</th><th>Details</th></tr></thead><tbody><tr><td><strong>Kubernetes integration</strong></td><td>Deploy to any connected EKS, GKE, AKS, or on-prem cluster</td></tr><tr><td><strong>Chart management</strong></td><td>Support for local charts and remote/OCI chart dependencies</td></tr><tr><td><strong>Release lifecycle</strong></td><td>Install, upgrade, and uninstall operations with <code>--wait</code></td></tr><tr><td><strong>Values injection</strong></td><td>Props and secrets are merged into Helm values at runtime</td></tr></tbody></table>

For a complete guide to how inputs and outputs work across all IaC tools, see [Inputs & Outputs](/docs/orchestration/packages/inputs-and-outputs.md).

## Required files and directory structure

A Helm artifact requires a standard Helm chart structure in the directory specified by `native.path`:

```
my-helm-artifact/
├── bricks.json              # Artifact manifest
└── chart/                   # native.path points here
    ├── Chart.yaml           # Chart metadata (required)
    ├── values.yaml          # Default values
    ├── templates/           # Kubernetes manifest templates
    │   ├── deployment.yaml
    │   ├── service.yaml
    │   └── _helpers.tpl
    └── charts/              # Sub-chart dependencies (optional)
```

The `native.path` field in `bricks.json` must point to the directory containing `Chart.yaml`.

## bricks.json reference

<table><thead><tr><th width="92.49609375">Field</th><th width="112.31640625">Required</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>type</code></strong></td><td>Yes</td><td><code>"helm"</code></td></tr><tr><td><strong><code>path</code></strong></td><td>Yes</td><td>Directory containing <code>Chart.yaml</code> and templates</td></tr></tbody></table>

## How to create this artifact

The only requirement is a directory with a valid Helm chart (`Chart.yaml`). If you can run `helm install` from it, Bluebricks can use it as-is. Bluebricks handles values injection, release management, and cluster authentication for you.

You can create a Helm artifact in two ways:

* **In the Bluebricks app** during [blueprint creation](/docs/orchestration/packages/blueprints-overview/creating-blueprints.md): select your repository and the directory containing `Chart.yaml`, and Bluebricks generates the artifact automatically
* **Via CLI**: use the `bricks blueprint prepare` workflow described below

{% hint style="info" %}
If you use umbrella charts (sub-chart dependencies), run `helm dependency build` before publishing via CLI.
{% endhint %}

### Create a Helm artifact via CLI

**Prerequisites:**

* Bluebricks CLI installed and authenticated (`bricks login`)
* An existing Helm chart with `Chart.yaml` and `values.yaml`

**Steps:**

1. **Navigate to your chart directory:**

   ```bash
   cd ~/my-helm-chart
   ```
2. **Run blueprint prepare:**

   ```bash
   # Option 1: In-place (keeps original files)
   bricks blueprint prepare --source . --iac-type helm

   # Option 2: With output directory (copies files to src/helm/)
   bricks blueprint prepare --source . --output ./dist --iac-type helm
   ```
3. **Publish the package:**

   ```bash
   bricks blueprint publish
   ```

**Example directory structure:**

Before:

```
my-helm-chart/
├── Chart.yaml
├── values.yaml
└── templates/
    ├── deployment.yaml
    └── service.yaml
```

After (with output directory):

```
my-helm-chart/
├── bricks.json          # Generated metadata
└── src/
    └── helm/            # Your files (copied)
        ├── Chart.yaml
        ├── values.yaml
        └── templates/
```

After (in-place, no output directory):

```
my-helm-chart/
├── bricks.json          # Generated metadata
├── Chart.yaml           # Original files remain
├── values.yaml
└── templates/
```

### Test locally

Verify your Helm package works correctly before publishing:

```bash
# Dry run (plan only)
bricks run . --dry

# With custom properties
bricks run . --dry --props-file properties.json
```

The dry run shows you exactly what Helm will deploy without making any changes to your cluster.

***

> The sections below explain how Bluebricks maps your code to inputs, outputs, and operations under the hood. Everything here is optional reading. To get started, head to [Creating Blueprints](/docs/orchestration/packages/blueprints-overview/creating-blueprints.md).

## Inputs

### What becomes an input

Keys defined in `values.yaml` and any additional configuration your chart needs become props in `bricks.json`. Unlike Terraform, Helm props are not auto-discovered from `values.yaml`; you declare them explicitly in `bricks.json`.

### How inputs are delivered at runtime

All props become Helm values; secrets are merged separately and never shown in diffs.

**Example mapping:**

For example, given props `replicas`, `image_tag`, and `nodeSelector`, the resulting Helm values are:

```yaml
replicas: 3
image:
  tag: v1.2.3
nodeSelector:
  tier: frontend
```

## Outputs

### What becomes an output

Helm artifacts do not auto-generate outputs from chart execution. You must define outputs manually in `bricks.json`.

{% hint style="info" %}
Auto-generated Helm outputs are coming soon.
{% endhint %}

### Referencing outputs downstream

If you define outputs in `bricks.json`, reference them in a blueprint the same way as any other package using `Data.helm_bdc.release_name`.

## Supported operations

<table><thead><tr><th width="149.66015625">Operation</th><th>What happens</th><th>Notes</th></tr></thead><tbody><tr><td><strong>Plan</strong></td><td>Dry-run, diffs rendered manifests against the live cluster, lists resources to create/update/delete</td><td>Orphaned live resources not yet surfaced in diff</td></tr><tr><td><strong>Apply</strong></td><td>Installs or upgrades the chart using <code>--wait</code></td><td>Waits for resources to be ready</td></tr><tr><td><strong>Plan Destroy</strong></td><td>Dry-run uninstall to preview all managed resources</td><td></td></tr><tr><td><strong>Apply Destroy</strong></td><td>Uninstalls the release and deletes all managed resources</td><td></td></tr></tbody></table>

## Release management

### Release naming

<table><thead><tr><th width="157.3125">Field</th><th width="198.74609375">Default</th><th>Override</th></tr></thead><tbody><tr><td><strong>Release name</strong></td><td><code>Chart.yaml</code> → <code>name</code></td><td><code>native.releaseName</code></td></tr><tr><td><strong>Namespace</strong></td><td><code>default</code></td><td><code>native.namespace</code> (created if absent)</td></tr></tbody></table>

{% hint style="info" %}
If multiple artifacts reuse the same chart, set a custom `releaseName` to avoid collisions.
{% endhint %}

### Plan caveats

* Orphaned resources (objects removed from the chart but still present in the cluster) **do not appear** in the diff yet; they will still be deleted on apply
* CRDs in the `crds/` directory are pre-installed before chart deployment. They appear in the plan diff. See [CRD Management](/docs/orchestration/packages/artifacts-overview/helm/helm-crd-management.md) for details

## Cluster integration

Bluebricks leverages cloud provider CLIs for Kubernetes authentication:

<table><thead><tr><th width="117.86328125">Provider</th><th>CLI Command</th></tr></thead><tbody><tr><td><strong>EKS</strong></td><td><code>aws eks update-kubeconfig --region region-code --name my-cluster</code></td></tr><tr><td><strong>GKE</strong></td><td><code>gcloud container clusters get-credentials CLUSTER_NAME --location=LOCATION</code></td></tr><tr><td><strong>AKS</strong></td><td><code>az aks get-credentials --resource-group RESOURCE_GROUP --name CLUSTER_NAME</code></td></tr><tr><td><strong>On-prem</strong></td><td>Service-account token in kubeconfig (if exists)</td></tr></tbody></table>

No kubeconfig needs to live inside the artifact.

## Umbrella charts

Manage sub-charts in `Chart.yaml`:

```yaml
dependencies:
  - name: postgresql
    version: "12.1.2"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled
  - name: redis
    version: "17.3.7"
    repository: "https://charts.bitnami.com/bitnami"
    condition: redis.enabled
```

Run `helm dependency build` before publishing when using umbrella charts.

## Best practices

* Parameterize every environment-specific setting
* Provide `values.schema.json` for validation
* Add liveness and readiness probes and resource limits
* Use consistent labels and annotations for observability
* Avoid hard-coding namespaces; rely on `Release.Namespace`

## See also

* [CRD Management](/docs/orchestration/packages/artifacts-overview/helm/helm-crd-management.md): automatic CRD handling for Helm charts
* [Creating Artifacts](/docs/orchestration/packages/artifacts-overview/creating-artifacts.md): general CLI publishing workflow
* [Creating Blueprints](/docs/orchestration/packages/blueprints-overview/creating-blueprints.md): compose artifacts into blueprints


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/orchestration/packages/artifacts-overview/helm.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.