Gateway onboarding: on-prem APIM support via host + on_prem config

[YasasRangika]

Purpose

This PR adds gateway onboarding support so the API Platform Gateway can register and connect to on-prem WSO2 APIM as well as the cloud control plane (Bijira), as described in the design doc "APIM and API Platform Gateway Integration". The same gateway binary is used for both: only configuration changes (host + on-prem flag). No separate WebSocket URL is configured; all URLs are derived from host in code, with the path chosen by on_prem.

Goal

Add gateway onboarding for wso2/api-manager#4665

Approach

1. Configuration (gateway-controller)

• Control plane config
  • ControlPlaneConfig.OnPrem (bool, koanf: on_prem) — When true, use on-prem paths for WebSocket and REST (/internal/data/v1/ws, /internal/data/v1). When false (default), use cloud paths (/api/internal/v1/ws, /api/internal/v1).
  • Env mappings (so standard env vars work):
    • GATEWAY_CONTROLPLANE_HOST / APIP_GW_CONTROLPLANE_HOST → controller.controlplane.host
    • GATEWAY_CONTROLPLANE_ON_PREM / APIP_GW_CONTROLPLANE_ON_PREM → controller.controlplane.on_prem
    • GATEWAY_REGISTRATION_TOKEN / APIP_GW_GATEWAY_REGISTRATION_TOKEN → controller.controlplane.token
  • Validation: When connecting, controlplane.host is required; when on_prem is true, host is required. Existing validation for reconnect/polling intervals unchanged.

2. Control plane client (URL building)

• getWebSocketURL()

  • On-prem: wss://{host}/internal/data/v1/ws
  • Cloud: wss://{host}/api/internal/v1/ws

• getWebSocketConnectURL()

  • Always getWebSocketURL() + "/gateways/connect" (path is the same for both modes).

• getRestAPIBaseURL()

  • On-prem: https://{host}/internal/data/v1
  • Cloud: https://{host}/api/internal/v1

Connection flow is unchanged: gateway sends registration token in api-key header, waits for connection.ack, runs heartbeat monitor; reconnection and backoff behaviour are the same for cloud and on-prem.

3. Tests

• TestClient_getWebSocketURL_OnPrem — Asserts on-prem WebSocket base URL.
• TestClient_getRestAPIBaseURL_OnPrem — Asserts on-prem REST base URL.
• Helper createTestClientWithOnPrem(t, onPrem bool) for client tests.

Design reference

Aligned with the design doc "APIM and API Platform Gateway Integration" (Section 2: Overview — host + on-prem flag; Section 4.3: Gateway client — GATEWAY_CONTROLPLANE_HOST, GATEWAY_CONTROLPLANE_ON_PREM, URL building from host in code; same handshake and keep-alive as API Platform).

On-prem usage (after control plane is set up)

export GATEWAY_CONTROLPLANE_HOST="localhost:9443"
export GATEWAY_CONTROLPLANE_ON_PREM=true
export GATEWAY_REGISTRATION_TOKEN="<token-from-admin-api-create-gateway>"

docker compose up

Summary by CodeRabbit

Release Notes

• New Features
  • Gateway controller now supports on-premises deployment configuration. A new option enables operators to switch between cloud and on-premises modes, with the system automatically routing to the appropriate endpoints based on the selected deployment type.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• ✅ Review completed - (🔄 Check again to review again)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

gateway/gateway-controller/pkg/controlplane/controlplane_test.go (1)

249-262: Good test coverage for OnPrem URL construction.

The test verifies both getWebSocketURL() and getWebSocketConnectURL() for the on-prem case. Consider adding a similar assertion for getWebSocketConnectURL() in the existing TestClient_getWebSocketURL test (cloud mode) for completeness.

💡 Optional: Add cloud mode getWebSocketConnectURL assertion

// In TestClient_getWebSocketURL, add after line 246:
connectURL := client.getWebSocketConnectURL()
expectedConnect := expected + "/gateways/connect"
if connectURL != expectedConnect {
    t.Errorf("getWebSocketConnectURL() = %q, want %q", connectURL, expectedConnect)
}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@gateway/gateway-controller/pkg/controlplane/controlplane_test.go` around
lines 249 - 262, Add the missing assertion for the cloud-mode WebSocket connect
URL in the existing TestClient_getWebSocketURL test: after obtaining url and
expected, call client.getWebSocketConnectURL(), compute expectedConnect as
expected + "/gateways/connect", and assert equality—reporting a useful error via
t.Errorf if they differ; this mirrors the OnPrem test's checks and uses the same
getWebSocketURL and getWebSocketConnectURL methods for locating the change.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@gateway/gateway-controller/pkg/controlplane/controlplane_test.go`:
- Around line 249-262: Add the missing assertion for the cloud-mode WebSocket
connect URL in the existing TestClient_getWebSocketURL test: after obtaining url
and expected, call client.getWebSocketConnectURL(), compute expectedConnect as
expected + "/gateways/connect", and assert equality—reporting a useful error via
t.Errorf if they differ; this mirrors the OnPrem test's checks and uses the same
getWebSocketURL and getWebSocketConnectURL methods for locating the change.