Deploy BindPlane OP Server

Install BindPlane OP server on Kubernetes

Architecture

Deployment Types

StatefulSet

BindPlane OP can operate as a single pod StatefulSet by default when using the default bboltstorage backend. In this configuration, a persistent volume claim is utilized to persist data between pod restarts and upgrades.

This architecture is not highly available, meaning there will be brief downtime when the BindPlane OP pod is restarted due to updates. All managed agents will re-connect automatically. Managed agents will continue to function without downtime, while BindPlane OP is unavailable.

BindPlane OP Open Source and Enterprise editions support running as a Statefulset.

Highly Available Deployment (Enterprise)

The Enterprise edition of BindPlane OP supports operating as a highly available deployment with multiple pod replicas. Persistent storage is handled using a shared database and an external event bus such as Google's PubSub.

Official support for high-availability deployments is coming soon.

Ingress

An ingress rule is used to provide external access to the cluster for Web browser interaction and management of external agents running outside of the cluster.

Ingress is optional. Omitting the ingress deployment will impose the following restrictions:

  • Web browser interaction will rely on the kubectl port-forward command, for exposing BindPlane to your workstation.
  • Only agents running within the cluster will be managed.

Resources

The following Kubernetes resources are created when installing BindPlane OP using a minimal configuration.

  • Service account: Service account without additional RBAC as BindPlane OP does not require permission to the cluster.
  • Service (clusterIP): For client communication.
  • StatefulSet or Deployment

Advanced configurations may result in additional resources being deployed, such as ingress or horizontal pod autoscaler resources.

Prerequisites

Supported Distributions

The following Kubernetes distributions are officially supported:

  • Google Kubernetes Engine (GKE)
  • Amazon Elastic Kubernetes Service (EKS)
  • Azure Kubernetes Service (AKS)
  • OpenShift 4.x

System Requirements

  • Storage class which supports persistent volume claims (When running as a StatefulSet).
  • Sufficient CPU and Memory capacity.
    • 250m CPU and 250Mi Memory are requested by default. It is recommended that these values be increased.
    • See the instance sizing guidelines for recommended CPU and memory capacity.
  • Ingress (optional) if managing agents outside of the cluster.

Install and Upgrade

Helm

The BindPlane OP Helm Chart can be used to deploy BindPlane OP to your Kubernetes Cluster.

Add Repository

Add the BindPlane OP chart to your Helm installation with the following commands:

shell
1helm repo add "bindplane" \
2    "https://observiq.github.io/bindplane-op-helm"
3
4helm repo update

Install

Configuration

Create a values.yaml file and add the following options:

  • config.username: The username you would like to use for BindPlane's super user.
  • config.password: The password you would like to use for BindPlane's super user.
  • config.secret_key: A new random UUIDv4 to use for securing communication between BindPlane and managed agents.
  • config.sessions_secret: A new random UUIDv4 to use for generating web interface session cookies.

The values.yaml file should look something like this, with unique values specific to your deployment.

yaml
1config:
2  username: 'admin'
3  password: 'admin'
4  secret_key: '13c15d7c-233e-49e3-bef4-f7498f33518f'
5  sessions_secret: 'a4e5aa85-5df4-4edd-8cfe-d8a7257d09dd'

You can find a full list of supported configuration options in the here .

Deploy

Deploy BindPlane OP with your values.yaml configuration using the helm upgrade command, which is suitable for installing new deployments and upgrading existing deployments.

bash
1helm upgrade --install "bindplane" \
2    --values "values.yaml" \
3    --namespace bindplane \
4    --create-namespace \
5    bindplane/bindplane

Helm will deploy or upgrade BindPlane OP in the namespace bindplane using the configuration specified in your values.yaml file.

Upgrade BindPlane OP

BindPlane OP can be upgraded by updating your local Helm and then re-deploying with the helm upgrade command.

The helm search repo bindplane command can be used to display the chart and application version.

bash
1helm repo update
2helm upgrade --install"bindplane" \
3    --values "values.yaml" \
4    --namespace bindplane \
5    --create-namespace \
6    bindplane/bindplane

