Control Plane Connection¶

Note

This step is optional. Configure it only if the gateway needs to sync API artifacts from the WSO2 APIM control plane or API Platform Cloud control plane.

The WSO2 API Platform gateway supports two fundamentally different deployment approaches, distinguished by the direction of API flow.

Top-Down (Control Plane → Gateway)Bottom-Up (Gateway → On-Prem APIM)

In this model, the platform control plane pushes APIs to the gateway via a persistent WebSocket connection. Use this approach when APIs are managed centrally and distributed to one or more gateway instances.

Create a secret for the registration token:

The registration token is generated when you register the gateway with your control plane. Refer to the setup guide for your control plane to obtain it:

kubectl create secret generic gateway-cp-token \
  --namespace <your-namespace> \
  --from-literal=token='your-registration-token'

Configure the chart:

 gateway:
  config:
    controller:
      gateway_name: "prod-gateway"
      server:
        gateway_id: "prod-gateway"
      controlplane:
        insecure_skip_verify: true
        reconnect_initial: 1s
        reconnect_max: 5m
        polling_interval: 15m
        sync_batch_size: 50
        gateway_name: "prod-gateway" # must match the gateway name registered in the controlplane
  controller:
    controlPlane:
      host: "apim-wso2am.example.com:9443"
      token:
        secretName: "gateway-cp-token"
        key: token

In this model, REST APIs deployed directly to the gateway are automatically synced back to an on-premises WSO2 APIM instance. A control plane WebSocket connection is also required alongside the bottom-up sync. API key events, subscription changes, and other lifecycle events are initiated from the control plane devportal and must reach the gateway over this channel.

Note

Bottom-up sync is only supported with APIM 4.7.x. Cloud control plane does not support this flow.

Step 1: Create a secret for the registration token

The registration token is generated when you register the gateway with your control plane. Refer to the WSO2 APIM control plane setup guide to obtain it.

kubectl create secret generic gateway-cp-token \
  --namespace <your-namespace> \
  --from-literal=token='your-registration-token'

Step 2: Generate OAuth2 client credentials

Register a DCR client against your APIM instance to obtain the client ID and secret:

curl -k -X POST https://<APIM_HOST>/client-registration/v0.17/register \
  -H "Content-Type: application/json" \
  -u admin:admin \
  -d '{
    "clientName": "gateway-controller",
    "owner": "admin",
    "grantType": "client_credentials password refresh_token",
    "saasApp": true
  }'

The response contains clientId and clientSecret. Use these in the next step.

Step 3: Store the OAuth2 credentials in a Kubernetes secret

Never place OAuth2 credentials directly in Helm values. Create a secret and inject it via extraEnvFrom instead.

Create apim-oauth-secret.yaml:

apiVersion: v1
kind: Secret
metadata:
  name: apim-oauth-client-secret-secret
  namespace: ap-gateway  # adjust to match your deployment namespace
type: Opaque
stringData:
  APIP_GW_CONTROLLER_CONTROLPLANE_APIM__OAUTH2__CLIENT__ID: "your-client-id"
  APIP_GW_CONTROLLER_CONTROLPLANE_APIM__OAUTH2__CLIENT__SECRET: "your-client-secret"

Apply it:

kubectl apply -f apim-oauth-secret.yaml

Step 4: Configure the chart

Reference both secrets and configure the control plane connection alongside the bottom-up sync settings:

gateway:
  config:
    controller:
      gateway_name: "prod-gateway"
      server:
        gateway_id: "prod-gateway"
      controlplane:
        insecure_skip_verify: true
        reconnect_initial: 1s
        reconnect_max: 5m
        polling_interval: 15m
        sync_batch_size: 50
        gateway_name: "prod-gateway" # must match the gateway name registered in the controlplane
        # apim_oauth2_client_id and apim_oauth2_client_secret are injected via
        # the apim-oauth-client-secret-secret Kubernetes Secret (see extraEnvFrom below).
        # Expected env var names: APIP_GW_CONTROLLER__CONTROLPLANE__APIM_OAUTH2__CLIENT_ID
        #                         APIP_GW_CONTROLLER__CONTROLPLANE__APIM_OAUTH2__CLIENT_SECRET
  controller:
    controlPlane:
      host: "apim-wso2am.example.com:9443"
      token:
        secretName: "gateway-cp-token"         # created in Step 1
        key: token
    deployment:
      extraEnvFrom:
        - secretRef:
            name: apim-oauth-client-secret-secret

Tip

If your organization uses the Resource Owner Password Credentials (ROPC) flow instead of client credentials, store APIP_GW_CONTROLLER__CONTROLPLANE__APIM_OAUTH2__USERNAME and APIP_GW_CONTROLLER__CONTROLPLANE__APIM_OAUTH2__PASSWORD in the secret using the same extraEnvFrom pattern.

← Deploy & Verify | Production Deployment Overview