Helm

Helm reference: chart lifecycle, Kubernetes authentication, release tracking, and input/output

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.

Feature

Details

Kubernetes integration

Deploy to any connected EKS, GKE, AKS, or on-prem cluster

Chart management

Support for local charts and remote/OCI chart dependencies

Release lifecycle

Install, upgrade, and uninstall operations with --wait

Values injection

Props and secrets are merged into Helm values at runtime

For a complete guide to how inputs and outputs work across all IaC tools, see Inputs & Outputs.

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

Field

Required

Description

type

Yes

"helm"

path

Yes

Directory containing Chart.yaml and templates

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: 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

If you use umbrella charts (sub-chart dependencies), run helm dependency build before publishing via CLI.

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:

Navigate to your chart directory:
```
cd ~/my-helm-chart
```

Run blueprint prepare:

# 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

Publish the package:
```
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:

# 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.

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:

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.

Auto-generated Helm outputs are coming soon.

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

Operation

What happens

Notes

Plan

Dry-run, diffs rendered manifests against the live cluster, lists resources to create/update/delete

Orphaned live resources not yet surfaced in diff

Apply

Installs or upgrades the chart using --wait

Waits for resources to be ready

Plan Destroy

Dry-run uninstall to preview all managed resources

Apply Destroy

Uninstalls the release and deletes all managed resources

Release management

Release naming

Field

Default

Override

Release name

Chart.yaml → name

native.releaseName

Namespace

default

native.namespace (created if absent)

If multiple artifacts reuse the same chart, set a custom releaseName to avoid collisions.

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 for details

Cluster integration

Bluebricks leverages cloud provider CLIs for Kubernetes authentication:

Provider

CLI Command

EKS

aws eks update-kubeconfig --region region-code --name my-cluster

GKE

gcloud container clusters get-credentials CLUSTER_NAME --location=LOCATION

AKS

az aks get-credentials --resource-group RESOURCE_GROUP --name CLUSTER_NAME

On-prem

Service-account token in kubeconfig (if exists)

No kubeconfig needs to live inside the artifact.

Umbrella charts

Manage sub-charts in Chart.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