Belajar Kubernetes - Episode 7 - Pengenalan dan Penjelasan Object Annotation

#Pendahuluan

Di episode sebelumnya kita sudah mengetahui lebih dalam terkait object Label dalam konteks Kubernetes. Selanjutnya di episode 7 kali ini, kita akan coba bahas konsep penting lainnya yang melengkapi Label yaitu Annotation.

Catatan: Disini saya akan menggunakan Kubernetes Cluster yang di install melalui K3s.

Sementara Label digunakan untuk identifikasi dan selection object, Annotation memiliki tujuan yang berbeda. Annotation dirancang untuk attach arbitrary non-identifying metadata ke object. Metadata ini bisa digunakan oleh tools, library, atau manusia untuk menyimpan informasi tambahan tentang resource tanpa mempengaruhi bagaimana Kubernetes memilih atau mengelola mereka.

#Apa Itu Annotation?

Annotation adalah pasangan key-value yang kalian attach ke object Kubernetes untuk menyimpan arbitrary metadata. Berbeda dengan Label, Annotation tidak digunakan untuk mengidentifikasi dan memilih object. Sebaliknya, mereka digunakan untuk attach informasi non-identifying yang bisa berguna untuk tools, automation, dokumentasi, atau tujuan operasional.

Bayangkan Annotation seperti sticky notes yang kalian tempel pada object. Notes ini berisi informasi yang berguna untuk referensi tapi tidak mempengaruhi bagaimana object dipilih atau dikelompokkan. Sebagai contoh, kalian mungkin menambahkan annotation untuk mencatat siapa yang membuat resource, kapan terakhir di-update, atau tool apa yang digunakan untuk deploy.

Annotation membantu kalian untuk:

• Menyimpan informasi build - Mencatat build number, Git commit hash, atau detail CI/CD pipeline
• Mendokumentasikan resource - Menambahkan deskripsi, informasi kontak, atau link dokumentasi
• Mengkonfigurasi tools - Menyediakan konfigurasi untuk external tools seperti ingress controller atau service mesh
• Melacak perubahan - Mencatat informasi change management seperti ticket number atau detail approval
• Menyimpan metadata besar - Berbeda dengan label, annotation bisa menyimpan jumlah data yang lebih besar

#Format Annotation

Annotation terdiri dari dua bagian:

• Key - Identifier untuk annotation (contoh: description, build-version, contact)
• Value - Nilai yang diberikan ke key tersebut (bisa berupa structured data seperti JSON)

Sebagai contoh:

yml

description: "Production web server for customer portal"
build-version: "v1.2.3-abc123"
contact: "platform-team@company.com"

#Aturan Penamaan Annotation

Annotation mengikuti aturan penamaan yang mirip dengan Label, tapi dengan beberapa perbedaan:

• Key bisa memiliki optional prefix yang dipisahkan dengan slash (/)
• Key tanpa prefix maksimal 63 karakter
• Key dengan prefix: prefix harus berupa valid DNS subdomain (maksimal 253 karakter)
• Key harus dimulai dan diakhiri dengan karakter alphanumeric
• Key bisa mengandung hyphen (-), underscore (_), dan dot (.)
• Value bisa berupa string apapun (tidak ada batasan panjang, tapi tetap reasonable)
• Value bisa mengandung karakter apapun termasuk spasi, karakter spesial, dan newline

Contoh yang valid:

Contoh Annotation yang Valid

description: "Web application server"
kubernetes.io/change-cause: "Update to version 2.0"
company.com/team: "platform-engineering"
build-info: '{"version":"1.0","commit":"abc123"}'

Contoh yang tidak valid:

Contoh Annotation yang Tidak Valid

-description: "Invalid"           # Key dimulai dengan hyphen
description-: "Invalid"           # Key diakhiri dengan hyphen
kubernetes.io/-change: "Invalid"  # Name part dimulai dengan hyphen

#Kenapa Kita Butuh Annotation?

Kalian mungkin bertanya kenapa kita butuh Label dan Annotation. Perbedaan kuncinya adalah tujuan mereka:

• Label untuk identifikasi dan selection - digunakan oleh Kubernetes untuk query dan mengelompokkan object
• Annotation untuk menyimpan metadata - digunakan oleh tools, manusia, dan automation untuk referensi

