# Migrating an Existing OpenTelemetry Collector to Bindplane Management 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](https://docs.bindplane.com/how-to-guides/collector-management/bring-your-own-collector/using-an-opentelemetry-distribution-with-bindplane) instead. This guide picks up after that work is done. {% hint style="warning" %} 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. {% endhint %} #### 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](https://docs.bindplane.com/how-to-guides/collector-management/bring-your-own-collector/using-an-opentelemetry-distribution-with-bindplane#id-1.-building-your-opentelemetry-collector-distribution). 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](/feature-guides/pipeline-intelligence/pipeline-intelligence.md#migrate-configurations). * **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. {% hint style="info" %} 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. {% endhint %} #### 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: ```bash sudo systemctl stop sudo systemctl disable ``` If the collector was launched directly as a process, terminate it: ```bash sudo pkill -f ``` 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](https://github.com/open-telemetry/opentelemetry-collector-releases/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: ```bash chmod +x ./opampsupervisor ``` {% hint style="info" %} 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](https://github.com/open-telemetry/opentelemetry-collector-releases/releases) page for the correct artifact. {% endhint %} #### 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. ```yaml server: endpoint: wss:///v1/opamp headers: Authorization: "Secret-Key " tls: insecure: false insecure_skip_verify: false capabilities: accepts_remote_config: true reports_remote_config: true reports_available_components: true agent: executable: config_apply_timeout: 30s bootstrap_timeout: 5s 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: ```bash ./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. {% hint style="info" %} 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. {% endhint %} #### 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. --- # 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/how-to-guides/collector-management/bring-your-own-collector/migrating-an-existing-opentelemetry-collector-to-bindplane-management.md?ask= ``` 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.