Kubernetes Dynamic Cluster Name

OpenTelemetry publishes semantic conventions for common resources. The OpenTelemetry Kubernetes Semantic Conventions can be found here.

BindPlane detects most of the resource attributes when using the Kubernetes sources. BindPlane does not detect the cluster name (k8s.cluster.name) because Kubernetes does not have the concept of a name. It is crucial to set k8s.cluster.name to filter between multiple clusters in your environment.

BindPlane has three methods for setting the k8s.cluster.name resource attribute.

  • Static configuration value
  • Environment variable
  • Resource Detection

Static Cluster Name

BindPlane's Kubernetes source types require the user to input a static cluster name. This is the easiest way to set the cluster name.

See the source type documentation for details:

Using a static cluster name will mean that you need one configuration per Kubernetes cluster. This solution is simple, but will not scale well in large environments. If you wish to use a single agent configuration for many clusters, see the Environment Variable and Resource Detection sections.

Environment Variable

BindPlane can use the Add Fields Processor to update the k8s.cluster.name resource attribute to the value of an environment variable.

Use a placeholder cluster in your configuration's source(s).

Cluster Name Placeholder

Next, use the Add Fields Processor to upsert the resource attribute k8s.cluster.name with the value of the environment variable CLUSTER_NAME.

Add Field Cluster Name

Follow the agent installation workflow to retrieve the Kubernetes YAML manifest for the agent.

Add an environment variable to the YAML manifest. The value should be the name of your cluster. If you have multiple clusters, make sure to copy the YAML manifest, once per cluster.

2  value: stage

Deploy the agent configuration to your cluster.

Once the agents are deployed, pick one of them and view its recent telemetry. You should see the cluster name defined in the agent's environment instead of the placeholder name.

Env Recent Telemetry


Be sure to configure the Add Fields processor on the configuration that matches the agent you have deployed.

Resource Detection

BindPlane can use the Resource Detection Processor to detect the cluster name by making an API request to your cloud provider.

Currently, only Google Cloud's GKE is supported. Support for Amazon EKS and Azure AKS is coming soon.

See the Resource Detection Kubernetes section for configuration details.

Frequently Asked Questions

Q: Can I set the cluster name using a Gateway agent?

A: Yes. If you are forwarding telemetry from the Node and Cluster agents to a Gateway agent, you can configure the Add Fields or Resource Detection processor on the Gateway configuration.