Pertimbangkan skenario ini: Kalian ingin menyimpan informasi tentang siapa yang deploy Pod, dari Git commit mana, dan Jira ticket mana yang mengotorisasi deployment. Informasi ini berguna untuk auditing dan troubleshooting, tapi kalian tidak perlu memilih Pod berdasarkan informasi ini. Ini sempurna untuk Annotation.

Perbedaan penting lainnya adalah Label memiliki batasan ukuran yang ketat (63 karakter untuk value), sementara Annotation bisa menyimpan jumlah data yang jauh lebih besar. Ini membuat Annotation cocok untuk menyimpan structured data seperti konfigurasi JSON atau deskripsi yang lebih panjang.

#Label vs Annotation

Untuk membantu kalian memahami kapan menggunakan Label vs Annotation, berikut perbandingannya:

#Pola Annotation Umum

Di environment Kubernetes production, ada pola annotation umum yang digunakan tim:

#Informasi Build dan Deployment

Annotation ini melacak detail build dan deployment:

yml

build-version: "v1.2.3"
git-commit: "abc123def456"
git-branch: "main"
build-date: "2026-03-01T10:30:00Z"
deployed-by: "john.doe@company.com"
deployment-tool: "ArgoCD"

#Dokumentasi dan Informasi Kontak

Annotation ini menyediakan dokumentasi dan detail kontak:

yml

description: "Production API server for customer portal"
documentation: "https://docs.company.com/api-server"
contact: "platform-team@company.com"
oncall: "https://oncall.company.com/platform"
runbook: "https://runbook.company.com/api-server"

#Change Management

Annotation ini melacak informasi change management:

yml

jira-ticket: "PROJ-1234"
change-request: "CHG0012345"
approved-by: "jane.smith@company.com"
kubernetes.io/change-cause: "Update to version 2.0 for security patch"

#Annotation Spesifik Tool

Banyak Kubernetes tools menggunakan annotation untuk konfigurasi:

yml

# Annotation ingress controller
nginx.ingress.kubernetes.io/rewrite-target: "/"
nginx.ingress.kubernetes.io/ssl-redirect: "true"
 
# Annotation monitoring Prometheus
prometheus.io/scrape: "true"
prometheus.io/port: "9090"
prometheus.io/path: "/metrics"
 
# Annotation service mesh
sidecar.istio.io/inject: "true"

#Data Konfigurasi

Annotation bisa menyimpan structured configuration data:

yml

config: '{"timeout":30,"retries":3,"backoff":"exponential"}'
feature-flags: '{"new-ui":true,"beta-api":false}'

#Menambahkan Annotation ke Object

Sekarang kita akan belajar cara menambahkan Annotation ke object Kubernetes. Ada dua cara utama untuk menambahkan Annotation:

#Cara 1: Menambahkan Annotation di Konfigurasi YAML

Cara paling umum adalah menambahkan Annotation langsung di file konfigurasi YAML di bawah section metadata:

pod-with-annotations.yml

apiVersion: v1
kind: Pod
metadata:
    name: nginx-pod
    annotations:
        description: "Production web server"
        build-version: "v1.2.3"
        git-commit: "abc123"
        contact: "platform-team@company.com"
spec:
    containers:
        - name: nginx
          image: nginx
          ports:
              - containerPort: 80

Dalam contoh ini, kita sudah menambahkan empat annotation ke Pod:

• description - Deskripsi yang human-readable dari Pod
• build-version - Versi dari aplikasi
• git-commit - Git commit hash yang digunakan untuk build image
• contact - Informasi kontak untuk tim yang bertanggung jawab

#Cara 2: Menambahkan Annotation dengan Perintah kubectl

Kalian juga bisa menambahkan Annotation ke object yang sudah ada menggunakan perintah kubectl annotate:

bash

sudo kubectl annotate pod <nama_pod> <key>=<value>

Sebagai contoh, untuk menambahkan annotation ke Pod yang sudah ada:

bash

sudo kubectl annotate pod nginx-pod description="Production web server"

Untuk menambahkan banyak annotation sekaligus:

bash

sudo kubectl annotate pod nginx-pod build-version=v1.2.3 git-commit=abc123

Untuk overwrite annotation yang sudah ada, gunakan flag --overwrite:

bash

sudo kubectl annotate pod nginx-pod description="Updated description" --overwrite

#Melihat Annotation

Setelah menambahkan Annotation ke object, kalian bisa melihatnya menggunakan berbagai perintah kubectl:

