Helm & Kubernetes Packaging - Charts, Values, Releases, Rollback, Hooks vs Kustomize, Operators & GitOps

"""Simulation: Helm values precedence and release history.

Values: chart values.yaml < parent chart values < -f files (later wins) < --set.
Maps merge deeply, lists are replaced whole, and null deletes a default key.
Releases: each install/upgrade/rollback writes a new revision record (Helm stores
them as Secrets named sh.helm.release.v1.<release>.v<revision> by default);
`helm upgrade --history-max` defaults to 10.
"""
import copy, json

def merge(base, over):
    out = copy.deepcopy(base)
    for k, v in over.items():
        if v is None:
            out.pop(k, None)                       # null removes the default
        elif isinstance(v, dict) and isinstance(out.get(k), dict):
            out[k] = merge(out[k], v)              # maps merge recursively
        else:
            out[k] = copy.deepcopy(v)              # scalars and lists replace
    return out

def set_flag(expr):                                # --set a.b.c=val
    path, val = expr.split("=", 1)
    val = int(val) if val.isdigit() else val
    node = {}
    cur = node
    keys = path.split(".")
    for k in keys[:-1]:
        cur[k] = {}; cur = cur[k]
    cur[keys[-1]] = val
    return node

chart_defaults = {"replicaCount": 1, "image": {"repository": "checkout", "tag": "1.4.2", "pullPolicy": "IfNotPresent"},
                  "resources": {"requests": {"cpu": "100m"}}, "ingress": {"enabled": False, "hosts": ["checkout.local"]},
                  "podAnnotations": {"prometheus.io/scrape": "true"}}
prod_file = {"replicaCount": 4, "ingress": {"enabled": True, "hosts": ["checkout.example.com"]}}
region_file = {"resources": {"requests": {"memory": "256Mi"}}, "podAnnotations": None}
layers = [("values.yaml", chart_defaults), ("-f prod.yaml", prod_file), ("-f us-east.yaml", region_file),
          ("--set image.tag=1.5.0", set_flag("image.tag=1.5.0"))]
vals = {}
for name, layer in layers:
    vals = merge(vals, layer)
    print(f"after {name:<22} replicas={vals.get('replicaCount')} tag={vals['image']['tag']} "
          f"hosts={vals['ingress']['hosts']} annotations={vals.get('podAnnotations', '(removed)')}")
print("resources merged deeply:", json.dumps(vals["resources"]))

# --------- releases --------------------------------------------------------
print("\nrelease history for 'checkout' (history-max 3 to keep output short)")
HISTORY_MAX = 3
secrets = []                                        # list of dicts, oldest first
def write(action, values, status="deployed"):
    for s in secrets:
        if s["status"] == "deployed":
            s["status"] = "superseded"
    rev = (secrets[-1]["rev"] + 1) if secrets else 1
    secrets.append({"rev": rev, "action": action, "tag": values["image"]["tag"], "status": status})
    while len(secrets) > HISTORY_MAX:               # prune oldest revisions
        secrets.pop(0)
    return rev

write("install", merge(vals, {"image": {"tag": "1.4.2"}}))
write("upgrade", vals)
r = write("upgrade", merge(vals, {"image": {"tag": "1.6.0-bad"}}), status="failed")
secrets[-2]["status"] = "deployed"                  # a failed upgrade leaves the previous one deployed
target = secrets[-2]
write(f"rollback to {target['rev']}", merge(vals, {"image": {"tag": target["tag"]}}))
for s in secrets:
    print(f"  Secret sh.helm.release.v1.checkout.v{s['rev']}: {s['action']:<14} tag={s['tag']:<10} {s['status']}")
print("  note: rollback created a NEW revision; revision 1 was pruned by history-max")

after values.yaml            replicas=1 tag=1.4.2 hosts=['checkout.local'] annotations={'prometheus.io/scrape': 'true'}
after -f prod.yaml           replicas=4 tag=1.4.2 hosts=['checkout.example.com'] annotations={'prometheus.io/scrape': 'true'}
after -f us-east.yaml        replicas=4 tag=1.4.2 hosts=['checkout.example.com'] annotations=(removed)
after --set image.tag=1.5.0  replicas=4 tag=1.5.0 hosts=['checkout.example.com'] annotations=(removed)
resources merged deeply: {"requests": {"cpu": "100m", "memory": "256Mi"}}

