GitOps

BindPlane OP's API allows developers to manage configuration state with GitOps.

This guide will showcase how to use Github actions for automating the deployment of resources to BindPlane OP.

Prerequisites

The following prerequisites must be satisfied before BindPlane can be automated.

BindPlane Authentication

You must have access to your BindPlane OP Server using an API key (when multi-project is enabled) or username and password (when single-project is enabled).

BindPlane CLI

You must have the ability to run CLI commands against your BindPlane OP server from your workstation.

You can create a quick CLI profile with the following commands (where gitflow is the name of the profile`):

1bindplane profile set "gitflow" --remote-url http://<host>:3001 --api-key <api key>
2bindplane profile list
3bindplane profile use "gitflow"
4bindplane get agents

If you are using a username and password, replace the --api-key flag with the --username and --password flags.

See the CLI documentation for more information.

Network Access

BindPlane OP must be reachable by the CI/CD "runner". If your BindPlane OP server is hidden behind a corporate firewall, you can look into using Self-hosted Runners.

Most installations of BindPlane will be listening on port 3001 unless configured otherwise or placed behind a load balancer.

Repository

You must have a new or existing repository that you can use while following this guide. This repository will be used to store BindPlane resource files as well as rendered OpenTelemetry "raw" configuration files.

Github Actions

Repository Secrets

The following repository secrets must be defined in your repository.

• BINDPLANE_REMOTE_URL: The remote URL of your BindPlane OP server, usually in the form of http://<hostname>:3001.
• BINDPLANE_API_KEY: API key if you do not want to use a username and password

BindPlane supports username and password, however, an API key is required when multi-project is enabled. If BindPlane is not configured for multi-project, you must have the following secrets for your basic authentication username and password.

• BINDPLANE_USERNAME
• BINDPLANE_PASSWORD

Export Existing Resources

Existing resources should be exported to your repository before enabling the Github Action.

1bindplane get destination -o yaml --export > destinations.yaml
2bindplane get configuration -o yaml --export > configurations.yaml

This will output all existing destinations to destinations.yaml and configurations to configurations.yaml. You can move these files to any directory within your repository. Make a note of where they live, as their paths will be required when configuring the GitHub Action.

Sensitive Values

Destinations and configurations that have sensitive values (passwords, tokens, API keys) will not export the actual value. Instead, the value will be a placeholder "(sensitive)". BindPlane will never allow you to retrieve a sensitive value.

BindPlane destination resource example:

1apiVersion: bindplane.observiq.com/v1
2kind: Destination
3metadata:
4  id: google
5  name: google
6spec:
7  type: googlecloud
8  parameters:
9    - name: project
10      value: my-project
11    - name: auth_type
12      value: json
13    - name: credentials
14      value: (sensitive)
15      sensitive: true

Raw OTEL configuration example:

1exporters:
2  googlecloud/google:
3    credentials: (sensitive)

When the configuration is pushed to the agent, the correct value will be included in the configuration.

Github Action Workflow

Create a new workflow at .github/workflows/bindplane.yml. Open the observIQ/bindplane-op-action repository to view the full list of configurable parameters.

1name: bindplane
2
3on:
4  push:
5    branches:
6      - main
7
8# Required for writing back otel configs to the repo.
9permissions:
10  contents: write
11
12# Prevents concurrent and potentially out of order
13# resource updates.
14concurrency:
15  group: ${{ github.head_ref || github.ref_name }}
16  cancel-in-progress: false
17
18jobs:
19  bindplane:
20    runs-on: ubuntu-latest
21    steps:
22      - name: Checkout
23        uses: actions/checkout@v4
24        with:
25          fetch-depth: 0
26
27      - uses: observIQ/bindplane-op-[email protected]
28        with:
29          bindplane_remote_url: ${{ secrets.BINDPLANE_REMOTE_URL }}
30          bindplane_api_key: ${{ secrets.BINDPLANE_API_KEY }}
31          target_branch: main
32          destination_path: destinations.yaml
33          configuration_path: configurations.yaml
34          enable_otel_config_write_back: true
35          configuration_output_dir: otel/
36          token: ${{ secrets.GITHUB_TOKEN }}

If using username and password, replace the bindplane_api_key option with:

1bindplane_username: ${{ secrets.BINDPLANE_USERNAME }}
2bindplane_password: ${{ secrets.BINDPLANE_PASSWORD }}

Update target_branch: main to point to the branch you wish to use as your source of truth. When the action is running against this branch, it will apply resources to BindPlane.

Make sure destination_path and configuration_path point to the relative path of the previously exported destination and configuration resource files.

If you do not wish to write back the raw OpenTelemetry configuration files to the repo, set enable_otel_config_write_back to false.

Commit and Test

Commit the destination resource, configuration resource, and actions workflow YAML files to the repository. If committing to a branch other than the target_branch, make sure to open a pull request to merge these changes to the target branch.

Once the target branch has the BindPlane resources and the actions workflow, you should see the action running under the repository's "Actions" tab.

Because the existing resources are up to date with the repository's resources, the results will be uneventful. The actions will pass without taking action. If enable_otel_config_write_back is set to true, the action will have committed the raw OpenTelemetry configuration back to the repo.

You can test changes by editing one of the resources in the repository (destinations.yaml or configurations.yaml). Save and commit the change to the target branch either directly or by using your pull request workflow.

Once the change is merged into the target branch, the following will happen:

1. The action will apply the resources to BindPlane
2. All affected BindPlane configurations will have a pending rollout
3. The updated raw OpenTelemetry configurations will be committed back to the repo if enable_otel_config_write_back is true

Configurations that have a pending rollout can be triggered by BindPlane Web Interface users.

Automatic Rollout

The action can be configured to trigger rollouts automatically after updating a configuration.

Set enable_auto_rollout to true.

1- uses: observIQ/bindplane-op-[email protected]
2  with:
3    bindplane_remote_url: ${{ secrets.BINDPLANE_REMOTE_URL }}
4    bindplane_api_key: ${{ secrets.BINDPLANE_API_KEY }}
5    target_branch: main
6    destination_path: destinations.yaml
7    configuration_path: configurations.yaml
8    enable_otel_config_write_back: true
9    configuration_output_dir: otel/
10    token: ${{ secrets.GITHUB_TOKEN }}
11    enable_auto_rollout: true

Updating Resources

Resources can be updated using two methods. You can edit the resources (destination and configuration YAML files) files directly or you can edit resources in the BindPlane UI and export them using the CLI, similar to the original export covered at the beginning of this guide.

Direct Edit

Direct edits can be done by editing the configuration files that the action is pointing to.

1destination_path: destinations.yaml
2configuration_path: configurations.yaml

In this example, the otlp_grpc destination's grpc_port is updated from 4317 to 44317.

1---
2apiVersion: bindplane.observiq.com/v1
3kind: Destination
4metadata:
5  id: bindplane-gateway-agent
6  name: bindplane-gateway-agent
7spec:
8  type: otlp_grpc
9  parameters:
10    - name: grpc_port
11      value: 44317

You can use git diff to view your changes.

With the changes in place, commit the change directly to the target branch (branch the action is deploying changes from) or go through your normal pull request and review workflow with your team.

Once the change is merged or committed to the target branch, the action will deploy the change to BindPlane.

If Auto Rollout is not enabled, you will need to log into BindPlane's web interface and trigger the rollout manually.

UI Export

As an alternative to editing the resource files directly, you can modify configurations in the web interface and re-export them to your repository.

1. Edit the configuration within the BindPlane web interface.
2. Do NOT roll the configuration out.
3. Re-run the CLI export commands in the Export Existing Resources section.
4. Verify the changes with git diff
5. Commit the changes to the target branch, or follow a pull request workflow to merge the changes to the target branch.

Once the change is merged or committed to the target branch, the action will deploy the change to BindPlane.

If Auto Rollout is not enabled, you will need to log into BindPlane's web interface and trigger the rollout manually.

Updating Sensitive Values

At this time, sensitive values must be updated by following the UI Export workflow. It is important to avoid storing sensitive values in the Git repository.

Role Based Access Control

When using the action with Auto Rollout enabled, it is recommended to restrict your Web Interface user's access by using RBAC.

You can allow users to make configuration changes and prevent them from rolling the configuration out by setting their permission level to user. See the Rollout Permissions guide for more information.