# 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.

{% hint style="info" %}
[View the `opampgateway` extension docs for a more detailed breakdown for configuration options.](https://github.com/observiq/bindplane-otel-contrib/tree/main/extension/opampgateway)
{% endhint %}

### 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.

<figure><img src="/files/XAakfQDFsgv219gSFfIJ" alt=""><figcaption></figcaption></figure>

Choose the OpAMP Gateway.

<figure><img src="/files/NaQmCyobtJrhAq0L68z0" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/kLYivcC2FGOcAxoDIgqx" alt=""><figcaption></figcaption></figure>

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

```yaml
# 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.

```yaml
# 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.

<figure><img src="/files/mrpN1emgcpH8sHRBlAaT" alt=""><figcaption></figcaption></figure>

### `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:**

```yaml
# 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](https://bindplane.com/blog/opamp-for-opentelemetry-managing-collector-fleets-and-introducing-the-new-opamp-gateway-extension)
* [OpAMP Gateway Extension on GitHub](https://github.com/observIQ/bindplane-otel-collector/tree/main/extension/opampgateway)
* [OpAMP Specification](https://opentelemetry.io/docs/specs/opamp/)
* [OpAMP Extension (opentelemetry-collector-contrib)](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/opampextension)
* [OpAMP Supervisor (opentelemetry-collector-contrib)](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/cmd/opampsupervisor/README.md)
* [Bindplane Distro for OTel Collector](https://github.com/observIQ/bindplane-otel-collector)
* [Bindplane OpAMP Configuration docs](https://github.com/observIQ/bindplane-otel-collector/blob/main/docs/opamp.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bindplane.com/feature-guides/deployment-and-management/opamp-gateway.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.