Lesson 8 of 8 in Kubernetes

Helm and GitOps: packaging and automating deploys

Advanced14 min

Helm packages Kubernetes manifests as a chart with templates and values, and tracks each install as a release you can upgrade or roll back. GitOps tools such as Argo CD and Flux keep a cluster in sync with manifests stored in Git.

Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.

Read these first: Deployments: replicas, rollouts and rollbacks, ConfigMaps and Secrets: settings outside the image

The problem this solves

Real apps need many objects, and you need slightly different values in each environment: replicas, image tags, host names. Copying YAML files and editing them by hand drifts quickly, and nobody can say which version is live.

Helm turns the YAML into templates with a values file, and records every install as a numbered release. GitOps goes one step further. The wanted state lives in Git, and an agent inside the cluster pulls it and applies it, so every change is a reviewed commit and the cluster does not depend on someone running kubectl.

How it works

How Helm builds and installs a release
How Helm builds and installs a releaseHelm combines the chart's templates with your values, produces plain manifests, and sends them to the cluster.1 templates2 your values3 renderedYAMLCharttemplates and defaultsYour values--set or values filehelmrenders the templatesClustera numbered release
  • Data
  • Control
  • Runs code

Helm combines the chart's templates with your values, produces plain manifests, and sends them to the cluster.

  1. Chart to helm: 1 templates
  2. Your values to helm: 2 your values
  3. helm to Cluster: 3 rendered YAML
The GitOps loop
The GitOps loopYou push a change to Git, an agent in the cluster pulls the repository, compares it with the live cluster and applies the difference.1 merge achange2 pull andcompare3 apply the differenceYouopen a pull requestGit repothe wanted stateArgo CD or Fluxruns in the clusterClusterthe live state
  • People and clients
  • Data
  • Control
  • Runs code

You push a change to Git, an agent in the cluster pulls the repository, compares it with the live cluster and applies the difference.

  1. You to Git repo: 1 merge a change
  2. Argo CD or Flux to Git repo: 2 pull and compare
  3. Argo CD or Flux to Cluster: 3 apply the difference

A chart is a folder with templates, a values.yaml of defaults and a Chart.yaml describing it. helm template shows the plain YAML a chart would produce without touching the cluster. helm install sends it, and Helm saves a record of the release in the cluster. Each helm upgrade adds a revision, and helm rollback reapplies an earlier one.

GitOps uses the same reconcile idea from the first concept, applied to Git. The Git repository is the wanted state. Argo CD and Flux are controllers that run in the cluster, pull from Git and compare. If someone edits the cluster by hand, the tool reports the difference, and when self-healing is on, it reverts the change.

The two work together. A Git repo can hold a Helm chart or plain manifests, and the GitOps tool renders and applies them. Push access to the repo then controls who can change production.

Try it yourself

Install Helm from its official page. Use a throwaway folder. helm create makes a working demo chart locally, so you need no chart repository.

  1. 1
    Create and check a chart
    mkdir helm-demo && cd helm-demo
    helm create demo
    helm lint demo

    helm create generates a small nginx chart with templates and a values.yaml.

  2. 2
    Render it without installing
    helm template demo ./demo --set replicaCount=2 | head -60

    Find the Deployment in the output and check that replicas is 2. Nothing has touched the cluster yet.

  3. 3
    Install a release
    helm install demo ./demo
    helm list
    kubectl get pods

    The release is named demo. Wait for the Pod to be Running.

  4. 4
    Upgrade, inspect and roll back
    helm upgrade demo ./demo --set replicaCount=2
    helm history demo
    helm rollback demo 1
    helm history demo

    Rolling back creates a new revision that reuses the settings of revision 1.

  5. 5
    Clean up
    helm uninstall demo
    cd .. && rm -r helm-demo

    GitOps tools like Argo CD and Flux run in the cluster and take more setup. Their install guides are the next step once you are comfortable with Helm.

What breaks, and where to look

  • Error: INSTALLATION FAILED: cannot re-use a name that is still in use.

    WHY IT HAPPENS
    A release with that name already exists in the namespace, often from an earlier try.
    CHECK FIRST
    Run helm list -A to find it. Use helm upgrade --install <name> <chart> to update it, or helm uninstall <name> first.
  • Error: YAML parse error on demo/templates/deployment.yaml: error converting YAML to JSON.

    WHY IT HAPPENS
    A template rendered invalid YAML, usually because of wrong indentation after a value, or a missing quote or nindent.
    CHECK FIRST
    Run helm template <name> <chart> and read the rendered output around the error, or helm lint <chart>, before you install anything.
  • Argo CD or Flux shows the app OutOfSync, or silently reverts a change you made with kubectl edit.

    WHY IT HAPPENS
    The cluster no longer matches Git. The agent treats Git as the truth, so it reports the drift and, with self-heal on, undoes manual edits.
    CHECK FIRST
    Make the change in Git instead. To see the difference, use the tool's diff view, for example argocd app diff <app-name> in Argo CD.

When not to use this

  • For one small app with a few files, plain manifests or Kustomize can be simpler than a chart. Templates add indentation errors and a layer to debug.
  • A GitOps agent can only reach what is in Git. Keep Secrets out of the repo and use a sealed or external secret tool, since a Git history keeps everything forever.

Check yourself

What is a Helm release?

One named installation of a chart in a cluster. Each upgrade adds a numbered revision that you can roll back to.

How can you see the YAML a chart would apply without changing the cluster?

helm template <name> <chart>, optionally with --set or -f values.yaml.

In GitOps, what happens if you edit a live object by hand?

The agent sees the cluster differs from Git, reports it as out of sync and may revert it, because Git is the source of truth.

Lesson 77 of 92 in the DevOps path

Search

Search cheat sheets and projects