Migrating an Existing OpenTelemetry Collector to Bindplane Management

This guide describes how to migrate an existing OpenTelemetry Collector deployment to be managed by the OpAMP Supervisor and connected to Bindplane.

This is a guide for when you already have a collector running on a VM, bare-metal host, or container and want Bindplane to take over remote configuration and lifecycle management without rebuilding or redeploying the collector binary itself.

If you have not yet built a Bindplane-compatible collector, start with Build and Connect Custom OpenTelemetry Collector Distributions instead. This guide picks up after that work is done.

Migration involves stopping the running collector. Plan for a brief telemetry gap and, if your collector tracks state (for example, file log offsets via the filestorage extension), preserve that state directory across the migration to avoid re-ingesting data.

Prerequisites

• An existing OpenTelemetry Collector running on the host you intend to migrate.

• The collector binary was built with at least the minimal set of Bindplane-compatible components. If your existing collector does not include these components, rebuild it before continuing.

• Permissions on the host to stop the existing collector service and run a new process.

• Your Bindplane endpoint and a Bindplane Secret Key.

1. Prepare the Configuration in Bindplane

The OpAMP Supervisor pulls its collector configuration from Bindplane and writes it to a managed location on disk. Once the supervisor takes over, your existing local config.yaml is no longer used. Before stopping the running collector, make sure Bindplane has a Configuration ready to be assigned to it.

You have two options:

• Use Pipeline Intelligence to migrate your configuration into Bindplane. This is the recommended path as it is the fastest way to get your configuration re-created in Bindplane. For more information on this feature, check out this guide on pipeline intelligence.

• Recreate the equivalent pipeline as a Bindplane Configuration. This option gives you full control over migration by individually configuring Bindplane's sources, destinations, and processors.

If your existing collector uses the filestorage extension (commonly used with filelogreceiver for offset tracking), make sure the storage directory referenced in your Bindplane Configuration matches the one your existing collector was using, or copy the contents over before starting the supervisor. Otherwise the new collector will re-read every log file from the beginning.

2. Stop and Disable the Existing Collector

Before installing the supervisor, stop the running collector so the supervisor can start a fresh, managed instance without conflict.

For example, if the collector runs as a systemd service:

sudo systemctl stop <collector-service-name>
sudo systemctl disable <collector-service-name>

If the collector was launched directly as a process, terminate it:

sudo pkill -f <collector-binary-name>

Confirm the process is no longer running and any ports it bound (for example, OTLP receivers on 4317/4318) are free before continuing.

3. Download the OpAMP Supervisor

Download the OpAMP Supervisor binary that matches your collector's OpenTelemetry Collector version from the OpenTelemetry Collector Releases.

For simplicity, place the supervisor binary in the same directory as your existing collector binary so configuration paths stay short and predictable. Make sure the binary is executable:

chmod +x ./opampsupervisor

The supervisor version should match the OpenTelemetry Collector version your existing collector was built with. Mismatched versions can result in capability negotiation failures or unexpected behavior. Refer to the OpenTelemetry Collector Releases page for the correct artifact.

4. Configure the OpAMP Supervisor

Create a file named supervisor.yaml next to the supervisor binary. The following template covers the required fields. Replace each placeholder with the value appropriate for your environment.

server:
  endpoint: wss://<BINDPLANE_ENDPOINT>/v1/opamp
  headers:
    Authorization: "Secret-Key <BINDPLANE_SECRET_KEY>"
  tls:
    insecure: false
    insecure_skip_verify: false

capabilities:
  accepts_remote_config: true
  reports_remote_config: true
  reports_available_components: true

agent:
  executable: <PATH_TO_EXISTING_COLLECTOR_BINARY>
  config_apply_timeout: 30s
  bootstrap_timeout: 5s

storage:
  directory: <SUPERVISOR_STORAGE_DIRECTORY>

The values you need to fill in:

• server.endpoint — Your Bindplane OpAMP endpoint. For Bindplane Cloud this is wss://app.bindplane.com/v1/opamp. For self-hosted Bindplane, use the address of your Bindplane server (typically ws:// for plain text or wss:// for TLS).

• server.headers.Authorization — Your Bindplane Secret Key, prefixed with Secret-Key (note the trailing space). You can find your secret key in the Bindplane UI by navigating to Collectors → Install Collector and looking at the value after the -s flag in the generated install command.

• agent.executable — The absolute or relative path to the existing collector binary on this host.

• storage.directory — A directory the supervisor can read from and write to. The supervisor uses this to persist the collector configuration it receives from Bindplane along with its own state. For production use, a dedicated path such as /var/lib/observiq/supervisor is recommended over the current working directory.

5. Start the Supervisor

Run the supervisor manually to confirm everything is wired up correctly:

./opampsupervisor --config ./supervisor.yaml

On startup, the supervisor will:

• Connect to Bindplane and register the collector

• Pull the assigned configuration and write it to the storage directory

• Launch your existing collector binary with that configuration

• Apply any subsequent configuration changes pushed from Bindplane

Once running, the collector will appear in Bindplane and is fully managed through the platform.

Running the supervisor in the foreground is fine for verification, but for ongoing operation you will want to run it as a service (for example, under systemd on Linux). Configuring a service unit for the supervisor is outside the scope of this guide. Refer to your platform's service management documentation, and ensure the service runs as a user with permission to execute the collector binary and write to the supervisor storage directory.

6. Verify the Migration

Confirm the migration succeeded before walking away:

• In the Bindplane UI, navigate to the Collectors page and locate the host you migrated. The collector should appear as connected and healthy.

• In the supervisor's terminal output (or its log file, if you redirected output), look for successful connection messages and confirmation that the collector process started.

• Validate that telemetry is flowing by checking your destinations or the Recent Telemetry view in Bindplane.

If the agent does not appear in Bindplane, double-check the server.endpoint, the Secret Key, and that the collector binary referenced by agent.executable actually starts (try running it directly to confirm). If the agent appears but reports configuration errors, verify that the Bindplane Configuration assigned to it only uses components that were compiled into your collector.