Operator#

The operator (maqpna-operator) is the Kubernetes controller of MAQPNA. It is built on controller-runtime and watches the maqpna.com/v1alpha1 kinds. It has two jobs:

1. Run sessions. For each AgentSession it checks the request, gets credentials from the identity broker (or registers an attested release), creates the sandbox through the upstream agent-sandbox project and fences it with a NetworkPolicy.
2. Feed the gateway. It renders the cluster's policies, MCP servers, model routes, A2A routes, revocations, budgets, memory stores and tenants into ConfigMaps (and two credential Secrets) in the gateway namespace, which the gateway hot-reloads.

The operator never sits on the request path of a tool call. Running sessions keep working when it is down.

Code: cmd/maqpna-operator, internal/controller, api/v1alpha1.

Responsibilities and neighbours#

flowchart LR
    K[("Kubernetes API<br/>maqpna.com/v1alpha1")] -- watch --> OP
    subgraph OP["maqpna-operator"]
      SR["AgentSession reconciler"]
      AGG["Aggregating reconcilers:<br/>ToolPolicy, MCPServer, ModelRoute,<br/>A2A, AgentRevocation, Budget,<br/>MemoryStore, Tenant"]
      OTH["Agent, TrustTier,<br/>SovereigntyPolicy, Snapshot"]
      MET["Licence watcher,<br/>node counter"]
    end
    SR -- "POST /v1/token" --> IB["Identity broker"]
    SR -- "POST /v1/releases" --> AT["Attestation service"]
    SR -- "Sandbox / SandboxClaim,<br/>Secrets, NetworkPolicy" --> K
    SR -- "POST /v1/usage/sandbox" --> GW["Gateway"]
    AGG -- "ConfigMaps maqpna-*<br/>in maqpna-system" --> K
    K -- "files, polled" --> GW
    OTH -- "SandboxWarmPool maqpna-tier" --> K

Inputs and outputs#

Reconcilers are registered in this order: AgentSession, Agent, TrustTier, ToolPolicy, ModelRoute, MCPServer, A2A, AgentRevocation, Budget, AgentSessionSnapshot, MemoryStore, Tenant, SovereigntyPolicy. Every aggregating reconciler validates each object first: an invalid one is left out of the rendered document with Ready=False, so one bad object cannot make the gateway reject the whole bundle.

How a session is reconciled#

1. On first sight the session becomes Pending and gets the finalizer maqpna.com/cleanup.
2. The operator loads the Agent and the TrustTier (AgentNotFound, TierNotFound fail the session).
3. It resolves the principal: status.principal{user, groups, verifiedBy} from --principal-binding, or a verified OIDC ID token from spec.userAssertionRef.
4. It checks the agent against the default SovereigntyPolicy (SovereigntyViolation in enforce mode).
5. It checks that the requested scopes are a subset of the agent's (ScopeEscalation), adding models:<route> when the agent has a model.
6. It clamps the TTL to the tier and agent maximums and computes expiresAt; an expired session is torn down and Completed.
7. It applies governance: a failed attestation (AttestationFailed), a matching revocation (terminate, suspend or block) and concurrency quotas (QuotaExceeded, oldest first).
8. It validates spec.input and resolves a fork.
9. It gets credentials: an attested release (tier-2), nothing (warm-pool claim, the broker mints at bootstrap), or a token from POST /v1/token, re-minted at 80% of its lifetime.
10. It creates the input Secret, workspace, Sandbox or SandboxClaim, then the NetworkPolicy, and sets the phase from the sandbox's conditions.

The full flow, with the state diagram, is in session lifecycle.

Configuration#

Flags of cmd/maqpna-operator (Helm sets them from operator.*, gateway.*, identity.* and attestation.*):

Environment: MAQPNA_BROKER_TOKEN, the bearer for broker and attestation calls. The manager caches only operator-labelled Secrets and ConfigMaps in the gateway namespace; other Secrets (MCP server credentials, model API keys) are read uncached.

Failure modes#

Scaling#

• Leader election (--leader-elect, added by the chart when operator.replicas > 1) makes one replica active; values-production.yaml runs two.
• --session-workers (8) sessions reconcile in parallel; quota admission stays serialised.
• The licence watcher runs on every replica; the node counter runs on the leader only.

Metrics#

maqpna_session_ready_seconds{tier,mode}, maqpna_sessions{namespace,tier,phase}, maqpna_session_phase_transitions_total{from,to,reason}, maqpna_session_outcomes_total{tier,result}, maqpna_token_mint_seconds, maqpna_warm_pool_ready{tier}, maqpna_reconcile_errors_total{controller,reason}, maqpna_reconcile_duration_seconds{controller}, maqpna_rendered_configmap_bytes{name}, maqpna_billable_nodes{period}, maqpna_license_state, maqpna_license_days_left, maqpna_license_node_limit and maqpna_build_info. See observability.

What you see#

maqpna status shows the operator next to the other workloads (format from cmd/maqpna/status.go; values illustrative):

Release maqpna in maqpna-system: deployed, revision 2, chart maqpna-0.1.0, app 0.1.0, updated 2026-10-02T14:05:09Z
  REVISION  STATUS      CHART         APP    UPDATED               DESCRIPTION
  1         superseded  maqpna-0.1.0  0.1.0  2026-10-01T09:12:44Z  maqpna install 0.1.0
  2         deployed    maqpna-0.1.0  0.1.0  2026-10-02T14:05:09Z  Upgrade complete

WORKLOAD                    COMPONENT  READY  IMAGE
deployment/maqpna-gateway   gateway    1/1    ghcr.io/maqpna/maqpna-gateway:0.1.0
deployment/maqpna-identity  identity   1/1    ghcr.io/maqpna/maqpna-identity:0.1.0
deployment/maqpna-operator  operator   1/1    ghcr.io/maqpna/maqpna-operator:0.1.0

CRDs: 13 maqpna.com   Sessions: Completed=12 Running=4
Gateway http://127.0.0.1:8080: ready=true pendingApprovals=1 revocations=0 tainted=2 auditHead=4711 verified=true licence=valid

The line formats are fixed in the code; the values are illustrative. Session events (maqpna events SESSION) carry the operator's reasons: Accepted, TokenMinted, TokenRefreshed, ReleaseRegistered, SandboxCreated, TTLClamped, Suspending, Resumed, Expired, Completed, and the warnings ScopeEscalation, SovereigntyViolation, Revoked, QuotaExceeded, AttestationFailed. See maqpna status and maqpna events.

Related#

• Session lifecycle
• CRD data model
• Network and egress design
• Agents, sessions, sandboxes and trust tiers