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:

1. Navigate to your chart directory:

   cd ~/my-helm-chart

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

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

See also

• CRD Management: automatic CRD handling for Helm charts

• Creating Artifacts: general CLI publishing workflow

• Creating Blueprints: compose artifacts into blueprints