Skip to content
Published on

Helm Release Lifecycle: install, upgrade, rollback Internals

🇰🇷KO🇺🇸EN🇯🇵JA
Split View
Authors

1. Release Storage Structure

1.1 Release Data in Secrets

Helm manages all release revisions as Kubernetes Secrets.

kubectl get secrets -l owner=helm,name=my-release -n default
# sh.helm.release.v1.my-release.v1   helm.sh/release.v1   1   30m
# sh.helm.release.v1.my-release.v2   helm.sh/release.v1   1   15m

1.2 Release History

helm history my-release
helm upgrade my-release ./my-chart --history-max 5

2. Install Flow

1. Load chart and resolve dependencies
2. Merge values (defaults + user values)
3. Render templates (execute Go templates)
4. Validate YAML
5. Install CRDs (crds/ directory)
6. Execute pre-install hooks
7. Create resources via Kubernetes API
8. Store release Secret (status: deployed)
9. Execute post-install hooks
10. Output NOTES.txt

helm install my-release ./my-chart -n production --create-namespace
helm install my-release ./my-chart -f production-values.yaml --set image.tag=v2.0.0
helm install my-release ./my-chart --dry-run=server
helm install my-release ./my-chart --atomic --timeout 5m
helm install my-release ./my-chart --wait --timeout 10m

3. Upgrade Flow

3.1 Three-way Strategic Merge Patch

Helm 3's key improvement compares three states:

Previous Release Manifest (Old Chart)
         - compare -
Current Live State (Live State)
         - compare -
New Release Manifest (New Chart)

Benefits:

  • Recognizes changes made directly via kubectl
  • Prevents unnecessary resource recreation
  • Safely merges manual changes
helm upgrade my-release ./my-chart -f new-values.yaml
helm upgrade --install my-release ./my-chart
helm upgrade my-release ./my-chart --reuse-values --set image.tag=v2.1.0
helm upgrade my-release ./my-chart --reset-values -f new-values.yaml
helm diff upgrade my-release ./my-chart -f new-values.yaml

4. Rollback Flow

1. Load target revision release data
2. Use that revision's manifest as "new manifest"
3. Calculate changes via three-way merge
4. Execute pre-rollback hooks
5. Apply resources
6. Store release with new revision number
7. Execute post-rollback hooks

helm rollback my-release        # Previous revision
helm rollback my-release 2      # Specific revision
helm history my-release
helm get manifest my-release --revision 2

Important: Rollback creates a new revision based on the previous revision's chart and values, rather than simply restoring old manifests.

5. Hook System

5.1 Hook Types

HookExecution Timing
pre-installAfter template rendering, before resource creation
post-installAfter all resources loaded into cluster
pre-deleteOn delete request, before resource deletion
post-deleteAfter all resources deleted
pre-upgradeOn upgrade, before resource update
post-upgradeAfter resource update
pre-rollbackOn rollback, before resource rollback
post-rollbackAfter resource rollback
testOn helm test execution

5.2 Hook Definition Example

apiVersion: batch/v1
kind: Job
metadata:
  name: {{ include "my-chart.fullname" . }}-db-migrate
  annotations:
    "helm.sh/hook": pre-upgrade,pre-install
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": before-hook-creation
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: migrate
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          command: ["./migrate", "--up"]

5.3 Hook Delete Policies

PolicyDescription
before-hook-creationDelete previous hook resource before new hook execution
hook-succeededDelete on hook success
hook-failedDelete on hook failure

6. Uninstall Flow

helm uninstall my-release
helm uninstall my-release --keep-history
helm uninstall my-release --dry-run

Note: CRDs are not deleted on uninstall and require manual removal.

7. Atomic Install and Wait

7.1 --wait Flag

Waits until: Deployments Ready, Services have IPs, Jobs Complete, PVCs Bound.

7.2 --atomic Flag

Includes --wait plus auto-uninstall on install failure, auto-rollback on upgrade failure.

helm install my-release ./my-chart --atomic --timeout 5m

8. Release Information Queries

helm list --all-namespaces
helm status my-release
helm get values my-release --all
helm get manifest my-release
helm get notes my-release
helm get all my-release

9. Summary

Key aspects of the Helm release lifecycle:

  1. Secret-based revision management: All release history managed as Kubernetes Secrets
  2. Three-way Merge: Safe upgrades by comparing previous manifest, live state, and new manifest
  3. Hook system: Custom logic injection at each lifecycle stage
  4. Atomic deployment: Automatic rollback on failure for reliability
  5. History-based rollback: Creates new revisions based on previous revision's chart/values
Discuss on Twitter • View on GitHub