release history for 'checkout' (history-max 3 to keep output short)
  Secret sh.helm.release.v1.checkout.v2: upgrade        tag=1.5.0      superseded
  Secret sh.helm.release.v1.checkout.v3: upgrade        tag=1.6.0-bad  failed
  Secret sh.helm.release.v1.checkout.v4: rollback to 2  tag=1.5.0      deployed
  note: rollback created a NEW revision; revision 1 was pruned by history-max

// Simulation: two-way vs three-way merge when the live object has drifted.
// Mirrors the Helm 3 docs example: chart says replicas 3, someone scales to 0,
// then the same chart is applied again. Also shows a field added by another
// actor (a mutating webhook's sidecar label) surviving a three-way merge.
type Doc = Record<string, string | number>;

function twoWay(oldM: Doc, newM: Doc, live: Doc): Doc {
  const out = { ...live };
  for (const k of new Set([...Object.keys(oldM), ...Object.keys(newM)])) {
    if (oldM[k] !== newM[k]) {                 // only chart-to-chart differences are patched
      if (k in newM) out[k] = newM[k]; else delete out[k];
    }
  }
  return out;
}

function threeWay(oldM: Doc, newM: Doc, live: Doc): Doc {
  const out = { ...live };
  for (const k of Object.keys(newM)) {
    if (live[k] !== newM[k]) out[k] = newM[k]; // desired value wins over drift
  }
  for (const k of Object.keys(oldM)) {
    if (!(k in newM)) delete out[k];           // we owned it before and dropped it now
  }
  return out;                                  // keys nobody declared (sidecar) are left alone
}

const chartV1: Doc = { replicas: 3, image: "checkout:1.5.0" };
const live: Doc = { replicas: 0, image: "checkout:1.5.0", "sidecar.istio.io/status": "injected" };
console.log("chart (old == new):", JSON.stringify(chartV1));
console.log("live after kubectl scale --replicas=0 and webhook injection:", JSON.stringify(live));
console.log("two-way result:  ", JSON.stringify(twoWay(chartV1, chartV1, live)), "<- drift kept");
console.log("three-way result:", JSON.stringify(threeWay(chartV1, chartV1, live)), "<- drift repaired, sidecar kept");

const chartV2: Doc = { image: "checkout:1.6.0" };   // v2 stops setting replicas (HPA owns it now)
const live2: Doc = { replicas: 7, image: "checkout:1.5.0" };
console.log("\nchart v2 drops 'replicas' so the HPA can own it; live has replicas=7");
const patched = threeWay(chartV1, chartV2, live2);
console.log("three-way result:", JSON.stringify(patched), "<- field you stopped declaring is deleted");
const defaulted = { replicas: 1, ...patched };       // API server defaulting fills spec.replicas
console.log("after API defaulting:", JSON.stringify(defaulted), "<- 7 pods drop to 1 until the HPA reacts");
console.log("lesson: hand replicas to the HPA in two steps (stop owning the field first), per the HPA migration docs");

chart (old == new): {"replicas":3,"image":"checkout:1.5.0"}
live after kubectl scale --replicas=0 and webhook injection: {"replicas":0,"image":"checkout:1.5.0","sidecar.istio.io/status":"injected"}
two-way result:   {"replicas":0,"image":"checkout:1.5.0","sidecar.istio.io/status":"injected"} <- drift kept
three-way result: {"replicas":3,"image":"checkout:1.5.0","sidecar.istio.io/status":"injected"} <- drift repaired, sidecar kept

chart v2 drops 'replicas' so the HPA can own it; live has replicas=7
three-way result: {"image":"checkout:1.6.0"} <- field you stopped declaring is deleted
after API defaulting: {"replicas":1,"image":"checkout:1.6.0"} <- 7 pods drop to 1 until the HPA reacts
lesson: hand replicas to the HPA in two steps (stop owning the field first), per the HPA migration docs