Install and upgrade flow#

MAQPNA installs with one command, maqpna install, and upgrades with maqpna upgrade. Both drive the MAQPNA Helm chart through the Helm v3 SDK. Because the Helm SDK would more than double the size of the CLI, the lifecycle commands live in a separate executable, the lifecycle plugin maqpna-install. The maqpna CLI lists them in its help and hands them over to the plugin with every argument unchanged.

How the plugin is found#

flowchart TD
    C["maqpna install ..."] --> E{"MAQPNA_INSTALL_PLUGIN set?"}
    E -- yes --> RUN["run that file"]
    E -- no --> B{"maqpna-install next to the maqpna binary<br/>(or next to its symlink target)?"}
    B -- yes --> RUN
    B -- no --> P{"maqpna-install on PATH?"}
    P -- yes --> RUN
    P -- no --> M["print how to install the plugin, exit 1"]
    RUN --> X["same arguments and global flags,<br/>stdin, stdout, stderr and exit code passed through,<br/>SIGTERM forwarded"]

The plugin is the only plugin the CLI knows; there is no general maqpna-<name> plugin lookup. Separately, the maqpna binary installed as kubectl-maqpna works as a kubectl plugin (kubectl maqpna ...).

Install#

sequenceDiagram
    autonumber
    participant U as Platform engineer
    participant CLI as maqpna
    participant PL as maqpna-install
    participant R as Chart registry (OCI)
    participant K as Kubernetes API
    U->>CLI: maqpna install --profile prod -f my-values.yaml
    CLI->>PL: exec with the same arguments
    PL->>R: pull the release chart<br/>(version = the CLI's version)
    PL->>PL: merge values: profile, -f files, --set
    PL->>K: release maqpna exists? (refuse: use maqpna upgrade)
    PL->>K: plan CRDs (server dry run), stop on blocking changes
    PL->>K: server-side apply the 13 CRDs (field manager maqpna)
    PL->>K: helm install (create namespace maqpna-system, wait, 10 min timeout)
    K-->>PL: release deployed
    PL-->>U: release, chart and app versions, CRD plan, notes

1. Run preflight first. maqpna preflight evaluates the same values install would use and checks, read-only: chart-renders, release-exists, kube-version (at least 1.29.0), install-permissions (SelfSubjectAccessReviews), agent-sandbox (the upstream CRDs are served), runtimeclass-<name> for every RuntimeClass the values enable, cni-networkpolicy (a CNI that enforces NetworkPolicies), image-registry-allowed, gateway-replicas-state (more than one gateway replica needs state.backend: postgres), state-dsn-secret, identity-key-secret, attest-sample-verifier and attest-dev-key-secret.
2. Pick a profile. --profile dev|prod|sovereign-eu maps to values-dev.yaml, values-production.yaml and values-sovereign-eu.yaml. The production profile turns on OIDC admin authentication, closed audit mode, Postgres state with three gateway replicas, WORM shipping with signed checkpoints and principal binding.
3. Resolve the chart. By default the release chart (oci://<release registry>/charts/maqpna, listed on maqpna.com/download) at the CLI's own version; --chart, --version, --repo and registry credentials (--username, --password, env MAQPNA_CHART_USERNAME, MAQPNA_CHART_PASSWORD) override it.
4. Apply the CRDs. Helm never upgrades the crds/ directory, so the plugin plans the CRD changes (a server-side dry run with --dry-run), refuses blocking changes, and server-side applies the CRDs itself before Helm runs (skip with --skip-crds).
5. Install the release. helm install into maqpna-system (created by default), waiting for the workloads.
6. Prerequisites the chart does not install. The upstream agent-sandbox controller (v1.0.4), the RuntimeClass handlers on your nodes (gVisor, Kata), and, for production, PostgreSQL and an identity provider.

Upgrade#

1. maqpna upgrade check runs the checks release-installed, version-path (fails on a downgrade or a skipped minor version), crd-changes, crd-removed-fields, crd-stored-versions (a stored version the new CRDs no longer serve would orphan objects), render-target (the new chart renders with the deployed values), behaviour-values (values whose meaning changes) and version-skew (gateway, identity broker, attestation service and operator on the same minor version; the CLI within one minor version).
2. maqpna upgrade requires the release to exist, re-applies the deployed values on top of the new chart's defaults (unless --reset-values), server-side applies the new CRDs and runs helm upgrade. --atomic implies --wait and rolls back on failure. --dry-run prints the CRD plan and a manifest diff with Secret values redacted.
3. maqpna rollback never rolls back CRDs, and refuses when an installed CRD stores a version the target revision does not define (--force overrides).
4. maqpna uninstall keeps the CRDs, the token and identity key Secrets (Helm resource-policy: keep) and agent namespaces unless --purge; it needs --yes when not run in a terminal.

Air-gapped install#

flowchart LR
    subgraph Online["Connected build host"]
      B["maqpna airgap bundle<br/>images, chart, manifests,<br/>SBOMs, SHA256SUMS, signature"]
    end
    B -- "removable media" --> V
    subgraph Offline["Air-gapped site"]
      V["maqpna airgap verify DIR<br/>checksums, cosign signature,<br/>all 11 images present"] --> P["maqpna airgap push DIR<br/>--registry registry.site.local"]
      P --> I["maqpna install with<br/>airgap.enabled, image.registry<br/>pointing at the mirror"]
    end

1. maqpna airgap bundle (from a source checkout) builds a bundle of the 11 images, the chart, upstream manifests, SBOMs, SHA256SUMS and a cosign signature (--key REF or --keyless).
2. maqpna airgap verify DIR checks every checksum, rejects path traversal, verifies the signature (offline with --key cosign.pub, or keyless against --certificate-identity and --certificate-oidc-issuer with --trusted-root), and checks that all 11 images are present. --require-signature makes a missing signature fatal.
3. maqpna airgap push DIR --registry REG copies every image to your registry with skopeo, crane or docker.
4. Install with maqpna install, pointing image.registry at your mirror. Nothing at runtime calls out.

What you see#

maqpna install prints the release line, the CRD plan and the chart notes (format from cmd/maqpna-install/install.go; values illustrative):

release maqpna in maqpna-system: deployed, revision 1, chart maqpna-0.1.1, app 0.1.1

CRDs: 13 create, 0 update, 0 unchanged
  create  a2apeers.maqpna.com           served v1alpha1, storage v1alpha1
  create  agentrevocations.maqpna.com   served v1alpha1, storage v1alpha1
  ...

maqpna preflight and maqpna upgrade check print checks as a table with a score (format from cmd/internal/cliutil/posture.go):

STATUS  CHECK                   COMPONENT  DETAIL
PASS    kube-version            operator   server v1.31.2, need >= 1.29.0 (chart kubeVersion >=1.29)
FAIL    gateway-replicas-state  state      gateway.replicas=3, state.backend=file
          fix:                             set state.backend=postgres or gateway.replicas=1
WARN    cni-networkpolicy       network    no NetworkPolicy-enforcing CNI recognised among kube-system DaemonSets: kube-proxy
          fix:                             agent sandboxes rely on default-deny NetworkPolicies: use Calico, Cilium or your cloud's network policy engine

score 72/100: 1 fail, 1 warn, 11 pass, 0 info, 0 skip, 0 accepted

See maqpna preflight, maqpna install, maqpna upgrade, maqpna upgrade check, maqpna rollback, maqpna uninstall and maqpna airgap.

Failure modes#

Related#

• Deployment topologies
• CLI and plugin
• CRD data model
• What "sovereign" means