MAQPNADocs

A2APeer

A2APeer (maqpna.com/v1alpha1): every field, type, default and validation rule, generated from the CRD schema.

A2APeer is a remote A2A agent that local agents may call through the gateway (F-15).

At a glance#

Property Value
API version maqpna.com/v1alpha1
Kind A2APeer
Scope Namespaced
Plural a2apeers
Short names a2ap, peer
Categories maqpna
Status subresource yes 
kubectl get a2apeers -A
kubectl get a2ap <name> -o yaml
kubectl explain a2apeers.spec

Columns in kubectl get#

Column Type From
URL string .spec.url
Trust string .spec.trust
Ready string .status.conditions[?(@.type=="Ready")].status
Age date .metadata.creationTimestamp

Example#

From config/samples/a2apeer-partner.yaml:

# A remote A2A v1.0 agent that agents in team-a may call through the gateway
# (POST /a2a/team-a/partner-reviewer; F-15). Its Agent Card must be signed
# (JWS over RFC 8785) by a pinned key and list spec.url; calls fail closed
# otherwise. Answers of untrusted peers taint the caller's session.
apiVersion: maqpna.com/v1alpha1
kind: A2APeer
metadata:
  name: partner-reviewer
  namespace: team-a
spec:
  url: https://agents.partner.acme.eu/a2a/v1
  jurisdiction: EU-DE
  trust: untrusted
  cardKeys:
    jwksConfigMapRef: {name: partner-reviewer-card-keys, key: jwks.json}
  allowedCallers: ["coder"]        # team-a/coder only
  skills: ["code-review"]
  auth:
    type: tokenExchange            # identity headers / Txn-Tokens never leave the trust domain
    tokenExchange: {audience: partner-reviewer}

Spec fields#

A2APeerSpec describes a remote A2A agent reachable through the gateway.

Field Type Required Description
allowedCallers []string allowedCallers: "" (this namespace) or "/"; empty = agents of this namespace only.
auth object auth presented to the peer (identity headers and Txn-Tokens never leave the trust domain). Rule: tokenExchange requires tokenExchange.
auth.tokenExchange object MCPTokenExchange configures a per-session RFC 8693 exchange at the MAQPNA identity broker: the upstream receives a down-scoped token carrying act.sub.
auth.tokenExchange.audience string yes audience must be allowlisted in the broker's -exchange-config. Min length: 1.
auth.type string yes One of: none, tokenExchange.
caBundleRef object caBundleRef selects a PEM CA bundle for the peer's TLS.
caBundleRef.key string yes Min length: 1.
caBundleRef.name string yes Min length: 1.
cardKeys object cardKeys pins the card signing keys.
cardKeys.jwks string jwks is an inline JWKS document (JSON).
cardKeys.jwksConfigMapRef object jwksConfigMapRef selects a JWKS document in a ConfigMap of the A2APeer's namespace.
cardKeys.jwksConfigMapRef.key string yes Min length: 1.
cardKeys.jwksConfigMapRef.name string yes Min length: 1.
cardKeys.jwksURL string jwksURL is fetched by the gateway (residency-checked) when no inline keys are given. Weaker than pinning: it trusts the URL's TLS. Pattern: ^https://.
cardURL string cardURL defaults to :///.well-known/agent-card.json. Pattern: ^https?://.
jurisdiction string jurisdiction of the peer, checked against the SovereigntyPolicy.
requireSignedCard boolean requireSignedCard (default true) fails every call closed unless the fetched card verifies with a pinned key and lists url.
skills []string skills restricts callable skill ids (empty = any skill on the verified card).
timeoutSeconds integer (int32) Minimum: 0. Maximum: 3600.
trust string trust (default untrusted): answers of untrusted peers taint the caller's session (label untrusted-input). One of: trusted, untrusted.
url string yes url is the peer's A2A JSON-RPC endpoint. Pattern: ^https?://.
  • Rule on spec: requireSignedCard needs cardKeys

Status fields#

A2APeerStatus is the observed state of an A2APeer.

The operator writes status; do not set it yourself.

Field Type Required Description
conditions []object
conditions[].lastTransitionTime string (date-time) yes lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
conditions[].message string yes message is a human readable message indicating details about the transition. This may be an empty string. Max length: 32768.
conditions[].observedGeneration integer (int64) observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. Minimum: 0.
conditions[].reason string yes reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. Min length: 1. Max length: 1024. Pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$.
conditions[].status string yes status of the condition, one of True, False, Unknown. One of: True, False, Unknown.
conditions[].type string yes type of condition in CamelCase or in foo.example.com/CamelCase. Max length: 316. Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$.
gatewayPath string gatewayPath is the path agents call: /a2a//.
observedGeneration integer (int64)