Installation, Upgrade, and Rollback Matrix

The install matrix is the compatibility table for Kubernetes delivery. It binds a values profile to the suite that must prove it, and it names the lifecycle transitions Atlas actually exercises.

Profile Evidence Lanes

Profile	Values file	Required suite
ci	ops/k8s/values/ci.yaml	install-gate
dev	ops/k8s/values/dev.yaml	install-gate
local	ops/k8s/values/local.yaml	install-gate
kind	ops/k8s/values/kind.yaml	k8s-suite
offline	ops/k8s/values/offline.yaml	k8s-suite
profile-baseline	ops/k8s/values/profile-baseline.yaml	k8s-suite
ingress	ops/k8s/values/ingress.yaml	nightly
multi-registry	ops/k8s/values/multi-registry.yaml	nightly
perf	ops/k8s/values/perf.yaml	nightly
prod	ops/k8s/values/prod.yaml	nightly

This table states the minimum named lane. A production decision can require additional security, load, observability, and recovery evidence even when the matrix row is satisfied.

Coverage Dimensions

flowchart TD
    Profile[Values profile] --> Install[Clean install]
    Profile --> Upgrade[Previous to candidate]
    Profile --> Rollback[Candidate to previous]
    Install --> Evidence[Named delivery lane and reports]
    Upgrade --> Evidence
    Rollback --> Evidence
    Evidence --> Qualify[Security, telemetry, load, and recovery qualification]

Support is the intersection of profile, lifecycle transition, source release, target release, and evidence lane. A row that covers clean installation does not imply either direction of release transition. A lifecycle scenario that uses Kind does not automatically qualify the production profile.

Lifecycle Coverage

flowchart LR
    N["No installed release"] -->|install| H["workspace-head"]
    P["chart-previous"] -->|upgrade| H
    H -->|rollback| P

The matrix declares these scenarios:

Lifecycle	Profiles	Source and target identity
Install	profile-baseline, ci, kind, offline, perf	Clean installation of the selected profile
Upgrade	kind, offline, perf	chart-previous to workspace-head
Rollback	kind, offline, perf	workspace-head to chart-previous

There is no declared upgrade or rollback scenario for prod, dev, local, ingress, or multi-registry in the current matrix. Do not present those transitions as proven by this contract.

The production-oriented prod-minimal, prod-ha, and prod-airgap profiles are absent from the profile rows as well as the lifecycle scenarios. Their values files define reviewable intent, but the matrix provides no execution lane for them. Production Qualification defines the additional evidence and the claims that must remain blocked.

Selecting a Path

1. Choose a profile whose intent matches the target environment.
2. Confirm its values file and suite in ops/k8s/install-matrix.json.
3. Validate the matrix against ops/schema/k8s/install-matrix.schema.json.
4. For upgrade or rollback, preserve both release references and rendered manifests.
5. Run the named suite and collect the install, probe, conformance, and observability evidence it requires.
6. Apply rollout and rollback decisions using the rollout-safety contract.

Record environment facts that can change the result even when the matrix row does not: Kubernetes version, architecture, registry mode, network policy implementation, storage class, ingress controller, and dependency topology. These facts belong in evidence; they do not create undocumented matrix rows.

Bind a Matrix Cell to One Run

An accepted cell needs more than the profile and lane names. Retain a receipt that fixes the lifecycle direction, both release identities, exact values and render hashes, cluster capabilities, selected checks, and final traffic state.

Cell state	Meaning
declared.	The matrix names the profile, lifecycle direction, and required lane.
executable.	Every referenced suite, tool, artifact, and rollback target resolves.
exercised.	One identified environment ran the complete selected path.
accepted.	Required behavior, evidence, and cleanup passed for the exact identities.
stale.	A release, profile, tool, policy, or environment input changed after acceptance.

Only an accepted, non-stale cell supports the scoped delivery claim. Matrix membership alone remains declaration evidence.

Honest Claims

A profile row proves that an evidence lane is defined. A passing install proves that one selected release can be installed under that lane. It does not prove upgrade compatibility, rollback recovery, capacity, air-gap completeness, or production readiness unless those claims have their own declared scenario and evidence.

When a real deployment path is missing from the matrix, add and validate the contract before calling the path supported. Do not borrow evidence from a different profile because its manifests appear similar.

Missing coverage is an explicit delivery risk. It may justify holding a release, narrowing the supported claim, or adding the missing scenario. It must not be converted into an inferred pass.

Continue with Render and Validate for preflight proof and Rollout Safety for live promotion decisions. Use Production Qualification to assemble the cross-domain production record.