Labels ed Annotazioni

Le Label sono usate principalmente per identificare e raggruppare risorse da Kubernetes ed hanno un significato semantico.

Le Annotation sono per Kubernetes degli oggetti opachi e non hanno impatto sulle operazioni interne. Sono metadati non identificativi aggiunte arbitrariamente ad un oggetto.

Sono dei clients come strumenti e librerie che eventualmente raccolgono questi dati.

Sia le annotazioni che le etichette sono mappe chiave-valore.

Un'annotazione ha la struttura:

[prefisso/]mome: "valore"

Il nome:

• è un requisito
• é lungo al massimo 63 caratteri, inizia e termina con un carattere alfanumerico, può avere trattini, punti e underscores

Il prefisso:

• è opzionale
• è lungo al massimo 253 caratteri
• è un dominio DNS

Il valore

• è un requisito
• è una stringa formattata JSON

Esempio:

apiVersion: v1
kind: Pod
metadata:
  name: annotations-demo
  annotations:
    imageregistry: "http://localhost:5000/"
spec:
  containers:
  - name: nginx
    image: nginx:1.14.2
    ports:
    - containerPort: 80

Specifica da quale registry provengono le immagini. E'da notare però che l'immagine è comunque scaricata dal Docker Hub e non dal registry locale.

Le annotations sono lette da tools esterni, non dal Kubernetes corrente.

Le annotazioni sono in genere poste manualmente nel Manifest dell'oggetto creato. Però in certi casi possono essere create ed usate da tools esterni di controllo o gestione.

Per esempio lo Horizontal Pod Autoscaler (HPA) genera annotazioni.

Oltre che porre annotazioni nel Manifest di un oggetto si può annotare un oggetto già esistente col comando kubectl annotate.

Esempi:

• Update del pod 'foo' con la annotation 'description' e il valore 'my frontend'
  • kubectl annotate pods foo description='my frontend'
• Update di un pod identificato nel file "pod.json"
  • kubectl annotate -f pod.json description='my frontend'
• Riscrivere un'annotazione esistente
  • kubectl annotate --overwrite pods foo description='my frontend running nginx'
• Update di un'annotazione in tutti i pod del namespace (-A: in tutti i namespace)
  • kubectl annotate pods --all description='my frontend running nginx'
• Update del pod 'foo' solo se la risorsa non è cambiata dalla versione 1
  • kubectl annotate pods foo description='my frontend running nginx' --resource-version=1
• Rimuovere un'annotazione
  • kubectl annotate pods foo description-

Esempio. Sia dato il Manifest:

vi ~/scripts/annotations.yml

apiVersion: v1
kind: Pod
metadata:
  name: nginx-pod
  labels:
    app: dashboard
    environment: test
  annotations:
    build-info: |
      {
        "commit": "abcd123",
        "timestamp": "2023-05-01T10:00:00Z"
      }
spec:
  containers:
    - name: frontend-nginx
      image: nginx

Una volta creato l'oggetto si possono compiere delle query basate sia sulle label che sulle annotation.

kubectl get pods nginx-pod -o yaml | grep -A2 'labels:'

  labels:
    app: dashboard
    environment: test

kubectl get pods nginx-pod -o yaml | grep -A5 'annotations:'

  annotations:
    build-info: |
      {
        "commit": "abcd123",
        "timestamp": "2023-05-01T10:00:00Z"
      }

kubectl get pods --selector='app=dashboard'

NAME        READY   STATUS    RESTARTS   AGE
nginx-pod   1/1     Running   0          5m33s

kubectl get pods --selector='app in (dashboard), environment in (test)'

NAME        READY   STATUS    RESTARTS   AGE
nginx-pod   1/1     Running   0          7m36s

E in generale si può usare la meravigliosa utility jq per compiere queries su stringhe JSON:

kubectl get pods -o json | \
jq -r '.items[] | select(.metadata.annotations."build-info" | fromjson | .commit=="abcd123") | .metadata.name'

nginx-pod

Terminare l'Esercizio

kubectl delete -f ~/scripts/annotations.yml