OpAMP Gateway

The OpAMP Gateway Extension is a relay between downstream OpAMP-supported OpenTelemetry Collectors and an upstream OpAMP server like Bindplane. It is not a separate binary — it runs inside a collector process deployed at the network boundary.

How the Gateway Works

The opampgateway keeps a fixed pool of upstream WebSockets (default 3) and assigns each new agent to the connection with the fewest agents, so the server sees only a small number of upstream links no matter how many agents connect.

It relays OpAMP messages without changing them—agent-to-server traffic goes out on the gateway's upstream connection, and server-to-agent replies are routed back using an internal mapping—so agents and server behave as if the connection topology were direct.

Authentication is not implemented in the gateway. When an agent connects to the gateway, it accepts the session and authenticates with Bindplane.

View the opampgateway extension docs for a more detailed breakdown for configuration options.

Prerequisites

• BDOT Collector v1.95.0 or greater on any collector that will run the gateway extension

• Network access:

  • The gateway must have outbound access to the OpAMP server

  • Agents must have outbound access to the gateway

• A created Configuration in Bindplane to roll out to the gateway

Step 1: Create an OpAMP Extension in Bindplane

Create a configuration and click the bottom right ⚙️ to open the extensions.

Choose the OpAMP Gateway.

Configure it to point to Bindplane's OpAMP endpoint. Enable TLS and set the downstream listener to localhost and port 4320.

This will configure an extension in your BDOT collector's config.yaml file:

# gateway-collector-config.yaml
extensions:
  opampgateway:
    server:
      endpoint: wss://app.bindplane.com/v1/opamp
      headers:
        Authorization: "Secret-Key ${env:OPAMP_SECRET_KEY}"
      connections: 3
    listener:
      endpoint: 0.0.0.0:4320
      tls:
        cert_file: /etc/otel/server.crt
        key_file:  /etc/otel/server.key

You do not need to manually configure anything since Bindplane will remotely push down this config when you roll it out to the gateway collector.

Step 2: Configure Downstream Agents

Point each agent collector's OpAMP connection at the gateway instead of the upstream server. Only the endpoint changes — capabilities and all other settings remain identical.

You'll do this using the manager.yaml:

• The only line that needs to be updated is the endpoint, point to the OpAMP Gateway instead of Bindplane directly.

# manager.yaml
agent_id: xxx
endpoint: ws://<opamp-gateway>:4320/v1/opamp   # <-- gateway address of the collector running the opamp gateway extension
extra_measurements_attributes:
    agent: xxx
    configuration: ""
    interval: 10s
    version: v2
measurements_interval: 10s
secret_key: ${OPAMP_SECRET_KEY}  # <-- Bindplane Secret Key
topology_interval: 1m0s

Step 3: Verify Connectivity

1. Check gateway collector logs for successful upstream WebSocket connections.

2. Verify agents appear in your OpAMP server's fleet view (e.g. Bindplane Agents UI).

3. Roll out the configuration from Bindplane and confirm it is applied to the gateway.

manager.yaml Reference

The manager.yaml file defines the BDOT collector's OpAMP connection — separate from config.yaml, which defines the telemetry pipeline. When Bindplane rolls out a pipeline config to an agent, config.yaml is remotely updated; manager.yaml stays stable.

Default file locations:

• Linux: /opt/observiq-otel-collector/manager.yaml

• Windows: C:\Program Files\observIQ OpenTelemetry Collector\manager.yaml

• Docker: path set by the MANAGER_YAML_PATH environment variable

Field	Required	Description
endpoint	Yes	WebSocket URL of the OpAMP server or gateway (ws:// or wss://)
secret_key	Yes	Shared secret for authenticating with the OpAMP server
agent_id	No	Stable unique identifier (ULID or UUID). Auto-generated on first connection. Do not change — the server uses it to recognize the agent across restarts
labels	No	key=value pairs for grouping and targeting in Bindplane
agent_name	No	Human-readable name shown in the Bindplane UI
measurements_interval	No	How often the agent reports throughput metrics upstream
topology_interval	No	How often the agent reports topology information upstream
extra_measurements_attributes	No	Additional key-value attributes attached to measurement data
tls_config.ca_file	No	Custom CA certificate path (for self-signed server certs)
tls_config.insecure_skip_verify	No	Skip TLS verification — for testing only
tls_config.cert_file / key_file	No	Client certificate and key for mTLS

Annotated example:

# The WebSocket URL of the OpAMP server or gateway.
# When routing through the opampgateway, point this at the gateway host — not Bindplane directly.
# ws://  = plain WebSocket (non-TLS)
# wss:// = secure WebSocket (TLS)
endpoint: ws://192.168.64.1:4320

# Shared secret for authenticating with the OpAMP server.
secret_key: your-secret-key

# Stable unique identifier for this agent (ULID or UUID).
# Auto-generated on first connection. Changing this registers a new agent.
agent_id: 019cfcb9-4c26-7e18-8e58-aac26ba66fba

# How often the agent sends throughput measurements upstream.
measurements_interval: 10s

# How often the agent reports topology information.
topology_interval: 1m0s

# Extra attributes attached to measurement data reported by this agent.
extra_measurements_attributes:
  agent: 019cfcb9-4c26-7e18-8e58-aac26ba66fba
  configuration: my-pipeline-config
  interval: 10s
  version: v3

# TLS config — only needed when using wss:// endpoint.
# tls_config:
#   ca_file: /etc/otel/certs/ca.crt
#   insecure_skip_verify: false
#   cert_file: /etc/otel/certs/client.crt  # mTLS only
#   key_file:  /etc/otel/certs/client.key   # mTLS only

Key things to know:

• Only endpoint is required. If neither manager.yaml nor OPAMP_ENDPOINT env var is present, the collector starts in standalone mode with no OpAMP connection.

• In Docker, manager.yaml is auto-generated at the MANAGER_YAML_PATH location from environment variables. You don't need to create it manually.

• When spinning up fresh Docker containers, clear any existing manager.yaml in the storage volume to avoid the agent reconnecting with a stale identity.

• The telemetry pipeline (config.yaml) is pushed remotely from Bindplane after the agent connects — you do not need a local pipeline config for managed agents.

Further Reading

• OpAMP Gateway Extension Announcement

• OpAMP Gateway Extension on GitHub

• OpAMP Specification

• OpAMP Extension (opentelemetry-collector-contrib)

• OpAMP Supervisor (opentelemetry-collector-contrib)

• Bindplane Distro for OTel Collector

• Bindplane OpAMP Configuration docs