Using Helm Charts with ConfigHub

This howto will walk you through using cub helm commands to manage Helm charts as ConfigHub units. You'll learn how to install charts, preserve customizations during upgrades, and work with popular Kubernetes operators.

Why Use Helm with ConfigHub?

When you use cub helm install, ConfigHub renders your Helm charts into Config Units. This gives you:

Full revision history of all chart deployments
Ability to review changes before applying
Preserved customizations during chart upgrades
ConfigHub's powerful query and bulk modification capabilities

Under the hood, cub helm commands use helm template to render charts locally. This means no Tiller or Helm server is required - charts are rendered directly to pure Kubernetes YAML, giving you full control over the rendered output before deployment. This approach works with any Helm v3 chart and ensures that what you see in ConfigHub is exactly what will be deployed to your cluster.

Getting Started with cub helm

Install a Helm Chart

The basic pattern for installing any Helm chart is:

cub helm install <release-name> \
    <repo>/<chart> \
    --space $SPACE \
    --namespace <namespace>

This command will create 1 or 2 units in ConfigHub:

<release>: The main resources of the chart and a namespace definition resource if namespace is specified
<release>-crds: Custom Resource Definitions if any exists in the chart

Let's install cert-manager as an example:

# Add the Helm repository
helm repo add jetstack https://charts.jetstack.io --force-update

# Install cert-manager
cub helm install cert-manager \
  jetstack/cert-manager \
  --space $SPACE \
  --namespace cert-manager \
  --version v1.17.2

Check what was created:

cub unit list \
  --space $SPACE \
  --where "Labels.helmrelease = 'cert-manager'"

Make Customizations

A key aspect of using ConfigHub with Helm is to not make customizations in the resource units created by the cub helm commands. Instead you make your changes in a clone. For example, if you installed cert-manager as above, you clone the cert-manager unit with:

cub unit create cert-manager-dev --upstream-unit cert-maanger

You can name your cloned unit anything you want. You can also clone all units in a space to another space:

cub unit create --dest-space $CLONEDSPACE --space $SPACE

In this case, the cloned units will have the same name as their upstream units.

Once you have a cloned unit, you can now edit it and make your customizations, e.g. in the case of cert-manager-dev:

cub unit edit cert-manager-dev --space $SPACE

For example, you might add resource limits or change replica counts. These changes are preserved when you upgrade the chart later.

Upgrade a Chart

When a new chart version is available:

cub helm upgrade cert-manager jetstack/cert-manager \
  --space $SPACE \
  --namespace cert-manager \
  --version v1.17.3

This updates only the cert-manager and cert-manager-crds units. Your customizations in cert-manager-dev remain untouched. To incorporate the upstream changes:

cub unit update cert-manager-dev --space $SPACE --upgrade

For detailed examples with popular charts like cert-manager, Prometheus, and others, see Working with Popular Charts below.

Configuration and Customization

Using Values Files

Create a values file for your configuration:

# cert-manager-values.yaml
installCRDs: true
replicaCount: 3
webhook:
  replicaCount: 3
prometheus:
  enabled: true
  servicemonitor:
    enabled: true

Install with values:

cub helm install cert-manager jetstack/cert-manager \
  --space $SPACE \
  --namespace cert-manager \
  --values cert-manager-values.yaml

Multiple Values Files

Later files override earlier ones:

cub helm install myapp bitnami/nginx \
  --space $SPACE \
  --values base-values.yaml \
  --values prod-values.yaml \
  --set replicaCount=5  # This overrides everything

Managing CRDs

Control how CRDs are handled:

# Skip CRDs entirely
cub helm install myapp repo/chart --skip-crds

# Update CRDs during upgrade (default is false)
cub helm upgrade myapp repo/chart --update-crds

Namespace Management

While cub helm install can automatically render a namespace resource and assign the namespace to the other rendered resources in a chart, this is not always what you want.

In many cases, you want to manage the creation and configuration of the namespace in a different place and assign the resources to the namespace at a later point.

ConfigHub supports this using a special placeholder string confighubplaceholder. You can render a chart in this way by simply omitting the --namespace flag:

cub helm install cert-manager jetstack/cert-manager \
  --space $SPACE \

Now, the namespace resource will not be added and all the namespaced resources will have confighubplaceholder as the namespace value. Next, you can clone this base resource to a dev and prod unit:

cub unit create cert-manager-dev --upstream-unit cert-maanger
cub unit create cert-manager-prod --upstream-unit cert-maanger

Then you associate each of these with their own namespace unit:

cub link create cert-manager-dev-to-dev-ns cert-manager-dev dev-ns --space $SPACE
cub link create cert-mananger-prod-to-prod-ns cert-manager-prod prod-ns --space $SPACE

This assumes that dev-ns and prod-ns are existing ConfigHub units that define a namespace resource and perhaps other configuration such as role bindings and other access controls.

Once you create these links, cert-manager-dev and cert-manager-prod are automatically updated and the correct namespace is inserted into all resources in the units. The mechanism responsible for doing this is called Needs/Provides.

Benefits of Using Placeholders

Dynamic Namespace Assignment: You can deploy the same config unit to different namespaces without re-rendering:

# Install once with placeholder
cub helm install myapp repo/chart --namespace prod

