Updated on 2025-09-05 GMT+08:00

Configuring Labels and Annotations

To support multi-dimensional metadata management, Kubernetes offers labels and annotations. They both attach metadata to resources in the format of key-value pairs, but their purposes and use cases differ significantly.

  • Labels are used for identifying and classifying Kubernetes objects. They follow a structured key-value format (for example, app=frontend) and can be used to efficiently select resources using selectors. They directly influence resource scheduling and management. The key and value of a label must comply with naming rules and typically represent persistent attributes of a resource, such as version.
  • Annotations serve to extend functionality and store additional metadata. They support flexible data formats (such as JSON or multi-line text). They are not used to select resources and do not influence scheduling.

Both labels and annotations apply to various Kubernetes resource types. This section will specifically examine their use in pods.

Pod Labels

Pod labels enable intelligent resource association. Once labels are added to pods, other Kubernetes resources can accurately identify and be associated with these pods using label selectors. Label keys and values must follow specific naming rules. For details, see Syntax and character set. For example, you can add the following label to two workloads (App 1 and App 2), respectively:

  • App 1: release=alpha
  • App 2: release=beta

When App 3 is created with a workload affinity of release=alpha, Kubernetes will attempt to schedule App 3 onto the same node as App 1 or another node that matches this affinity. This enables intelligent collaborative deployment between App 1 and App 3. For details, see Configuring Workload Affinity or Anti-affinity Scheduling (podAffinity or podAntiAffinity).

You can add labels to a pod using either the console or YAML.

When creating or upgrading a workload on the CCE console, you can add a pod label by clicking Labels and Annotations in the Advanced Settings area. This label helps identify the pod within the cluster. During the workload creation, CCE will add the label shown in the figure below to the workload pod by default. The value of app is the workload name.

When creating or upgrading a workload, you can add a pod label in the following area of the YAML file:

...
spec:
  selector:
    matchLabels:
      app: nginx
      version: v1
  template:
    metadata:
      labels:
        app: nginx
        version: v1
    spec:
      ...

Pod Annotations

CCE provides some advanced functions for pods. These functions can be implemented by adding annotations to the YAML files. You can add annotations to a pod using either the console or YAML.

When creating or upgrading a workload on the CCE console, you can add a pod annotation by clicking Labels and Annotations in the Advanced Settings area to enable advanced functions for the pod.

For example, to disable the collection of container standard output logs for a pod, set the pod annotation to kubernetes.AOM.log.stdout='[]' and click Confirm.

When creating or upgrading a workload using YAML, you can use the annotations parameter to enable advanced pod functions.

For example, you can use annotations to disable the collection of container standard output logs for a pod:

...
spec:
  replicas: 1     # Number of pods
  selector:
    matchLabels:  # Selector for selecting resources with specific labels
      app: nginx  
  template:
    metadata:
      labels:     # Labels
        app: nginx
      annotations:
        kubernetes.AOM.log.stdout: '[]'
...

Typical Pod Annotations

Table 1 provides some typically used annotations. You can add annotations for pods as required.

Table 1 Pod annotations

Annotation

Description

Default Value

kubernetes.AOM.log.stdout

The standard output log collection setting for containers. If left unspecified, the standard output logs from all containers will be automatically reported to AOM by default. You can customize this annotation to collect standard output logs only from specified containers or disable standard output log collection for all containers.

Example:

  • Disabling standard output log collection for all containers:
    kubernetes.AOM.log.stdout: '[]'
  • Collecting standard output logs from container-1 and container-2:
    kubernetes.AOM.log.stdout: '["container-1","container-2"]'

N/A

metrics.alpha.kubernetes.io/custom-endpoints

The AOM metric reporting setting, which allows specified metrics to be sent to AOM.

For details, see Monitoring Custom Metrics on AOM.

N/A

prometheus.io/scrape

The Prometheus metric reporting setting, which allows specified metrics to be sent to Prometheus. If set to true, the metrics of the specified workload will be reported to Prometheus.

For details, see Monitoring Custom Metrics Using Cloud Native Cluster Monitoring.

N/A

prometheus.io/path

URL for Prometheus to collect data.

For details, see Monitoring Custom Metrics Using Cloud Native Cluster Monitoring.

/metrics

prometheus.io/port

Endpoint port number for Prometheus to collect data.

For details, see Monitoring Custom Metrics Using Cloud Native Cluster Monitoring.

N/A

prometheus.io/scheme

Protocol used by Prometheus to collect data. The value can be http or https.

For details, see Monitoring Custom Metrics Using Cloud Native Cluster Monitoring.

N/A

kubernetes.io/ingress-bandwidth

The ingress bandwidth of a pod. It controls the rate at which the pod receives data to ensure that the pod can process external requests.

For details, see Configuring QoS for a Pod.

N/A

kubernetes.io/egress-bandwidth

The egress bandwidth of a pod. It controls the rate at which the pod sends data to external systems. This affects the efficiency of communication between the pod and external services or users.

For details, see Configuring QoS for a Pod.

N/A

Helpful Links