Federation Manager (FM)¶

The East/Westbound Interface between Operator Platforms.

The Federation Manager lets two operators' platforms use each other's edge zones. It speaks the GSMA OPG.04 East/Westbound Interface (EWBI) with the Federation Manager of every partner operator, and inside the platform it hands the work to the Service Resource Manager (SRM), the same way a local request would go. Seen from one request, the operator whose App Provider asked is the Leading OP and the operator that runs the workload is the Partner OP; every platform plays both roles, with different partners or at different times. FM never touches infrastructure and offers nothing to App Providers: OEG faces them, SRM runs the workloads, and FM is the only component that talks to other operators.

What it does¶

• Terminates the OPG.04 EWBI for partners under /operatorplatform/federation/v1: federation lifecycle, zone offer and subscription, application onboarding, application install and removal, and the Device Location and Quality on Demand service APIs.
• Authenticates every partner call with an OAuth2 client-credentials token from our Keycloak realm federation, and fetches tokens from each partner's own authorization server for the calls it makes.
• Keeps the partner registry in fm_db: one agreement per partner (which of our zones it may use, and on what terms), the federation contexts in both directions, the zones each side offers, and an audit row for every cross-operator transaction.
• Turns an accepted partner request into the command.srm.* command OEG would have sent, and runs our own deploys on a partner's zone when SRM hands them over (command.fm.service.deploy / .terminate).
• Strips internal IPs, cluster, namespace, pod and node names before any answer leaves the operator.

Read in the specs¶

The FM specification is four documents. Start from the question that matches what you need:

A federated deploy, end to end¶

The App Provider doesn't do anything special: it picks a zone that happens to belong to a partner. SRM notices the zone isn't local and hands the deploy to FM, which talks to the partner's FM.

sequenceDiagram
    autonumber
    participant AP as App Provider
    participant OEG as OEG (Leading OP)
    participant SRM as SRM (Leading OP)
    participant FMa as FM (Leading OP)
    participant FMb as FM (Partner OP)
    participant SRMb as SRM (Partner OP)
    AP->>OEG: POST /appinstances (partner zone)
    OEG->>SRM: command.srm.service.deploy
    SRM->>FMa: GET /internal/federated-zones/{zoneId}
    SRM->>FMa: command.fm.service.deploy
    FMa->>FMb: OPG.04 onboarding (first time only)
    FMa->>FMb: OPG.04 InstallApp
    FMb->>SRMb: command.srm.service.deploy
    SRMb-->>FMb: event.srm.operation.completed
    FMb-->>FMa: onInstanceStatusEvent callback (READY)
    FMa-->>SRM: event.fm.operation.completed
    SRM-->>OEG: event.srm.operation.completed

FM onboards the application at the partner the first time one of its instances goes there, and reuses that onboarding afterwards. Only applications whose image or chart sits in a public repository can be onboarded at a partner in this release.

APIs¶

FM has two HTTP surfaces on two ports, and nothing else can reach the second one.

/internal/* answers only on 8083. On the EWBI port it returns the same 404 as a path that doesn't exist, so exposing 8082 through a NodePort or an ingress never exposes the internal API.

The GSMA OPG.04 EWBI Federation API¶

Built in Release 2:

Not built yet: GetFederationAPIs, UpdateFederation, GetFederationContextId, RenewFederation, GetPlatformCapabilities, GetAppInstanceDetails, the DeviceStatus service API and the onZoneResourceUpdateEvent callback.

Try it on your install¶

FM serves its own API description, generated from the code, at /docs (Swagger UI) and /openapi.json on the EWBI port. On kind that's http://localhost:30989/docs. The internal routes appear there too, but calling them on this port gives 404, as explained above.

curl -s http://localhost:30989/healthz          # FM is up
curl -si http://localhost:30989/operatorplatform/federation/v1/partner \
  -X POST -H 'Content-Type: application/json' -d '{}' | head -1   # 401: no partner token

A real EWBI call needs a token from the realm federation, issued to a client that FM knows as a registered, active partner. On kind that realm already has two partner clients, originating-op-1 and originating-op-2, with their secrets in keycloak-credentials under federation-<client id>-secret. The simplest way to see the whole exchange is to let a second platform make the calls: Federate two operators does exactly that.

Code and deployment¶

Things to know before you deploy it:

• No login, no FM. With global.auth.enabled=false the chart doesn't install FM at all, because partners have to authenticate.
• FM is the only JetStream user. It creates the OOP_TASKS and OOP_EVENTS streams at startup. OEG and SRM use plain NATS. The chart README explains how to watch the JetStream volume.
• Callback links must be reachable by partners. FM hands partners the URLs to call it back on. Set federation-manager.publicUrl to the address partners reach FM on; the kind default, http://localhost:30989, only works for a partner on the same machine.
• Partner secrets are encrypted with a key you must keep. The chart generates federation-manager-keys on first install. Back it up with the database: losing it makes every stored partner secret unreadable.
• The internal API has no login in this release. It relies on being reachable only inside the cluster, on the ClusterIP Service federation-manager-internal.
• Plain-HTTP partners are refused unless allowInsecurePartnerEndpoints is true, which is meant for test networks only.

To run two or more platforms and federate them, see Deploy with Ansible.