Skip to content
Hands-on IT IT Drills

Day 7: Helm Provider – Postgres and notes as a Chart

Goal: Install Helm charts with OpenTofu: the Postgres operator CloudNativePG, a database as a cluster, and notes as its own chart – connected through the Secret the operator creates. · Duration: approx. 90 min · Prerequisite: Day 6

Briefing

  • The Helm provider installs charts like helm install, but with plan and state: helm_release with repository, chart, version, and values.
  • It’s best to pass values as values = [yamlencode({ … })]: HCL maps become YAML, and variables and references go straight in.
  • CloudNativePG is an operator for Postgres in Kubernetes. A Cluster resource describes the database; the operator creates pods, volumes, services, and a Secret with the ready-made connection URL.
  • The operator brings its own resource types (CRDs). Anything that uses such a type depends on the operator – depends_on makes that visible.
 helm_release.cnpg  (operator, namespace cnpg-system)
   └─► helm_release.db    (chart "cluster" → Cluster notes-db-cluster, Secret …-app)
         └─► helm_release.notes (own chart, NOTES_DB_URL from Secret …-app/uri)
                └─► http://notes-helm.<VM_IP>.sslip.io

Drill 1: The Operator

mkdir -p ~/tf-lab/tag07 && cd ~/tf-lab/tag07
cat > versions.tf <<'EOF'
terraform {
  required_version = ">= 1.13.0"
  required_providers {
    helm = {
      source  = "hashicorp/helm"
      version = "~> 3.3"
    }
  }
}

provider "helm" {
  kubernetes = {
    config_path = "/etc/rancher/k3s/k3s.yaml"
  }
}
EOF
cat > operator.tf <<'EOF'
resource "helm_release" "cnpg" {
  name             = "cnpg"
  repository       = "https://cloudnative-pg.github.io/charts"
  chart            = "cloudnative-pg"
  version          = "0.29.1"
  namespace        = "cnpg-system"
  create_namespace = true
  wait             = true
}
EOF
tofu init -no-color | grep -E 'Installed|initialized'
tofu apply -auto-approve -no-color | grep -E 'Apply complete'
kubectl -n cnpg-system get deployments
kubectl get crd -o name | grep -c 'postgresql.cnpg.io'

Expected (age differs):

- Installed hashicorp/helm v3.3.0 (signed, key ID 0C0AF313E5FD9F80)
OpenTofu has been successfully initialized!
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
NAME                  READY   UP-TO-DATE   AVAILABLE   AGE
cnpg-cloudnative-pg   1/1     1            1           40s
11
  • In version 3 of the Helm provider, kubernetes is an attribute with =, not a block – older examples on the web still show kubernetes { … }.
  • wait = true waits until all pods of the chart are ready. After that, the eleven new resource types exist, among them clusters.postgresql.cnpg.io.

Save your progress? Sign up for free

Drill 2: A Database

cat > db.tf <<'EOF'
resource "helm_release" "db" {
  name             = "notes-db"
  repository       = "https://cloudnative-pg.github.io/charts"
  chart            = "cluster"
  version          = "0.9.0"
  namespace        = "notes-helm"
  create_namespace = true
  values = [yamlencode({
    type = "postgresql"
    cluster = {
      instances = 1
      storage   = { size = "1Gi" }
    }
  })]
  depends_on = [helm_release.cnpg]
}

locals {
  db_secret = "${helm_release.db.name}-cluster-app"
}
EOF
tofu apply -auto-approve -no-color | grep -E 'Apply complete'
kubectl -n notes-helm wait cluster/notes-db-cluster --for=condition=Ready --timeout=300s
kubectl -n notes-helm get secret notes-db-cluster-app -o jsonpath='{.data.uri}' \
  | base64 -d; echo

Expected (after one to two minutes; the password is random and longer):

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
cluster.postgresql.cnpg.io/notes-db-cluster condition met
postgresql://app:kbdPex8sZQv5…@notes-db-cluster-rw.notes-helm:5432/app
  • The cluster chart only creates the Cluster resource and is done immediately; the actual work is then done by the operator. kubectl wait waits for it.
  • The Secret notes-db-cluster-app contains user, password, and under uri the ready-made connection URL. The operator generated the password – it appears nowhere in the code and not in OpenTofu’s state.
  • local.db_secret derives the name from the release. If someone changes the release’s name, the Secret follows.

Save your progress? Sign up for free

Drill 3: notes as Its Own Chart

The companion code contains a small chart for notes:

ls ~/tf-lab/code/charts/notes ~/tf-lab/code/charts/notes/templates
grep -A3 'secretKeyRef' ~/tf-lab/code/charts/notes/templates/deployment.yaml | head -4

Expected:

/home/ubuntu/tf-lab/code/charts/notes:
Chart.yaml
templates
values.yaml

/home/ubuntu/tf-lab/code/charts/notes/templates:
deployment.yaml
ingress.yaml
secret.yaml
service.yaml
                secretKeyRef:
                  name: {{ .Values.db.secretName }}
                  key: uri
      {{- end }}

An init container runs notes-api migrate before every start; both read the URL from the Secret whose name is passed in as a value.

cat > notes.tf <<'EOF'
variable "vm_ip" {
  type = string
}

resource "helm_release" "notes" {
  name      = "notes"
  chart     = "${pathexpand("~")}/tf-lab/code/charts/notes"
  namespace = "notes-helm"
  values = [yamlencode({
    replicas = 1
    db       = { secretName = local.db_secret }
    host     = "notes-helm.${var.vm_ip}.sslip.io"
  })]
}