Kubernetes Manifest

Users who wish to avoid deploying BindPlane OP with Helm can do so by generating their manifest with the helm templatecommand.

Install

bash
1helm template "bindplane" --values values.yaml bindplane/bindplane > bindplane.yaml
2kubectl apply -f bindplane.yaml

The output of helm template can be saved to a file and deployed with kubectl.

Upgrade

BindPlane OP can be upgraded by modifying the image tag and re-deploying with kubectl

yaml
1containers:
2  - name: server
3    image: ghcr.io/observiq/bindplane:1.13.0

Access BindPlane OP

By default, BindPlane OP is deployed without ingress. This means:

  • Port forwarding is used for access
  • BindPlane can only manage agents in the cluster.

To access BindPlane, run the following command.

text
1kubectl -n bindplane port-forward svc bindplane 3001

This command assumes that BindPlane was deployed to the bindplane namespace and the clusterIP service's name is bindplane.

Once port forwarding is running, you can access BindPlane with your browser at http://localhost:3001

Ingress

BindPlane OP's Helm chart supports ingress. When ingress is configured, BindPlane can be accessed without port forwarding, and agents from outside of the cluster can be managed.

See the Production Example section of this doc for instructions on configuring ingress.

Production Example

This section provides an example configuration for production-grade deployments of BindPlane OP on Kubernetes.

This example deploys BindPlane OP server to Google Kubernetes Engine (GKE) as a StatefulSet with ingress and transport layer security (TLS). The steps shown here can be adapted to work on any Kubernetes cluster.

Prerequisites

  • Ingress: Managed agents and web browsers will connect to BindPlane through an ingress service.
    • This example assumes you would like to manage agents that are running outside of the cluster.
    • Ingress is optional if you would like to manage agents which are internal to the cluster.
  • DNS: You must create a DNS record for the ingress hostname
  • Storage class that supports persistent volumes: BindPlane OP relies on a volumeClaimTemplate for persistent storage

Configuration

Create a values.yaml file based on this example:

yaml
1config:
2  username: 'admin'
3  password: 'admin'
4  secret_key: '1b66fdab-dc7c-4316-872c-e3556f326103'
5  sessions_secret: '1b66fdab-dc7c-4316-872c-e3556f326103'
6  server_url: 'http://bindplane.data-metric.com:80'
7
8backend:
9  bbolt:
10    volumeSize: '120Gi'
11
12resources:
13  requests:
14    cpu: '500m'
15    memory: '1024Mi'
16  limits:
17    memory: '1024Mi'
18
19ingress:
20  enable: true
21  host: 'bindplane.data-metric.com'
22  class: 'gce'

Modify this example

  • Set a secure value for config.username
  • Set a secure value for config.password
  • Replace config.secret_key and sessions_secret with new and random UUIDv4 values.
  • Update ingress.hostto your desired hostname.
    • You must have DNS access for this domain.
    • Once BindPlane is deployed, you will need to manually create a DNS record if you do not have automatic DNS provided by a service such as External DNS.
  • Set config.server_url to match your ingress.host value.
  • Optionally update ingress.class if you wish to use a different ingress class. GKE has the GCE ingress class by default.

Deploy

Deploy to the namespace bindplane and name the Helm deployment bindplane.

bash
1helm upgrade --install "bindplane" \
2    --namespace "bindplane" \
3    --create-namespace \
4    --values "values.gke.yaml" \
5    bindplane/bindplane

Once deployed, the following will be present in the bindplane namespace:

  • StatefulSet named bindplane (One pod)
  • Service named bindplane with port 3001
  • Persistent volume named bindplane-data-bindplane-0
  • Ingress named bindplane

DNS

Once BindPlane has been deployed, the GKE cluster will deploy a load balancer for the ingress object. This process will take a few minutes.

DNS must be configured properly for your browser and managed agents to connect to BindPlane using the ingress hostname.

Once the load balancer is deployed, you can check its IP address with kubectl -n bindplane get ingress

text
1NAME        CLASS    HOSTS                       ADDRESS          PORTS   AGE
2bindplane   <none>   bindplane.data-metric.com   34.107.187.193   80      12m