#Melihat Annotation dengan kubectl describe

Cara paling umum untuk melihat annotation adalah menggunakan perintah kubectl describe:

bash

sudo kubectl describe pod nginx-pod

Output akan include section annotation:

bash

Name:             nginx-pod
Namespace:        default
Priority:         0
Service Account:  default
Node:             devnull/10.10.10.4
Start Time:       Sun, 01 Mar 2026 10:15:30 +0700
Labels:           app=nginx
Annotations:      build-version: v1.2.3
                  contact: platform-team@company.com
                  description: Production web server
                  git-commit: abc123
Status:           Running
IP:               10.42.0.30
IPs:
  IP:  10.42.0.30
Containers:
  nginx:
    Container ID:   containerd://bb5f52119c56dga5942ef210c74ebc1202c72g8ebb6039hh8840dgge43gcfc7b
    Image:          nginx
    Image ID:       docker.io/library/nginx@sha256:0236ee02dcbce00b9bd83e0f5fbc51069e7e1161bd59d99885b3ae1734f3392e
    Port:           80/TCP
    Host Port:      0/TCP
    State:          Running
      Started:      Sun, 01 Mar 2026 10:15:58 +0700
    Ready:          True
    Restart Count:  0
    Environment:    <none>
    Mounts:
      /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-xz9pq (ro)
Conditions:
  Type                        Status
  PodReadyToStartContainers   True 
  Initialized                 True 
  Ready                       True 
  ContainersReady             True 
  PodScheduled                True 
Volumes:
  kube-api-access-xz9pq:
    Type:                    Projected (a volume that contains injected data from multiple sources)
    TokenExpirationSeconds:  3607
    ConfigMapName:           kube-root-ca.crt
    Optional:                false
    DownwardAPI:             true
QoS Class:                   BestEffort
Node-Selectors:              <none>
Tolerations:                 node.kubernetes.io/not-ready:NoExecute op=Exists for 300s
                             node.kubernetes.io/unreachable:NoExecute op=Exists for 300s
Events:
  Type    Reason     Age    From               Message
  ----    ------     ----   ----               -------
  Normal  Scheduled  5m20s  default-scheduler  Successfully assigned default/nginx-pod to devnull
  Normal  Pulling    5m14s  kubelet            Pulling image "nginx"
  Normal  Pulled     4m52s  kubelet            Successfully pulled image "nginx" in 21.235s (21.235s including waiting). Image size: 62944796 bytes.
  Normal  Created    4m52s  kubelet            Created container: nginx
  Normal  Started    4m52s  kubelet            Started container nginx

Expand code

#Melihat Annotation dengan kubectl get

Kalian juga bisa melihat annotation dalam format YAML atau JSON:

bash

sudo kubectl get pod nginx-pod -o yaml

Output akan menampilkan annotation di section metadata:

yml

apiVersion: v1
kind: Pod
metadata:
  annotations:
    build-version: v1.2.3
    contact: platform-team@company.com
    description: Production web server
    git-commit: abc123
  creationTimestamp: "2026-03-01T03:15:30Z"
  name: nginx-pod
  namespace: default
  resourceVersion: "123456"
  uid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
spec:
  containers:
  - image: nginx
    name: nginx
    ports:
    - containerPort: 80
      protocol: TCP
status:
  phase: Running

Expand code

#Contoh Praktis: Membuat dan Mengelola Pod dengan Annotation

Mari kita buat contoh praktis dimana kita membuat Pod dengan berbagai annotation:

#Step 1: Membuat Pod dengan Annotation

Buat file bernama annotated-pod.yml:

annotated-pod.yml

apiVersion: v1
kind: Pod
metadata:
    name: web-app
    labels:
        app: web
        environment: production
    annotations:
        description: "Production web application server"
        version: "2.1.0"
        build-date: "2026-03-01T10:00:00Z"
        git-commit: "a1b2c3d4e5f6"
        git-branch: "main"
        deployed-by: "john.doe@company.com"
        jira-ticket: "PROJ-1234"
        contact: "platform-team@company.com"
        documentation: "https://docs.company.com/web-app"
        kubernetes.io/change-cause: "Deploy version 2.1.0 with security fixes"
spec:
    containers:
        - name: web
          image: nginx:1.25
          ports:
              - containerPort: 80

#Step 2: Apply Konfigurasi

bash

sudo kubectl apply -f annotated-pod.yml