output "url" {
  value = "http://notes-helm.${var.vm_ip}.sslip.io"
}
EOF
export TF_VAR_vm_ip=$VM_IP
tofu apply -auto-approve -no-color | grep -E 'Apply complete'
U=$(tofu output -raw url)
curl -s -X POST -H "X-API-Key: $NOTES_API_KEY" -H 'Content-Type: application/json' \
  -d '{"text":"in Postgres auf k3s"}' "$U/notes" | jq -r .text
kubectl -n notes-helm get pods

Expected (pod names and age differ):

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
in Postgres auf k3s
NAME                     READY   STATUS    RESTARTS   AGE
notes-5fbc5f7cf9-65kvp   1/1     Running   0          20s
notes-5fbc5f7cf9-fhs9z   1/1     Running   0          20s
notes-db-cluster-1       1/1     Running   0          2m

A chart from a local folder doesn’t need a repository. pathexpand("~") turns ~ into the home directory – OpenTofu itself doesn’t understand ~.

Save your progress? Sign up for free

Drill 4: Changing Values

sed -i 's/^    replicas = 1$/    replicas = 2/' notes.tf
tofu plan -no-color | grep -E '[-+] +"replicas"|Plan:'
tofu apply -auto-approve -no-color | grep -E 'Apply complete'
kubectl -n notes-helm get deployment notes -o jsonpath='{.status.readyReplicas}'; echo
kubectl -n notes-helm get secrets -l owner=helm,name=notes --no-headers | wc -l

Expected:

              - "replicas": 1
              + "replicas": 2
Plan: 0 to add, 1 to change, 0 to destroy.
Apply complete! Resources: 0 added, 1 changed, 0 destroyed.
2
2

The plan shows the difference in the YAML that yamlencode generates – with quotes around every key. Helm stores every version of a release in a Secret – after the upgrade there are two. A rollback with helm rollback would bypass OpenTofu; the right way back is the old value in the code and a new apply.

Save your progress? Sign up for free

Drill 5: New Chart Version

The chart version in the code changes – OpenTofu sees it from the folder’s contents:

sed -i 's/^version: 1.0.0$/version: 1.1.0/' ~/tf-lab/code/charts/notes/Chart.yaml
tofu plan -no-color | grep -E '^      ~ version|Plan:'
tofu apply -auto-approve -no-color | grep -E 'Apply complete'
tofu state show helm_release.notes | grep -E '^ +(version|status) +='

Expected:

      ~ version                    = "1.0.0" -> "1.1.0"
Plan: 0 to add, 1 to change, 0 to destroy.
Apply complete! Resources: 0 added, 1 changed, 0 destroyed.
    status                     = "deployed"
    version                    = "1.1.0"

For a chart from a repository, the version is in the code as version = "…"; a new chart then only arrives when you change it.

Save your progress? Sign up for free

Checkpoint

curl -s "$(tofu output -raw url)/notes" | jq -r '.[].text'

Expected:

in Postgres auf k3s
tofu state list

Expected:

helm_release.cnpg
helm_release.db
helm_release.notes
kubectl -n notes-helm get cluster notes-db-cluster -o jsonpath='{.status.phase}'; echo

Expected:

Cluster in healthy state

Challenge

The values for notes should come from a file notes-values.yaml.tftpl so that someone without HCL knowledge can read them too. Afterwards, the plan must not show any change.

Hint: values = [templatefile("…", { … })].

Solution

cat > notes-values.yaml.tftpl <<'EOF'
replicas: 2
db:
  secretName: ${db_secret}
host: notes-helm.${vm_ip}.sslip.io
EOF
python3 - <<'PY'
import re
s = open("notes.tf").read()
s = re.sub(r"values = \[yamlencode\(\{.*?\}\)\]",
           'values = [templatefile("${path.module}/notes-values.yaml.tftpl", {\n'
           '    db_secret = local.db_secret\n    vm_ip     = var.vm_ip\n  })]',
           s, flags=re.S)
open("notes.tf", "w").write(s)
PY
tofu fmt >/dev/null
gen=$(kubectl -n notes-helm get deployment notes -o jsonpath='{.metadata.generation}')
tofu plan -no-color | grep -E 'Plan:|No changes'
tofu apply -auto-approve -no-color | grep -E 'Apply complete'
neu=$(kubectl -n notes-helm get deployment notes -o jsonpath='{.metadata.generation}')
[[ $gen == "$neu" ]] && echo "Deployment unverändert"

Expected:

Plan: 0 to add, 1 to change, 0 to destroy.
Apply complete! Resources: 0 added, 1 changed, 0 destroyed.
Deployment unverändert

OpenTofu compares the text of the values: yamlencode writes "replicas": 2, the template replicas: 2. That’s why it plans a change. Helm renders the same manifests from both – the Deployment stays untouched; only a new release version is created. Watch the indentation in templates: YAML doesn’t forgive wrong spacing.

Save your progress? Sign up for free

Enterprise Note

  • Pin versions: Charts without version install whatever is newest – an apply after a few weeks can then bring a major upgrade.
  • CRDs and operators belong in a separate configuration that runs before the applications. Resources via kubernetes_manifest need the CRDs already at plan time; in the same configuration as the operator, the first run fails.
  • OpenTofu or GitOps? Many teams install platform components (operators, ingress, monitoring) with OpenTofu and applications with Argo CD or Flux.