You will need to create a DNS record for your hostname, pointing to the IP address that is bound to the load balancer. You can do this two ways

  1. Using your domain hosting provider's DNS portal
  2. Using automation with tools such as External DNS

Install Agents

After deploying BindPlane and configuring DNS, you can navigate to your ingress hostname and log in using the username and password defined in your Helm values file.

Linux / Windows

Linux and Windows agents can be installed using the "Install Agents" option on the Agents page.

observIQ docs - Deploy BindPlane OP Server - image 1

Ensure that the agent install command includes the correct hostname. In this example, we expect the install command to use ws://bindplane.data-metric.com:80/v1/opamp. This is derived from the config.remote_urlHelm option. It is the endpoint used by agents to connect to BindPlane using the OpAMP protocol.

Copy and run the install command on your agent system. Once installed, the agent will become available on the Agents page.

observIQ docs - Deploy BindPlane OP Server - image 2

Kubernetes

Kubernetes-based agents can be installed within the same cluster as BindPlane, or a separate cluster. In both scenarios, the ingress hostname will be used for connectivity.

Deploy a Kubernetes agent with the following steps:

  1. Create a Kubernetes configuration on the Configs page.
  2. Choose "Install Agents" on the Agents page.

The agent install page will present a Kubernetes YAML manifest. Copy this manifest to a file and ensure that the environment variable OPAMP_ENDPOINTvalue is derived from the config.remote_urlvalue set in your Helm values file. Additionally, the OPAMP_SECRET_KEY should match the value used for config.secret_key.

observIQ docs - Deploy BindPlane OP Server - image 3

In this example, the environment configuration looks like this:

text
1env:
2  - name: "OPAMP_ENDPOINT"
3    value: "ws://bindplane.data-metric.com:80/v1/opamp"
4  - name: "OPAMP_SECRET_KEY"
5    value: "13c15d7c-233e-49e3-bef4-f7498f33518f"

Apply the manifest to your cluster with kubectl apply -f <file name>.

After a few moments, your agents will appear in on the Agents page.

observIQ docs - Deploy BindPlane OP Server - image 4

Ingress Transport Layer Security (TLS)

The BindPlane OP Helm chart supports configuring the ingress rule to use TLS.

Usage

Create a secret named "bindplane-tls" and add your TLS certificate to it. This secret must be created in the same namespace that BindPlane is deployed to.

Update your Helm values configuration with the following changes

  • config.server_url should contain https and port 443
  • ingress.tls.enable should be set to true
  • ingress.tls.secret should be set to the name of the TLS secret
text
1config:
2+  server_url: "https://bindplane.data-metric.com:443"
3...
4ingress:
5  enable: true
6  host: bindplane.data-metric.com
7  class: gce
8+ tls:
9+   enable: true
10+   secret: bindplane-tls

You can re-deploy BindPlane using the same Helm command used for initial deployment.

Update Existing Agents

Agents that were previously connected to BindPlane without TLS will need to be updated. This guide assumes that the certificate used for BindPlane's ingress is trusted by all agent systems.

Linux / Windows

Update the agents manager.yaml. The manager configuration can be found in /opt/observiq-otel-collector on Linux and observIQ OpenTelemetry Collectoron Windows.

Update the endpoint parameter to use wss and port 443.

text
1#endpoint: "ws://bindplane.data-metric.com:80/v1/opamp"
2endpoint: "wss://bindplane.data-metric.com:443/v1/opamp"
3secret_key: "13c15d7c-233e-49e3-bef4-f7498f33518f"
4agent_id: "01GYWP11HNTHDQNB2MAM2FH7HW"

Once updated, restart the collector service.

Kubernetes

Kubernetes agents can be updated to use TLS with the following steps.

  1. Navigate to the Agents page and select "Install Agents"
  2. Choose the Kubernetes platform and configuration for your agents
  3. Copy the YAML manifest to a file and apply it with kubectl apply.

The YAML manifest generated by the BindPlane web interface will include an updated value from the OPAMP_ENDPOINT environment variable.

TLS External Documentation