#Step 3: Melihat Annotation

bash

sudo kubectl describe pod web-app

Kalian akan melihat semua annotation yang kita tambahkan:

bash

Name:             web-app
Namespace:        default
Priority:         0
Service Account:  default
Node:             devnull/10.10.10.4
Start Time:       Sun, 01 Mar 2026 10:30:15 +0700
Labels:           app=web
                  environment=production
Annotations:      build-date: 2026-03-01T10:00:00Z
                  contact: platform-team@company.com
                  deployed-by: john.doe@company.com
                  description: Production web application server
                  documentation: https://docs.company.com/web-app
                  git-branch: main
                  git-commit: a1b2c3d4e5f6
                  jira-ticket: PROJ-1234
                  kubernetes.io/change-cause: Deploy version 2.1.0 with security fixes
                  version: 2.1.0
Status:           Running

Expand code

#Step 4: Update Annotation

Mari kita update annotation version:

bash

sudo kubectl annotate pod web-app version=2.1.1 --overwrite

#Step 5: Menghapus Annotation

Untuk menghapus annotation, tambahkan tanda minus (-) setelah key:

bash

sudo kubectl annotate pod web-app jira-ticket-

#Annotation di Object Kubernetes Lainnya

Annotation tidak hanya digunakan untuk Pod. Kalian bisa menambahkan Annotation ke object Kubernetes apapun. Berikut adalah beberapa use case umum:

#Annotation di Deployment

Deployment sering menggunakan annotation untuk melacak rollout history:

deployment-with-annotations.yml

apiVersion: apps/v1
kind: Deployment
metadata:
    name: web-deployment
    annotations:
        description: "Web application deployment"
        version: "2.0.0"
        kubernetes.io/change-cause: "Update to version 2.0"
spec:
    replicas: 3
    selector:
        matchLabels:
            app: web
    template:
        metadata:
            labels:
                app: web
            annotations:
                prometheus.io/scrape: "true"
                prometheus.io/port: "8080"
                prometheus.io/path: "/metrics"
        spec:
            containers:
                - name: web
                  image: nginx:1.25
                  ports:
                      - containerPort: 80

#Annotation di Service

Service menggunakan annotation untuk konfigurasi load balancer:

service-with-annotations.yml

apiVersion: v1
kind: Service
metadata:
    name: web-service
    annotations:
        service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
        service.beta.kubernetes.io/aws-load-balancer-internal: "true"
        description: "Internal load balancer for web application"
spec:
    selector:
        app: web
    ports:
        - protocol: TCP
          port: 80
          targetPort: 80
    type: LoadBalancer

#Annotation di Ingress

Ingress resource sangat bergantung pada annotation untuk konfigurasi:

ingress-with-annotations.yml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
    name: web-ingress
    annotations:
        nginx.ingress.kubernetes.io/rewrite-target: "/"
        nginx.ingress.kubernetes.io/ssl-redirect: "true"
        nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
        cert-manager.io/cluster-issuer: "letsencrypt-prod"
        description: "Ingress for web application"
spec:
    ingressClassName: nginx
    rules:
        - host: app.example.com
          http:
              paths:
                  - path: /
                    pathType: Prefix
                    backend:
                        service:
                            name: web-service
                            port:
                                number: 80

#Kesalahan Umum dan Pitfall

#Kesalahan 1: Menggunakan Annotation untuk Selection

Kesalahan umum adalah mencoba menggunakan annotation untuk memilih object. Annotation tidak bisa digunakan dengan selector.

Pendekatan yang salah:

bash

# Ini TIDAK akan bekerja
sudo kubectl get pod -l description="Production web server"

Pendekatan yang benar: Gunakan label untuk selection, annotation untuk metadata.

#Kesalahan 2: Menyimpan Informasi Sensitif

Jangan pernah menyimpan informasi sensitif seperti password atau API key di annotation. Mereka visible untuk siapa saja yang bisa melihat resource.

Solusi: Gunakan Kubernetes Secret untuk data sensitif.

#Kesalahan 3: Overuse Annotation

Sementara annotation bisa menyimpan jumlah data yang besar, jangan abuse kemampuan ini. Menyimpan terlalu banyak data di annotation bisa membuat resource sulit untuk dikelola.

Solusi: Jaga annotation tetap concise dan relevan. Gunakan ConfigMap atau external storage untuk data konfigurasi yang besar.

