> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-4-1/cybus-helm-charts/working-with-cybus-helm-charts/adding-labels-and-annotations.md). # Adding Labels and Annotations [Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) and [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) let you attach metadata to Kubernetes objects managed by the Connectware Helm charts. Use labels to select and organize resources. Use annotations to carry non-identifying metadata for external tooling such as monitoring systems, cost management platforms, and policy engines. ## When to Use Labels and Annotations Use labels and annotations when you need to: * Apply organizational tagging policies, such as team ownership, environment, or cost center, across Connectware resources. * Integrate with external tools that select resources by label, such as Prometheus, Datadog, or Kubernetes network policies. * Add annotations required by cloud provider load balancers or ingress controllers on Service resources. ## Configuration Values The following Helm values control labels and annotations for each chart. {% tabs %} {% tab title="connectware Helm Chart Values" %} | Value | Description | | --------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `global.commonLabels` | Labels applied to all Kubernetes resources created by this Helm chart. | | `${COMPONENT_NAME}.labels` | Labels applied to the component's resources such as Deployment, StatefulSet, Pods, and Services. | | `${COMPONENT_NAME}.annotations` | Annotations applied to the component's resources such as Deployment, StatefulSet, Pods, and Services. | | `${COMPONENT_NAME}.podLabels` | Labels applied to the component's Pods only. | | `${COMPONENT_NAME}.podAnnotations` | Annotations applied to the component's Pods only. | | `${COMPONENT_NAME}.service.labels` | Labels applied to the component's Service only. | | `${COMPONENT_NAME}.service.annotations` | Annotations applied to the component's Service only. | | {% endtab %} | | {% tab title="connectware-agent Helm Chart Values" %} | Value | Description | | ------------------------------------------------- | -------------------------------------------------------------------- | | `protocolMapperAgentDefaults.labels` | Labels applied to all Kubernetes resources of all agents. | | `protocolMapperAgentDefaults.annotations` | Annotations applied to all Kubernetes resources of all agents. | | `protocolMapperAgentDefaults.podLabels` | Labels applied to all agent Pods only. | | `protocolMapperAgentDefaults.podAnnotations` | Annotations applied to all agent Pods only. | | `protocolMapperAgentDefaults.service.labels` | Labels applied to all agent Services only. | | `protocolMapperAgentDefaults.service.annotations` | Annotations applied to all agent Services only. | | `protocolMapperAgents[*].labels` | Labels applied to all Kubernetes resources of a specific agent. | | `protocolMapperAgents[*].annotations` | Annotations applied to all Kubernetes resources of a specific agent. | | `protocolMapperAgents[*].podLabels` | Labels applied to a specific agent's Pods only. | | `protocolMapperAgents[*].podAnnotations` | Annotations applied to a specific agent's Pods only. | | `protocolMapperAgents[*].service.labels` | Labels applied to a specific agent's Service only. | | `protocolMapperAgents[*].service.annotations` | Annotations applied to a specific agent's Service only. | | {% endtab %} | | | {% endtabs %} | | {% hint style="info" %} ## How values are merged Labels and annotations are merged, not overridden. If you supply both `global.commonLabels` and `${COMPONENT_NAME}.labels`, the resulting labels and annotations on the Kubernetes object are the union of both sets. {% endhint %} ## Configuring Labels and Annotations The following tabs show how to configure labels and annotations. Pick the tab that matches your deployment. {% tabs %} {% tab title="connectware Helm Chart" %} ## Applying Labels to All Connectware Resources To apply labels to every Kubernetes resource managed by the `connectware` Helm chart, use `global.commonLabels`. **Example: Applying common labels to all resources** {% code title="values.yaml" lineNumbers="true" %} ```yaml global: commonLabels: team: platform environment: production ``` {% endcode %} All Deployments, StatefulSets, Pods, Services, ConfigMaps, Secrets, and other objects created by the Helm chart receive these labels. ## Configuring Labels and Annotations Per Component Individual components can be given labels and annotations independently by setting the values under their own configuration section. Use `podLabels`, `podAnnotations`, `service.labels`, and `service.annotations` to target a specific resource type within a component. All Connectware components support these values. **Example: Adding labels and annotations to a specific component** {% code title="values.yaml" lineNumbers="true" %} ```yaml # Note: 'broker' is used as an example, but this configuration # is applicable to any Connectware component. broker: labels: team: platform annotations: cost-center: '12345' podLabels: broker-pod-label: broker-pod-value service: labels: broker-service-label: broker-service-value ``` {% endcode %} In this example, the `broker` StatefulSet, its Pods, and its Services all receive the `team: platform` label and the `cost-center` annotation. The `broker-pod-label` label is added to Pods only, and the `broker-service-label` label is added to the Service only. ## Combining Global Common Labels with Per-Component Values You can use `global.commonLabels` and component-level values together. Both sets of labels and annotations are added to the relevant Kubernetes objects — neither overrides the other. **Example: Global common labels combined with per-component labels and annotations** {% code title="values.yaml" lineNumbers="true" %} ```yaml global: commonLabels: team: platform environment: production # Add a component-specific label and pod label to the broker in addition # to the global common labels. broker: labels: additional-label: additional-value podLabels: broker-pod-label: broker-pod-value service: labels: broker-service-label: broker-service-value ``` {% endcode %} {% endtab %} {% tab title="connectware-agent Helm Chart (Standalone)" %} Use this tab if you deploy the `connectware-agent` Helm chart on its own. If you deploy it as a subchart of the `connectware` Helm chart, see the **connectware-agent Helm Chart (As Subchart)** tab instead. ## Configuring Default Labels and Annotations for All Agents To apply labels and annotations to all agent resources at once, set the values under `protocolMapperAgentDefaults`. **Example: Shared defaults for all agents** {% code title="values.yaml" lineNumbers="true" %} ```yaml protocolMapperAgentDefaults: labels: team: shopfloor annotations: cost-center: '12345' podLabels: pod-label: pod-value podAnnotations: pod-annotation: pod-annotation-value service: labels: service-label: service-value annotations: service-annotation: service-annotation-value protocolMapperAgents: - name: my-agent-1 - name: my-agent-2 ``` {% endcode %} ## Configuring Labels and Annotations Per Agent Individual agents can be given labels and annotations in addition to the defaults by setting the values under their own entry in `protocolMapperAgents[]`. Per-agent values are merged with the defaults: both are applied to the Kubernetes objects. **Example: Adding a per-agent label in addition to shared defaults** {% code title="values.yaml" lineNumbers="true" %} ```yaml protocolMapperAgentDefaults: labels: team: shopfloor annotations: cost-center: '12345' protocolMapperAgents: - name: bending-unit labels: line: bending - name: welding-unit labels: line: welding ``` {% endcode %} In this example, all agents receive the `team: shopfloor` label and the `cost-center` annotation. The `bending-unit` agent additionally receives `line: bending`, and `welding-unit` receives `line: welding`. {% endtab %} {% tab title="connectware-agent Helm Chart (As Subchart)" %} Use this tab if you deploy the `connectware-agent` Helm chart as a subchart of the `connectware` Helm chart. If you deploy it on its own, see the **connectware-agent Helm Chart (Standalone)** tab instead. When deployed as a subchart, all `connectware-agent` values must be nested under the `connectwareAgent` section. Agents also inherit `global.commonLabels` from the parent chart. ## Configuring Default Labels and Annotations for All Agents **Example: Deploying agents as part of the connectware Helm chart with shared labels** {% code title="values.yaml" lineNumbers="true" %} ```yaml global: commonLabels: environment: production connectwareAgent: protocolMapperAgentDefaults: labels: team: shopfloor annotations: cost-center: '12345' protocolMapperAgents: - name: my-agent-1 - name: my-agent-2 ``` {% endcode %} In this example, all agents receive the `environment: production` label from `global.commonLabels`. Additionally, all agents receive the `team: shopfloor` label and `cost-center: 12345` annotation from `protocolMapperAgentDefaults`. ## Configuring Labels and Annotations Per Agent You can combine agent-level defaults with per-agent label overrides. Set shared values under `protocolMapperAgentDefaults`, then add agent-specific values in each `protocolMapperAgents[]` entry. **Example: Shared defaults with per-agent label overrides** {% code title="values.yaml" lineNumbers="true" %} ```yaml global: commonLabels: environment: production connectwareAgent: protocolMapperAgentDefaults: labels: team: shopfloor annotations: cost-center: '12345' protocolMapperAgents: - name: bending-robots labels: line: bending - name: welding-robots labels: line: welding ``` {% endcode %} In this example, all agents receive the `environment: production` label from `global.commonLabels`. Additionally, all agents receive the `team: shopfloor` label and `cost-center: 12345` annotation from `protocolMapperAgentDefaults`. The `bending-robots` agent additionally receives `line: bending`, and `welding-robots` receives `line: welding`. {% endtab %} {% endtabs %} ## Applying Configuration Changes After editing your `values.yaml` file, apply the changes by running the `helm upgrade` command. For details, see [Applying Helm Configuration Changes](/2-4-1/cybus-helm-charts/working-with-cybus-helm-charts.md#applying-helm-configuration-changes). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.cybus.io/2-4-1/cybus-helm-charts/working-with-cybus-helm-charts/adding-labels-and-annotations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.