Operator CRD reference

The MCPG operator manages everything through Custom Resources in the mcpg.dev API group. This page is the authoritative reference for all eight CRDs, their scope, and their key spec fields. For the gateway's own configuration schema (the spec.config payload on an MCPGGateway), see the Configuration reference. To install the operator, follow the Kubernetes install guide.

At a glance

All eight live in API group mcpg.dev at version mcpg.dev/v1alpha2, which is the served and stored version. Namespaced CRDs scope to a tenant's namespace; cluster-scoped CRDs describe shared infrastructure (signed plugins, revocations, coordinators, mirrors, tenant boundaries) that the platform team owns.

Admission and serving model

The operator runs a single validating admission webhook — there is no mutating webhook and no conversion webhook. Pre-1.0 the operator serves only v1alpha2; older alpha versions are dropped wholesale rather than carried via a conversion webhook, so your manifests should target mcpg.dev/v1alpha2 directly.

• Webhook — ValidatingWebhookConfiguration covering all eight kinds on CREATE / UPDATE. The webhook server listens on :9443 inside the operator pod (the Service that kube-apiserver dials defaults to port 443). Default failurePolicy: Fail (fail-closed): when the operator is unreachable, CRD edits are blocked. A namespace label mcpg.dev/skip-validation opts a namespace out of the namespaced webhooks.
• Metrics / health — the operator's /metrics, /healthz, and /readyz endpoints listen on :8443.

Because the operator is otherwise schema-blind for gateway config (see MCPGGateway.spec.config below), the webhook validates CRD-level invariants — plugin trust, capability-grant subsets, namespace exclusivity, replica caps, anchored cosign regexes — while the gateway's own boot-time validator remains the source of truth for the inner gateway config.

MCPGGateway

Scope: Namespaced · short name mcpgw

The core resource: the operator renders one MCPGGateway into a Deployment + Service + ConfigMap, plus optional Ingress, NetworkPolicy, PodDisruptionBudget, HorizontalPodAutoscaler, ServiceMonitor, and PrometheusRule, all reconciled into the gateway's namespace.

Key spec fields

Status

conditions[] is the authoritative readiness signal (Ready, Available). Hash fields let you confirm a change has propagated: configHash (SHA-256 of the rendered config, flips on any spec change that reaches the pod template), pluginSetHash, and revocationListHash. Replica counters (replicas, readyReplicas, updatedReplicas, availableReplicas) mirror the Deployment.

apiVersion: mcpg.dev/v1alpha2
kind: MCPGGateway
metadata:
  name: dev-gateway
  namespace: mcpg-dev
spec:
  replicas: 1
  pluginSetRef:
    name: minimal-plugins
  config:
    gateway:
      server:
        bind_address: "0.0.0.0:8787"
  resources:
    requests: { cpu: 100m, memory: 128Mi }
    limits:   { cpu: 500m, memory: 512Mi }

MCPGPluginSet

Scope: Namespaced · short name mcpgps

An ordered bundle of plugin references with per-plugin runtime config. A gateway references one set via spec.pluginSetRef; the set names cluster-scoped MCPGPlugin resources (a cross-scope read the operator validates for RBAC and readiness at admission and reconcile time).

Key spec fields

Status

resolvedEntries == totalEntries is the canonical Ready signal. resolvedHash is the SHA-256 of the rendered config (entries + per-entry configs + grants) so dependent gateways can detect change and roll pods. Per-entry failures land in failedEntries[] with a stable reason (PluginNotFound, PluginNotReady, PluginRevoked, PluginIdMismatch, ArtefactSecretMissing).

apiVersion: mcpg.dev/v1alpha2
kind: MCPGPluginSet
metadata:
  name: minimal-plugins
  namespace: mcpg-dev
spec:
  entries:
    - id: dev.mcpg.builtin.audit
      pluginRef:
        name: builtin-audit        # required — a cluster-scoped MCPGPlugin that must be Ready
      enabled: true
      config:
        sinks:
          - type: stdout

MCPGRoute

Scope: Namespaced · short name mcpgr

A per-tenant route into a shared gateway — the soft multi-tenancy path. From their own namespace, a tenant team declares which tools they expose through a gateway owned by the platform team, plus the chains and per-tenant attributes that govern them. MCPGRoute is the only CRD permitted to reference a gateway in another namespace, and only when that gateway opts in via MCPGGateway.spec.acceptedRouteNamespaces.

Key spec fields

What is enforced today

The operator fans each route's match.tools + attributes.tenant into the shared gateway's governance.policy.tool_access.rules[] as tenant-scoped CEL rules (a tool is reachable only when $identity.attributes.tenant == "<tenant>"). That is enforced at tools/list (visibility) and tools/call (authorization).

The identityChain / policyChain / auditChain fields are validated and recorded, but per-route chain dispatch is not yet enforced by the gateway runtime — a route cannot today swap the identity/policy/audit chain on a per-tool basis. The controller reports this honestly via the ChainsEnforced status condition (False, reason PerRouteDispatchUnsupported). The tool-access scoping still applies. See the Multi-tenant deployments guide.

Status