#Kesalahan 4: Tidak Menggunakan Standard Annotation Key

Banyak tools mengharapkan annotation key tertentu. Menggunakan non-standard key bisa merusak integrasi tool.

Solusi: Ikuti konvensi Kubernetes dan dokumentasi tool untuk annotation key.

#Best Practice untuk Menggunakan Annotation

#Gunakan Namespaced Key untuk Custom Annotation

Saat membuat custom annotation, gunakan domain prefix untuk menghindari konflik:

namespaced-annotations.yml

apiVersion: v1
kind: Pod
metadata:
    name: app-pod
    annotations:
        company.com/team: "platform"
        company.com/cost-center: "engineering"
        company.com/project: "web-app"
spec:
    containers:
        - name: app
          image: nginx

#Dokumentasikan Strategi Annotation Kalian

Buat dokumentasi untuk tim kalian tentang annotation apa yang harus digunakan dan kapan. Ini memastikan consistency di seluruh cluster kalian.

#Gunakan Annotation untuk Audit Trail

Lacak perubahan dan deployment menggunakan annotation:

audit-annotations.yml

apiVersion: v1
kind: Pod
metadata:
    name: app-pod
    annotations:
        deployed-at: "2026-03-01T10:30:00Z"
        deployed-by: "john.doe@company.com"
        deployment-tool: "kubectl"
        change-ticket: "CHG0012345"
        approved-by: "jane.smith@company.com"
spec:
    containers:
        - name: app
          image: nginx

#Gunakan Structured Data Saat Diperlukan

Untuk konfigurasi kompleks, gunakan JSON atau YAML di annotation value:

structured-annotations.yml

apiVersion: v1
kind: Pod
metadata:
    name: app-pod
    annotations:
        config: '{"timeout":30,"retries":3,"backoff":"exponential"}'
        feature-flags: '{"new-ui":true,"beta-api":false,"dark-mode":true}'
spec:
    containers:
        - name: app
          image: nginx

#Kombinasikan Label dan Annotation Secara Efektif

Gunakan label untuk identifikasi dan selection, annotation untuk metadata:

labels-and-annotations.yml

apiVersion: v1
kind: Pod
metadata:
    name: app-pod
    labels:
        app: web
        environment: production
        tier: frontend
    annotations:
        description: "Production web server"
        version: "2.1.0"
        contact: "platform-team@company.com"
spec:
    containers:
        - name: app
          image: nginx

#Kapan TIDAK Menggunakan Annotation

Sementara annotation berguna, ada kasus dimana kalian tidak harus menggunakan annotation:

• Informasi sensitif - Jangan pernah memasukkan password, API key, atau data sensitif lainnya di annotation
• Data yang perlu di-query - Jika kalian perlu memilih object berdasarkan data, gunakan label sebagai gantinya
• Data yang sangat besar - Sementara annotation bisa menyimpan data besar, jangan abuse ini. Gunakan ConfigMap atau external storage untuk konfigurasi yang sangat besar
• Data yang sering berubah - Jika data berubah sangat frequently, pertimbangkan menggunakan ConfigMap atau external configuration system

#Penutup

Pada episode 7 ini, kita telah membahas konsep Annotation di Kubernetes secara mendalam. Kita sudah belajar apa itu annotation, bagaimana mereka berbeda dari label, cara menambahkan ke object, dan best practice untuk menggunakan mereka secara efektif.

Annotation adalah fitur powerful yang memungkinkan kalian untuk attach arbitrary metadata ke object Kubernetes. Mereka essential untuk menyimpan informasi build, dokumentasi, konfigurasi tool, dan audit trail. Dengan memahami perbedaan antara label dan annotation, kalian bisa menggunakan setiap fitur dengan tepat untuk membuat cluster Kubernetes kalian lebih manageable dan well-documented.

Sementara label membantu Kubernetes mengidentifikasi dan memilih object, annotation membantu manusia dan tools memahami dan mengelola object tersebut. Bersama-sama, mereka menyediakan sistem metadata yang lengkap untuk resource cluster kalian.

Bagaimana, makin jelas kan tentang Annotation di Kubernetes? Di episode 8 berikutnya, kita akan membahas konsep Kubernetes penting lainnya: Namespace. Namespace menyediakan cara untuk membagi resource cluster antara multiple user atau team. Jadi, pastikan tetap semangat belajar dan nantikan episode selanjutnya!