# Kubernetes Cluster Name Detection

OpenTelemetry publishes semantic conventions for common resources. The OpenTelemetry Kubernetes Semantic Conventions can be found [here](https://opentelemetry.io/docs/specs/semconv/resource/k8s/#cluster).

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:

* [Cluster Events](https://app.gitbook.com/s/gmiOMzBfoNFwmKJFHMcJ/integrations/sources/kubernetes-cluster-events)
* [Cluster Metrics](https://app.gitbook.com/s/gmiOMzBfoNFwmKJFHMcJ/integrations/sources/kubernetes-cluster-metrics)
* [Container Logs](https://app.gitbook.com/s/gmiOMzBfoNFwmKJFHMcJ/integrations/sources/kubernetes-container-logs)
* [Kubelet Metrics](https://app.gitbook.com/s/gmiOMzBfoNFwmKJFHMcJ/integrations/sources/kubernetes-kubelet-metrics)

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 collector\
configuration for many clusters, see the [Environment Variable](#environment-variable) and [Resource Detection](#resource-detection) sections.

### Environment Variable

Bindplane can use the [Add Fields Processor](https://app.gitbook.com/s/gmiOMzBfoNFwmKJFHMcJ/integrations/processors/add-fields) 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).

<figure><img src="https://content.gitbook.com/content/A6BP9V0wfJj4LZdQH6OJ/blobs/RGJEGS69jSZud2dNIqO1/how-to-guides-kubernetes-kubernetes-cluster-name-detection-image-1.png" alt="Bindplane docs - Kubernetes Dynamic Cluster Name - image 1"><figcaption></figcaption></figure>

Next, use the [Add Fields Processor](https://app.gitbook.com/s/gmiOMzBfoNFwmKJFHMcJ/integrations/processors/add-fields) to upsert the resource attribute `k8s.cluster.name` with the value of the environment variable`CLUSTER_NAME`.

<figure><img src="https://content.gitbook.com/content/A6BP9V0wfJj4LZdQH6OJ/blobs/ZFVJ8tIGUuz4XSyYRicG/how-to-guides-kubernetes-kubernetes-cluster-name-detection-image-2.png" alt="Bindplane docs - Kubernetes Dynamic Cluster Name - image 2"><figcaption></figcaption></figure>

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

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.

```yaml
- name: CLUSTER_NAME
  value: stage
```

Deploy the collector configuration to your cluster.

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

<figure><img src="https://content.gitbook.com/content/A6BP9V0wfJj4LZdQH6OJ/blobs/bYsJ3YEj4E2GmvfyQMy4/how-to-guides-kubernetes-kubernetes-cluster-name-detection-image-3.png" alt="Bindplane docs - Kubernetes Dynamic Cluster Name - image 3"><figcaption></figcaption></figure>

{% hint style="info" %}
**NOTE**

Be sure to configure the Add Fields processor on the configuration that matches the collector you have deployed.
{% endhint %}

### Resource Detection

Bindplane can use the [Resource Detection Processor](https://app.gitbook.com/s/gmiOMzBfoNFwmKJFHMcJ/integrations/processors/resource-detection) 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](https://app.gitbook.com/s/gmiOMzBfoNFwmKJFHMcJ/integrations/processors/resource-detection#kubernetes) section for configuration details.

### Frequently Asked Questions

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

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


---

# 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/cloud-and-platform-integrations/kubernetes/kubernetes-cluster-name-detection.md?ask=<question>
```

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.