> ## Documentation Index
> Fetch the complete documentation index at: https://docs.expanse.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes annotations and labels

> Configure Pod, Service and Ingress metadata for certificate injection, DNS registration and your cluster's policies.

Add annotations and labels to the values file for each Expanse Helm chart. Use the
keys recognised by your certificate injector, DNS controller or admission policy.
Merge the examples into your existing values for the matching chart, keeping its
component enablement and other installation settings.

The coverage below is available from these chart versions:

| Chart | Version |
| - | - |
| `expanse-daemon` | `1.2.0` |
| `expanse` | `1.2.0` |
| `expanse-postgres` | `1.2.0` |
| `expanse-clickhouse` | `1.3.0` |

## Choose the component

Metadata settings apply to the named component. A setting on one component does
not apply to the other workloads in the chart. Configure each component that
needs the policy, including optional Jobs and backup workloads.

Every map accepts string values. Quote values such as `"true"` and `"007"`.
New maps default to empty. Chart-owned identity labels and generated rollout
annotations take precedence on collisions. Customer labels never change
workload or Service selectors.

When upgrading from the previous chart version with `helm upgrade --reuse-values`,
missing Service metadata maps are treated as empty. You can add annotations and
labels during the upgrade without resetting your existing values.

The keys under `injector.example.com`, `dns.example.com` and
`customer.example.com` below are placeholders. Replace them with your cluster's
keys before installing. These settings attach metadata; your cluster's
controllers determine what happens when those keys are present.

## expanse-daemon

| Resource | Annotations | Labels |
| - | - | - |
| Observer Pod | `podAnnotations` | `podLabels` |
| Node sampler Pods | `nodeSampler.podAnnotations` | `nodeSampler.podLabels` |
| Registry refresher Pod | `registryPull.podAnnotations` | `registryPull.podLabels` |
| Adapter and history-import Pods | `integration.podAnnotations` | `integration.podLabels` |
| Agent injection webhook Service | `agentInjection.service.annotations` | `agentInjection.service.labels` |

For example, set an injector annotation on the adapter and history-import Pods,
and a DNS annotation on the webhook Service:

```yaml theme={"dark"}
integration:
  podAnnotations:
    injector.example.com/inject-ca: "true"
  podLabels:
    customer.example.com/team: "platform"
agentInjection:
  service:
    annotations:
      dns.example.com/register: "true"
    labels:
      customer.example.com/team: "platform"
```

The history Job receives the integration metadata even in a history-only install
with `integration.enabled: false`.

### Changing metadata after a history import

A connected `helm upgrade` preserves the existing history Job's Pod metadata
while applying changed metadata to the adapter. Changing metadata alone never
starts another history import.

To run the import with new metadata, set a new `integration.history.attempt`
value and keep the import ID. This creates a new Job and runs the import again.

Offline renderers, including Argo CD, cannot look up the existing Job. Change
`integration.history.attempt` alongside metadata before syncing an existing
history Job. Keeping the attempt unchanged would try to update an immutable
Job Pod template.

## expanse

In the table, `<component>` means `controlplane`, `dataplane`, `intelligence`,
`console`, `prediction` or `rightsizer`.

| Resource | Annotations | Labels |
| - | - | - |
| Component Pods | `<component>.podAnnotations` | `<component>.podLabels` |
| Component Services | `<component>.service.annotations` | `<component>.service.labels` |
| Metric consumer Pod | `dataplane.metricsQueue.consumer.podAnnotations` | `dataplane.metricsQueue.consumer.podLabels` |
| Walker extraction Pod | `intelligence.walkerExtract.podAnnotations` | `intelligence.walkerExtract.podLabels` |
| Walker extraction Service | `intelligence.walkerExtract.service.annotations` | `intelligence.walkerExtract.service.labels` |
| Walker profiler Job, including canaries | `walkerProfiler.podAnnotations` | `walkerProfiler.podLabels` |
| Ingress | `ingress.annotations` | `ingress.labels` |

For example, configure the data-plane Pod and its Service separately:

```yaml theme={"dark"}
dataplane:
  podAnnotations:
    injector.example.com/inject-ca: "true"
  podLabels:
    customer.example.com/team: "platform"
  service:
    annotations:
      dns.example.com/register: "true"
    labels:
      customer.example.com/team: "platform"
```

Changing only an existing walker profiler Job's Pod metadata requires recreating
that Job before upgrading.

## expanse-postgres

| Resource | Annotations | Labels |
| - | - | - |
| PostgreSQL server Pod | `podAnnotations` | `podLabels` |
| Backup Pods | `backup.podAnnotations` | `backup.podLabels` |
| Secret-generator Pod | `secretGenerator.podAnnotations` | `secretGenerator.podLabels` |
| Client Service | `service.annotations` | `service.labels` |
| Headless Service | `headlessService.annotations` | `headlessService.labels` |

For example, annotate backup Pods and the client Service:

```yaml theme={"dark"}
backup:
  podAnnotations:
    injector.example.com/inject-ca: "true"
  podLabels:
    customer.example.com/team: "platform"
service:
  annotations:
    dns.example.com/register: "true"
  labels:
    customer.example.com/team: "platform"
```

The client Service settings and headless Service settings are independent.

## expanse-clickhouse

| Resource | Annotations | Labels |
| - | - | - |
| ClickHouse resources managed by the operator | `clickhouse.annotations` | `clickhouse.labels` |
| Keeper resources managed by the operator | `keeper.annotations` | `keeper.labels` |
| Schema Job Pod | `schemaJob.podAnnotations` | `schemaJob.podLabels` |
| CRD preflight Job Pod | `crdPreflight.podAnnotations` | `crdPreflight.podLabels` |
| Backup Pods | `backup.podAnnotations` | `backup.podLabels` |
| Client Service | `clickhouse.service.annotations` | `clickhouse.service.labels` |
| Internal client Service | `clickhouse.internalService.annotations` | `clickhouse.internalService.labels` |
| Operator Pod | `operator.manager.pod.annotations` | `operator.manager.pod.labels` |
| Operator metrics Service | `operator.metrics.service.annotations` | `operator.metrics.service.labels` |
| Operator webhook Service | `operator.webhook.service.annotations` | `operator.webhook.service.labels` |

The ClickHouse and Keeper maps apply to their Pods, headless Services and other
operator-managed resources, including PersistentVolumeClaims. ClickHouse metadata
also applies to its version-probe Job. Choose keys suitable for all those resource
kinds; these maps are shared across them.

For example, apply a policy annotation to both clusters and register the client
Service with your DNS controller:

```yaml theme={"dark"}
clickhouse:
  annotations:
    injector.example.com/inject-ca: "true"
  labels:
    customer.example.com/team: "platform"
  service:
    annotations:
      dns.example.com/register: "true"
keeper:
  annotations:
    injector.example.com/inject-ca: "true"
  labels:
    customer.example.com/team: "platform"
```

Keep the operator Pod's existing `clickhouse.com/role: operator` label when
customising `operator.manager.pod.labels`. NetworkPolicies use that label.

## Check the deployed metadata

Render your values with `helm template` before installing. For ClickHouse and
Keeper, the render contains cluster resources; the operator creates their Pods
and headless Services after installation.

Inspect the actual Pods and Services, including optional workloads, to confirm
the annotations and labels are present:

```bash theme={"dark"}
kubectl -n <namespace> get pod <pod-name> -o yaml
kubectl -n <namespace> get service <service-name> -o yaml
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.