Compatibility matrix

Mirops checks each detected add-on against the target Kubernetes version using a vendor-verified compatibility matrix, embedded in the operator at build time and overridable via ConfigMap.

Coverage

Common add-ons, across Kubernetes target versions 1.24 – 1.35:

Istio · cert-manager · ingress-nginx · Argo CD · Prometheus · external-dns · metrics-server · cluster-autoscaler · Calico · Cilium

How a check works

Each add-on has rules mapping an add-on version range to a supported Kubernetes range. For an incompatible add-on, Mirops computes the version you'd need to upgrade to (an inverse lookup) and records it as a blocker:

incompatible add-on: cert-manager 1.18.2 (upgrade to >=1.20.0)

An incompatible add-on is a deterministic blocker — it sets CRITICAL.

bestEffort rules

Some matrix rules are marked bestEffort: true — they were extrapolated, not confirmed against the vendor's official compatibility statement (typically for EOL add-on versions the vendor no longer tests). They evaluate exactly like a verified rule; the flag is a provenance signal for the people who maintain the matrix.

Where the matrix comes from

The operator consumes the matrix in two layers — the override wins:

1. ConfigMap mirops-compatibility-matrix (operator namespace) — an override, when present.
2. Embedded snapshot — baked into the operator image at build. The default; deterministic and offline-safe.

The operator never reaches a registry at runtime, so it always starts (even air-gapped).

Choosing a matrix version (from Helm)

By default the operator uses its embedded matrix — it tracks the operator's own releases. To update the matrix without rebuilding the operator, let the Helm chart pull a published version into the override ConfigMap. A pre-install/pre-upgrade hook Job does the pull (versions are tagged by UTC date, vYYYY.MM.DD, plus a moving latest).

Because the pull is a pre-install hook (before the chart's normal resources), the namespace must already exist — install with --create-namespace so Helm creates it first:

# newest matrix — non-prod / stay current
helm upgrade --install mirops oci://ghcr.io/miropshq/charts/mirops \
  --namespace mirops --create-namespace \
  --set compatMatrix.enabled=true --set compatMatrix.version=latest

# pinned date — reproducible; recommended for production
helm upgrade --install mirops oci://ghcr.io/miropshq/charts/mirops \
  --namespace mirops --create-namespace \
  --set compatMatrix.enabled=true --set compatMatrix.version=v2026.09.03

Pin in production

latest is a moving tag — an upgrade could change compatibility results. Pin a date in production so the verdict stays reproducible; use latest in non-prod to stay current. For air-gapped clusters, leave compatMatrix.enabled=false and rely on the embedded matrix.

Inspecting what a version covers

Compatibility isn't defined per OCI tag — it's a frozen snapshot of every add-on rule (addonRange → k8sRange) at that date, merged into a single matrix.yaml. To see exactly what a version covers, pull it and read the file:

# a pinned date
oras pull ghcr.io/miropshq/mirops-compat:v2026.09.03 --output ./matrix
cat ./matrix/dist/matrix.yaml

# or the moving 'latest'
oras pull ghcr.io/miropshq/mirops-compat:latest --output ./matrix
cat ./matrix/dist/matrix.yaml

Already running in a cluster? Read the same content from the override ConfigMap the operator consumes (once compatMatrix.enabled=true populated it):

kubectl get configmap mirops-compatibility-matrix -n mirops -o jsonpath='{.data.matrix\.yaml}'

When that ConfigMap isn't present, the operator uses its embedded snapshot (baked into the image at build), which tracks the operator's release rather than a date tag.

Overriding the matrix by hand

Instead of pulling a published version, you can ship your own mirops-compatibility-matrix ConfigMap (with a matrix.yaml key) in the operator's namespace to extend or correct the rules. Per add-on, override rules fully replace the built-in ones.

Source

The matrix is curated in the mirops-compat repository — every rule traces to an official source, and unverified rules are marked bestEffort.