FAQ

Short answers to the questions platform teams ask most often about running MAQPNA in production.

Installation and requirements#

Do I need Kubernetes? Not to develop. maqpna dev up runs a local MAQPNA (identity broker, gateway and a test MCP server) on a laptop with no Kubernetes (Your first governed agent). Production runs on Kubernetes 1.29 or later.

Which Kubernetes distributions work? Any conformant cluster with a CNI that enforces NetworkPolicy and the node runtimes for the trust tiers you enable. The install notes cover AKS, EKS, GKE, OpenShift, k3s and kind (Production install).

Do I need all three trust tiers? No. Enable only the RuntimeClasses whose runtime is installed on your nodes. tier-0 (gVisor) is enough to start; tier-1 (microVM) needs /dev/kvm; tier-2 (confidential VM) needs AMD SEV-SNP or Intel TDX nodes with Kata CoCo and an attestation verifier. maqpna doctor fails runtimeclass-per-tier when a tier has no RuntimeClass.

Does the chart install agent-sandbox? No. Install the upstream kubernetes-sigs/agent-sandbox controller (v1.0.x) first. The air-gap bundle includes its manifest and images.

Why is maqpna install a separate binary? The Helm-based lifecycle commands (preflight, install, upgrade, rollback, uninstall) live in the maqpna-install plugin, so maqpna stays small. maqpna install runs the plugin with the same arguments; install both from the same release.

Operations#

Does MAQPNA call home? No. There is no telemetry, no usage analytics, no update check and no licence server. The only egress is what you configure (MCP servers, model routes, an identity provider, a WORM bucket, an attestation verifier), and sovereignty.allowedEgressHosts can restrict even that.

Can I run more than one gateway replica? Yes, with state.backend: postgres. With the file backend, every replica keeps its own approvals, revocations and audit ledger, so the chart refuses more than one replica (Scaling and HA).

What happens to agent calls when the audit ledger cannot be written? It depends on gateway.auditFailurePolicy. With open (the default), calls proceed and the failure is logged and counted. With closed (the prod profile), an intent record must be durable before any allowed call is forwarded; otherwise the call is refused and the replica reports not ready. Choose closed when evidence matters more than availability.

What happens when PostgreSQL is down? Gateways report state backend unreachable and leave the Service; approvals cannot be created or decided; with closed audit, allowed calls are refused. The kill switch still works through Kubernetes: maqpna kill … --emit-yaml | kubectl apply -f -.

How fast does the kill switch act? On the replica that receives the revocation, the next call is denied. Other replicas apply it within state.postgres.pollMillis (shared state) or gateway.configSync.pollMillis (an AgentRevocation); a measured median across two regions was 195 ms (Kill switch and revocations).

How much latency does the gateway add? In a load test at 2,000 calls/s on one replica with the file ledger, about 2.4 ms p50 with open audit and 4 ms p50 with closed audit. With PostgreSQL state, every allowed call makes synchronous database commits, so expect about 7 ms p50 or more in-region (Scaling and HA).

How do I upgrade? One minor version at a time: maqpna upgrade check --to V, maqpna upgrade --to V --dry-run, then maqpna upgrade --to V --wait --atomic. CRDs are applied first and never roll back (Upgrade and rollback).

How do I get the console? Run maqpna console --open. It serves the console on 127.0.0.1 and proxies the admin API to the gateway (through kubectl port-forward, or --gateway URL), so no CORS setup is needed. Sign in with maqpna login when adminAuth.mode is oidc. Approvers can also use MAQPNA Desk (maqpna desk).

Security and evidence#

Who holds the keys? You do. The identity signing key, the audit checkpoint key, the token-vault key and the attestation response key are in your Secrets, your HSM (PKCS#11) or your KMS. The prod profile never generates the identity key.

Can an approver approve their own agent's call? No. The session's own user and the agent can never approve its calls (409 self_approval), and a four-eyes approval needs two different people (409 duplicate_approver).

How do I prove the audit ledger was not changed? maqpna audit verify FILE --jwks jwks.json recomputes the hash chain and checks the Ed25519-signed checkpoints offline. Ship the ledger to write-once storage (WORM) with audit.sink: worm for an independent copy (Audit).

What does support get from a support bundle? Versions, the doctor report, release history, objects, events and logs, redacted. Never Secret values, never agent logs, never the audit ledger (Troubleshooting).

Licensing#

Does an expired licence stop my agents? No. A licence only switches paid features on. No licence state (none, invalid, grace or expired) ever blocks or degrades agent traffic. Paid features stay on for 30 days after expiry (Licensing).

How are nodes counted? The operator counts distinct nodes that ran sandbox pods, as day and month high-water marks in the ConfigMap maqpna-usage-nodes. Exceeding the licence's node limit is reported, never enforced.