Relay Proxy
The App Configuration Relay Proxy sits between your SDK clients and the IBM Cloud App Configuration service. Instead of every SDK connecting directly to IBM Cloud, SDK clients connect to the proxy within your own network. The proxy fetches and caches configuration from IBM Cloud App Configuration, then delivers it to all connected clients.
Why use the Relay Proxy?
Consider using the Relay Proxy in the following scenarios:
- Reduce outbound calls to IBM Cloud — The proxy opens one upstream connection per configured collection and environment combination regardless of how many SDK instances are deployed in your fleet.
- Air-gap or private-network deployments — SDK clients communicate only with the proxy inside your network. The proxy handles all connectivity to IBM Cloud.
- Single point of authentication — One IBM Cloud IAM API key is required on the proxy. SDK clients authenticate to the proxy using a key that you define.
- Primary and backup instance failover — The proxy automatically switches to a backup IBM Cloud App Configuration instance when the primary is unavailable, and recovers automatically.
- Graceful start from a local seed file — In fast-start mode, the proxy serves configuration immediately from a local seed file while fetching fresh data from IBM Cloud in the background.
How SDK clients connect to the Relay Proxy
SDK clients use the same connection types they use to connect directly to IBM Cloud App Configuration, but they target the proxy host and port instead:
| SDK type | Connection type | Purpose |
|---|---|---|
| Server SDKs | WebSocket | Receive real-time configuration change events |
| Client SDKs | Server-Sent Events (SSE) | Receive configuration snapshots and updates |
| All SDKs | REST | Fetch initial configuration |
Connection multiplexing
One of the primary benefits of the Relay Proxy is connection multiplexing. Hundreds or thousands of SDK instances can connect to the proxy, but the proxy opens only one upstream WebSocket connection per collection × environment combination to IBM Cloud App Configuration. That upstream connection count is fixed by your configuration and never grows with your fleet size.
For example, if you configure two collections (inventory and payments) each used in two environments (dev and prod), the proxy maintains exactly four upstream WebSocket sessions regardless
of how many SDK instances connect to it:
| Upstream WebSocket session | Collection | Environment |
|---|---|---|
| Session 1 | inventory | dev |
| Session 2 | inventory | prod |
| Session 3 | payments | dev |
| Session 4 | payments | prod |
When IBM Cloud App Configuration sends a change event on an upstream connection, the proxy fans it out instantly to all SDK clients subscribed to that combination.
Each collection × environment combination has its own isolated cache slot and upstream WebSocket session inside the proxy.
Startup modes
The Relay Proxy supports two startup modes depending on whether a seed file is configured.
Normal start
In normal start mode, the proxy must successfully contact IBM Cloud App Configuration before it serves any request. If any configuration fetch fails, startup aborts. This mode guarantees that clients always receive authoritative data from their first request.
The startup sequence is as follows:
- Fetch configuration from IBM Cloud App Configuration — all configured combinations are fetched synchronously.
- Cache all configurations in memory.
- Start the HTTP server and accept client requests.
- Open upstream WebSocket sessions for live change notifications, one per combination.
Fast start
In fast-start mode, a seed file pre-warms the cache so the proxy can start serving requests immediately, without waiting for IBM Cloud. Fresh configuration is fetched in the background and pushed to all already-connected clients when available. This mode is suited to air-gap environments and resilient deployments.
The startup sequence is as follows:
- Load the seed file from disk — the cache is pre-warmed instantly, no network call required.
- Start the HTTP server immediately.
- Fetch fresh configuration from IBM Cloud App Configuration in the background — overwrites seed data and notifies all connected clients.
- Open upstream WebSocket sessions for live change notifications, one per combination.
For the seed file format and configuration options, see the App Configuration API reference.
How a configuration change reaches your SDKs
When a configuration change is published in the App Configuration console, the change reaches your SDK clients through the following sequence:
- IBM Cloud App Configuration sends a WebSocket message to the proxy on the relevant upstream session.
- The proxy re-fetches the updated configuration for that combination and stores it in the cache.
- The proxy broadcasts the updated configuration to all connected clients:
- Server SDKs receive a WebSocket event.
- Client SDKs receive an SSE event with the updated configuration payload.
Primary and backup failover
When a backup instance is configured, the proxy provides automatic failover for WebSocket sessions and configuration fetches.
- WebSocket sessions — Each combination maintains its own upstream WebSocket. When the primary instance becomes unavailable, the proxy immediately connects to the backup. The proxy retries the primary instance every 15 seconds and closes the backup connection as soon as the primary recovers.
- Configuration fetches — HTTP configuration fetches follow a primary-then-backup order.
Pointing your SDKs at the Relay Proxy
To connect your SDK clients to the Relay Proxy instead of directly to IBM Cloud:
- Replace the IBM Cloud hostname in your SDK initialization with the proxy's host and port.
- Region, guid, API key, collection_id and environment_id should be same as what passed in the relay proxy configuration.
No other SDK code changes are required.
To get started with the Relay Proxy, reach out to App Configuration support.