Skip to main content
Version: 1.0.1

Federations Service

Overview​

The Federations service (FederationsAPI, kamiwaza_sdk/services/federations.py) manages cluster-to-cluster federation pairings and cross-cluster access from the SDK. Access it as client.federations. It covers the federation lifecycle (pair, list, get, probe, disconnect), a per-federation proxy for sub-resources, and brokered-user allowlisting. Cross-cluster identity trust is governed by each federation's identity mode (shared_idp or peer_kc); see the platform Identity Trust Modes guide for the trust model.

Methods​

pair(name, role, *, remote_ips, preshared_key=None, shared_issuer_url=None, ...) -> Federation​

Create a federation pairing. role is the side being set up (initiator or receiver). A pre-shared key is auto-generated (UUID4) when preshared_key is None; supply your own to share a key out-of-band.

Selecting the identity mode: supplying shared_issuer_url (with shared_jwks_url / shared_ca_pem) creates a receiver-controlled shared_idp federation; omitting it creates a legacy source-trusted peer_kc federation (subject to the cluster's ALLOW_UNTRUSTED_FEDERATION policy).

# shared_idp (receiver-controlled)
fed = client.federations.pair(
    name="ORION",
    role="receiver",
    remote_ips=[{"ip": "10.0.0.5", "primary": True}],
    preshared_key=shared_psk,
    shared_issuer_url="https://idp.example/realms/federated",
    shared_jwks_url="https://idp.example/realms/federated/protocol/openid-connect/certs",
)

list() -> List[Federation]​

List all federations on this cluster (GET /cluster/federations). Handles both a bare list and an {"items": [...]} response shape.

get(federation_id) -> Federation​

Fetch a single federation by id (GET /cluster/federations/{id}).

client.federations[name] -> FederationProxy​

Index by name to get a proxy for one federation's sub-resources. The proxy resolves the federation id on first use and caches it.

orion = client.federations["ORION"]
caps  = orion.probe()               # peer capabilities over the mesh
orion.users.add(external_id="alice@peer-uuid")
orion.disconnect()

FederationProxy.probe() -> ClusterCapabilities​

Probe the peer's capabilities through the local mesh proxy. Mesh egress is authenticated-only.

FederationProxy.disconnect(*, force=False) -> Any​

Disconnect (unpair) the federation (POST /cluster/federations/{id}/disconnect). force=True tears down without waiting for the peer.

FederationProxy.users.add(external_id, *, initial_tuples=None) -> BrokeredUser​

Allowlist a brokered remote user on this (receiver) cluster (POST /cluster/federations/{id}/users). external_id identifies the remote subject; initial_tuples seeds the ReBAC grants the user should have on this cluster.

The kamiwaza-fed CLI​

The SDK ships an operator/test utility, kamiwaza-fed (kamiwaza_sdk.seeding.federation), that scripts shared_idp stand-up and ReBAC access seeding. Groups: access (ReBAC grants), fed (pair / status / allow-user / unpair), dataset / gate / attr (gated-retrieval setup), and idp.

The idp group is DEV/TEST-only. Its bootstrap / persona subcommands drive the Keycloak admin API, which the platform ingress does not expose — they need direct Keycloak access (a port-forward). In production, provision the shared realm through the auth chart's install-time Keycloak init-Job pipeline, not this command.

Secrets are always read from environment variables, never passed on the command line.