# Later, link to different namespace units
cub link create myapp-to-dev myapp dev-ns --space $SPACE
cub link create myapp-to-staging myapp staging-ns --space $SPACE

Namespace Consistency: When you link a unit to a namespace unit, ConfigHub automatically replaces all confighubplaceholder occurrences with the actual namespace name from the linked namespace unit.
Multi-Environment Flexibility: One base configuration can serve multiple environments:

# Create base with placeholder
cub helm install redis bitnami/redis --namespace cache

# Clone for different environments
cub unit create redis-dev --upstream-unit redis-base --space $SPACE
cub unit create redis-prod --upstream-unit redis-base --space $SPACE

# Link to appropriate namespaces
cub link create redis-dev-ns redis-dev cache-dev-ns --space $SPACE
cub link create redis-prod-ns redis-prod cache-prod-ns --space $SPACE

Potential Pitfalls

Hardcoded Namespace Values: Some charts have hardcoded namespace references in ConfigMaps or Secrets which would be rendered, for example, like this:

# ConfigMap with hardcoded reference
apiVersion: v1
kind: ConfigMap
metadata:
  namespace: confighubplaceholder
data:
  config.yaml: |
    webhook:
      url: http://webhook.confighubplaceholder.svc.cluster.local

For charts with hardcoded namespace references in values, you have two options:

Use --use-placeholder=false to render with actual namespace values
After installation, use cub unit edit to manually update the URLs with proper namespace references or use ConfigHub's string replacement features

Apply Gate Enforcement: If you have a no-placeholders trigger, units with placeholders cannot be applied until properly linked:

# This will fail if no-placeholders trigger exists
cub unit apply myapp --space $SPACE
# Error: Apply gate 'complete/no-placeholders' prevents apply

When to Disable Placeholders

Use --use-placeholder=false when:

Single-Namespace Deployment: The chart will only ever run in one specific namespace
Complex Namespace References: The chart has complex namespace references in some values.
Quick Testing: You want to apply immediately without linking

The following example will be always rendered namespace value as monitoring without using confighubplaceholder.

# Render with actual namespace
cub helm install monitoring prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --use-placeholder=false \
  --space $SPACE

# Can apply immediately without linking
cub unit apply monitoring --space $SPACE

Troubleshooting

Chart Not Found

If you get "failed to locate chart", ensure the repository is added:

helm repo list
helm repo add <name> <url>
helm repo update

CRDs Not Created

Some charts control CRD installation with values:

# cert-manager example
cub helm install cert-manager jetstack/cert-manager \
  --set installCRDs=true

# Or check if you're skipping CRDs
cub helm install myapp repo/chart  # Don't use --skip-crds

Customizations Lost

Ensure you're editing the clone unit, not the base:

# Correct - edit the clone
cub unit edit myapp

# Wrong - editing base (will be overwritten on upgrade)
cub unit edit myapp-base

Working with Popular Charts

cert-manager - Certificate Management

cert-manager automates TLS certificate management in Kubernetes.

# Install with CRDs
cub helm install cert-manager jetstack/cert-manager \
  --space $SPACE \
  --namespace cert-manager \
  --version v1.17.2

# Apply in order
cub unit apply cert-manager-crds --space $SPACE

# Wait for CRDs to be ready
kubectl wait --for condition=established --timeout=60s \
  crd/certificates.cert-manager.io \
  crd/issuers.cert-manager.io \
  crd/clusterissuers.cert-manager.io

# Apply the main resources
cub unit apply cert-manager --space $SPACE

External Secrets Operator

Sync secrets from external systems like AWS Secrets Manager or HashiCorp Vault.

# Add repository
helm repo add external-secrets https://charts.external-secrets.io --force-update

# Install
cub helm install external-secrets external-secrets/external-secrets \
  --space $SPACE \
  --namespace external-secrets \
  --version 0.16.2

# Apply units
cub unit apply external-secrets-crds --space $SPACE
cub unit apply external-secrets --space $SPACE

Prometheus Stack - Complete Monitoring

Deploy Prometheus, Grafana, and Alertmanager together.

# Add repository
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts --force-update

# Create values file to disable components you don't need
cat > prometheus-values.yaml <<EOF
grafana:
  enabled: true
prometheus:
  prometheusSpec:
    retention: 30d
    storageSpec:
      volumeClaimTemplate:
        spec:
          accessModes: ["ReadWriteOnce"]
          resources:
            requests:
              storage: 50Gi
EOF

# Install with custom values
cub helm install prom prometheus-community/kube-prometheus-stack \
  --space $SPACE \
  --namespace prometheus \
  --version 72.3.0 \
  --values prometheus-values.yaml

Traefik - Modern Load Balancer

helm repo add traefik https://traefik.github.io/charts --force-update

cub helm install traefik traefik/traefik \
  --space $SPACE \
  --namespace traefik \
  --set service.type=LoadBalancer

Flux - GitOps for Kubernetes

helm repo add fluxcd-community https://fluxcd-community.github.io/helm-charts --force-update

cub helm install flux fluxcd-community/flux2 \
  --space $SPACE \
  --namespace flux-system

Summary

The cub helm commands give you the best of both worlds: the vast ecosystem of Helm charts with ConfigHub's powerful configuration management. By following the clone-based deployment pattern, you can safely upgrade charts while preserving your customizations, making it ideal for production environments.