Install, Upgrade, and Uninstall Agents

Kubernetes Agents

BindPlane manages three different Kubernetes Agent types. Node, Cluster, and Gateway. Each agent type serves a unique purpose within the cluster. They can be used together or independently.

Node

The BindPlane Node agents are deployed as a DaemonSet. The Node agent scales up and down with the size of the cluster. Each individual agent is responsible for collecting logs and metrics from the node it is running on.

Additionally, the Node agent supports receiving OTLP metrics, traces, and logs from other services running in the cluster, via clusterIP service.

Supported Sources

Persistence

The Node agent makes use of Host Path volumes to persist the agent configuration file and exporter persistent queue directories.

The Host Path /var/lib/observiq/otelcol/containeris mounted at /etc/otel/storage within the agent container.

Persistence allows the agents to operate during a BindPlane or backend outage.

Cluster

The BindPlane Cluster agent is deployed as a Deployment. The Cluster agent operates a single pod and is responsible for collecting cluster-level metrics and events (logs). The Cluster agent is not intended to scale above one pod, therefore it is limited to sources that should run on a single replica to avoid duplicate telemetry.

Supported Sources

Gateway

The BindPlane Gateway agents are deployed as a StatefulSet. The Gateway agent is intended to operate as an aggregation layer, allowing other agents or services to forward metrics, traces, and logs to the gateway for additional processing before being shipped to a backend.

The Gateway agent is optional for monitoring a Kubernetes cluster. It should be used during the following situations:

  • Offload processing from the Node and Cluster agent
  • Limit backend access to a dedicated set of agents.
  • You already have a solution for logs and metrics, and need a solution to receive telemetry from services running in the cluster.

Supported Sources

Persistence

The Gateway agent uses a Volume Claim Template to generate and assign volumes to each Gateway agent pod. The volume contains the agent's configuration file and exporter persistent queue directories. If an agent pod is killed or restarted for any reason, the volume assigned to that pod will be attached to the new instance of the pod, allowing the new pod to continue where the previous instance left off.

Persistence allows the agents to operate during a BindPlane or backend outage.

Install

Kubernetes Agent installation has a different flow than normal agents.

Steps

  1. Create a configuration for a Kubernetes platform
    1. Kubernetes Node: Deploys an agent to each node in the cluster using a DaemonSet.
    2. Kubernetes Cluster: Deploys an agent as a single pod Deployment.
    3. Kubernetes Gateway: Deploys a scalable set of agents using a StatefulSet.
    4. OpenShift Daemonset: Deploys an agent to each node in the cluster.
    5. OpenShift Deployment: Deploys an agent as a single pod deployment.
  2. Navigate to the agent's page and select "Install Agents"
  3. Choose a Kubernetes Platform
  4. Select your configuration from step 1
  5. Copy the YAML manifest to a file
  6. Deploy the YAML manifest with kubectl apply -f <file name>

The agents will be deployed to the cluster in the bindplane-agent namespace and connect to BindPlane OP automatically.

Example Installation

Create a configuration using a Kubernetes-compatible source. This example uses the Kubernetes Container Logs source.

observIQ docs - Install, Upgrade, and Uninstall Agents - image 1

Once the configuration has been created, navigate to the Agents page and select "Install Agents".

Select your Kubernetes platform and configuration. You will be prompted to copy the YAML manifest. Copy it and save it to a file.

observIQ docs - Install, Upgrade, and Uninstall Agents - image 2

Ensure that the OPAMP_ENDPOINTenvironment variable has the correct value for your server. If you did not configure ingress, this value should match your deployment clusterIP service name and namespace. In this example, the service name is "my-bindplane" and the namespace is "default".

text
1- name: OPAMP_ENDPOINT
2  value: "ws://my-bindplane.default.svc.cluster.local:3001/v1/opamp"

If you configured ingress, your OPAMP_ENDPOINT should contain the ingress hostname and port. The port should be 80 for non-TLS ingress, and 443 if ingress TLS is enabled. Similarly, the protocol should be ws (websocket) when TLS is not configured, and wss (secure web socket) when TLS is enabled.

Deploy the YAML manifest with kubectl apply -f <manifest file path>. Once deployed, your agent(s) will appear on the Agents page, and they will be bound to your configuration.

observIQ docs - Install, Upgrade, and Uninstall Agents - image 3

Upgrade

BindPlane OP does not support upgrading container-based agents when using the web interface. This is because the container filesystems are immutable and operate with a read-only filesystem. Volumes are used for any data that needs to be written at runtime.

You can upgrade the agent version by re-deploying the agents using the process outlined in the Install section. Alternatively, you can modify the image tag and re-deploy with kubectl apply.

Uninstall

Agents can be uninstalled by using the kubectl delete command against the previously downloaded YAML manifest.

bash
1kubectl delete -f <file name>

If the yaml file is not available, you can clean up all resources with the following commands:

bash
1kubectl -n bindplane-agent delete ds bindplane-node-agent
2kubectl -n bindplane-agent delete deploy bindplane-cluster-agent
3kubectl -n bindplane-agent delete sts bindplane-gateway-agent
4kubectl delete namespace bindplane-agent

Limitations

Change Configurations

Kubernetes agents are bound to a single configuration. Changes to that configuration are supported, however, changing to a new configuration is not supported. To change to a new configuration, you can re-deploy the agents by using the Install Agents page and selecting your new configuration.

Non Kubernetes Agents

Agents running outside of Kubernetes can be installed as long as ingress has been configured. See the getting started guide for agent installation instructions.