Notable conditions: Ready (route accepted, tool-access rules rendered), GatewayBound (referenced gateway exists and accepts this route's namespace), and ChainsEnforced (today False). matchedTools counts the rendered rules; boundGateway is the resolved <namespace>/<name>.

MCPGPlugin

Scope: Cluster · short name mcpgp

A single OCI-published, signed plugin artefact plus the trust policy under which the operator verifies it. Cluster-scoped because the same plugin bytes are byte-identical across every namespace — storing once cluster-wide deduplicates. Tenant MCPGPluginSet resources reference plugins by name.

Key spec fields

The three trust layers are fail-closed and run in order: Ed25519 signature (mandatory) → cosign keyless (optional) → SLSA L3 provenance (optional). The signing-key Secret must live in the operator's namespace so a tenant cannot supply its own trust anchor.

Status

resolvedDigest is the SHA-256 of the verified cdylib bytes (lower-case hex). signatureValid / cosignVerified / slsaVerified are tri-state (Option<bool>: absent ⇒ not yet evaluated). revokedBySha flips true when resolvedDigest matches the cluster MCPGRevocationList; the operator refuses to materialise a revoked plugin into any set. artefactSecretName names the operator-managed Secret holding the verified bytes.

MCPGRevocationList

Scope: Cluster · short name mcpgrl

A cluster-wide list of revoked plugin SHA-256 hashes. The operator treats a single resource named cluster-default as authoritative and fans it out into every namespace running a gateway as a per-namespace ConfigMap, mounted read-only into the gateway pod. Gateway pods enforce at plugin-load time — a list update plus a pod roll is the full revocation cycle.

Key spec fields

Status

observedRevocations is the last-observed entry count; materialisedNamespaces counts the namespaces holding a materialised ConfigMap; pluginsBlocked[] lists the MCPGPlugin resources flagged revokedBySha; contentHash lets you verify rollout consistency across consumer namespaces.

MCPGCluster

Scope: Cluster · short name mcpgc

A shared coordination-backend binding. A multi-replica gateway needs a shared coordinator for sessions, leases, pub/sub, and idempotency state. MCPGCluster centralises that: the platform team declares the backend once, and any gateway binds it with clusterRef: { name: ... }. The operator renders the backend's cluster: config block and ensures the matching dev.mcpg.cluster.<kind> cdylib entry is present.

Key spec fields

The backend enum maps to cdylib ids: redis → dev.mcpg.cluster.redis, nats → dev.mcpg.cluster.nats, consul → dev.mcpg.cluster.consul, etcd → dev.mcpg.cluster.etcd. single_node loads no cdylib.

Status

pluginId is the resolved cdylib id (absent for single_node). boundGateways counts gateways currently bound via clusterRef (blast-radius signal before an edit). configHash is the SHA-256 of the rendered cluster: block, which bound gateways fold into their pod-roll hash so a cluster config edit re-rolls every bound gateway.

apiVersion: mcpg.dev/v1alpha2
kind: MCPGCluster
metadata:
  name: prod-redis
spec:
  backend: redis
  config:
    url: "redis://redis.mcpg-prod.svc.cluster.local:6379"
    key_prefix: "mcpg.prod"
  credentialRefs:
    - name: password
      secretName: redis-creds
      key: password

MCPGTenant

Scope: Cluster · short name mcpgt

A declarative tenant boundary. A cluster-admin declares the namespaces a tenant owns, which cluster MCPGPlugins those namespaces may reference, and hard quotas. Cluster-scoped because only a cluster-admin should define tenant boundaries — a tenant must not be able to grant itself more namespaces or raise its own quota. Namespaces are exclusively owned (a namespace belongs to at most one tenant, enforced at admission). Opt-in: a cluster with no MCPGTenant keeps the implicit, PluginSet-triggered RBAC unchanged.

Key spec fields

Division of labour

The admission webhook synchronously enforces the plugin allowlist, namespace exclusivity, and the per-gateway replica cap. The reconcile loop (eventual) binds per-namespace Secret-write RoleBindings, labels namespaces mcpg.dev/tenant=<name>, and generates the per-namespace ResourceQuota — the race-safe count-quota enforcement (the apiserver holds the lock; the webhook count-check is only a nicer error message).

Status

boundNamespaces[] lists the namespaces successfully bound (exist + labelled + RBAC/quota applied). observed carries aggregate counts (gateways, pluginSets, routes) for quota-headroom visibility only — never the enforcement point. Notable conditions: Ready, NamespacesBound, and QuotaWithinLimits (a soft signal, not a gate).

MCPGPluginMirror

Scope: Cluster · short name mcpgm

An in-cluster OCI mirror declaration for air-gapped plugin pulls. It is a rewrite rule + endpoint descriptor, not the registry itself and not a pull-through cache (images must be pre-mirrored by a sync station). An MCPGPlugin opts in via spec.oci.mirrorRef; the operator then rewrites the upstream ref onto the mirror and never falls back to the public registry (fail-closed).

Key spec fields

The tag and @sha256: digest pin are preserved through the rewrite, so the content-addressed identity the operator verifies is unchanged. cosign cert-identity and SLSA source-URI checks still validate against the upstream repo — a mirror cannot launder an unsigned artefact.

Status

reachable reports whether the operator could reach the mirror's /v2/ endpoint at last reconcile (false ⇒ pulls through this mirror will fail). proxiedReferences counts MCPGPlugins referencing this mirror. endpointHost is the resolved in-cluster registry host.

apiVersion: mcpg.dev/v1alpha2
kind: MCPGPluginMirror
metadata:
  name: airgap-mirror
spec:
  endpoint:
    service:
      namespace: oci-mirror
      name: harbor
      port: 80
      pathPrefix: /v2/mirror
    insecure: true
  upstream:
    registry: ghcr.io
    namespace: mcpg-dev/source-code
  auth:
    secretRef:
      secretName: mirror-pull
      key: .dockerconfigjson
  resyncInterval: 1h

Cross-references

• Configuration reference — the gateway's own AppConfig schema (the MCPGGateway.spec.config payload).
• Kubernetes install with Helm — installing the operator and CRDs.
• Multi-tenant deployments — hard vs. soft tenancy, MCPGTenant, and MCPGRoute in practice.