Kubernetes Label & Annotation

레이블

오브젝트에 첨부된 키:값 쌍

• 노드, 파드, 레플리카셋, 디플로이먼트, 서비스 등 모든 리소스에 할당 가능
• 리소스의 특성을 분류하고, 셀렉터를 이용하하여 선택 가능
  • 키:값 형태

파드레이블 예제

kubectl run 통해 pod 생성

[root@master ~/kube/10/label]# kubectl run testpod --image=nginx:1.14 --port=80
pod/testpod created
[root@master ~/kube/10/label]# kubectl get pod
NAME      READY   STATUS    RESTARTS   AGE
testpod   1/1     Running   0          5s
[root@master ~/kube/10/label]# kubectl get pod --show-labels
NAME      READY   STATUS    RESTARTS   AGE   LABELS
testpod   1/1     Running   0          82s   run=testpod

▶ 자동으로 pod label이 run:{pod명} 으로 생성됨

yaml 파일 통해 label 없이 pod 생성

[root@master ~/kube/10/label]# vi nolabel-pod.yaml
[root@master ~/kube/10/label]# cat nolabel-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: nolabel-pod
spec:
  containers:
  - name: nginx-container
    image: nginx:1.14
    ports:
    - containerPort: 80

[root@master ~/kube/10/label]# kubectl apply -f nolabel-pod.yaml
pod/nolabel-pod created
[root@master ~/kube/10/label]# kubectl get pod
NAME          READY   STATUS    RESTARTS   AGE
nolabel-pod   1/1     Running   0          2s
testpod       1/1     Running   0          2m51s
[root@master ~/kube/10/label]# kubectl get pod --show-labels
NAME          READY   STATUS    RESTARTS   AGE     LABELS
nolabel-pod   1/1     Running   0          10s     <none>
testpod       1/1     Running   0          2m59s   run=testpod

▶ label 지정하지 않으면, label 없는 상태(<none>)로 생성됨

yaml 파일 통해 label 지정 pod 생성

[root@master ~/kube/10/label]# vi label-pod.yaml
[root@master ~/kube/10/label]# cat label-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: label-pod
  labels:
    name: mainui
    rel: stable
spec:
  containers:
  - name: nginx-container
    image: nginx:1.14
    ports:
    - containerPort: 80

[root@master ~/kube/10/label]# kubectl apply -f label-pod.yaml
pod/label-pod created
[root@master ~/kube/10/label]# kubectl get pod --show-labels
NAME          READY   STATUS    RESTARTS   AGE     LABELS
label-pod     1/1     Running   0          7s      name=mainui,rel=stable
nolabel-pod   1/1     Running   0          3m20s   <none>
testpod       1/1     Running   0          6m9s    run=testpod

▶ 지정한 label 생성됨

특정 label pod 검색

[root@master ~/kube/10/label]# kubectl get pod -l name=mainui --show-labels
NAME        READY   STATUS    RESTARTS   AGE    LABELS
label-pod   1/1     Running   0          119s   name=mainui,rel=stable
[root@master ~/kube/10/label]# kubectl get pod -l run=testpod --show-labels
NAME      READY   STATUS    RESTARTS   AGE     LABELS
testpod   1/1     Running   0          8m40s   run=testpod

label 추가

[root@master ~/kube/10/label]# kubectl label pods nolabel-pod name=product rel=beta
pod/nolabel-pod labeled
[root@master ~/kube/10/label]# kubectl get pod --show-labels
NAME          READY   STATUS    RESTARTS   AGE     LABELS
label-pod     1/1     Running   0          3m36s   name=mainui,rel=stable
nolabel-pod   1/1     Running   0          6m49s   name=product,rel=beta
testpod       1/1     Running   0          9m38s   run=testpod

기존에 존재하는 label key에 대해 수정

※ key 값은 고유해야 함 → --overwrite 필요

[root@master ~/kube/10/label]# kubectl label pods nolabel-pod name=order --overwrite
pod/nolabel-pod labeled
[root@master ~/kube/10/label]# kubectl get pod --show-labels
NAME          READY   STATUS    RESTARTS   AGE     LABELS
label-pod     1/1     Running   0          5m      name=mainui,rel=stable
nolabel-pod   1/1     Running   0          8m13s   name=order,rel=beta
testpod       1/1     Running   0          11m     run=testpod

label 삭제

[root@master ~/kube/10/label]# kubectl get pod --show-labels
NAME          READY   STATUS    RESTARTS   AGE     LABELS
label-pod     1/1     Running   0          8m44s   name=mainui,rel=stable
nolabel-pod   1/1     Running   0          11m     name=order,rel=beta
testpod       1/1     Running   0          14m     run=testpod
[root@master ~/kube/10/label]# kubectl label pod testpod run-
pod/testpod unlabeled
[root@master ~/kube/10/label]# kubectl get pod --show-labels
NAME          READY   STATUS    RESTARTS   AGE     LABELS
label-pod     1/1     Running   0          8m57s   name=mainui,rel=stable
nolabel-pod   1/1     Running   0          12m     name=order,rel=beta
testpod       1/1     Running   0          14m     <none>

노드레이블 예제

[root@master ~/kube/10/nodelabel]# kubectl get node --show-labels
NAME     STATUS   ROLES           AGE    VERSION   LABELS
master   Ready    control-plane   7d2h   v1.27.7   beta.kubernetes.io/arch=amd64,beta.kubernetes.io/os=linux,kubernetes.io/arch=amd64,kubernetes.io/hostname=master,kubernetes.io/os=linux,node-role.kubernetes.io/control-plane=,node.kubernetes.io/exclude-from-external-load-balancers=
node1    Ready    <none>          7d2h   v1.27.7   beta.kubernetes.io/arch=amd64,beta.kubernetes.io/os=linux,kubernetes.io/arch=amd64,kubernetes.io/hostname=node1,kubernetes.io/os=linux
node2    Ready    <none>          7d2h   v1.27.7   beta.kubernetes.io/arch=amd64,beta.kubernetes.io/os=linux,kubernetes.io/arch=amd64,kubernetes.io/hostname=node2,kubernetes.io/os=linux
node3    Ready    <none>          7d2h   v1.27.7   beta.kubernetes.io/arch=amd64,beta.kubernetes.io/os=linux,kubernetes.io/arch=amd64,kubernetes.io/hostname=node3,kubernetes.io/os=linux

▶ 따로 추가하지 않아도 기본적으로 갖는 레이블들이 존재

nodelabel 추가

[root@master ~/kube/10/nodelabel]# kubectl label nodes node1 gpu=true disk=ssd
node/node1 labeled
[root@master ~/kube/10/nodelabel]# kubectl label nodes node2 gpu=true
node/node2 labeled
[root@master ~/kube/10/nodelabel]# kubectl label nodes node3 disk=ssd
node/node3 labeled
[root@master ~/kube/10/nodelabel]# kubectl get node --show-labels
NAME     STATUS   ROLES           AGE    VERSION   LABELS
master   Ready    control-plane   7d2h   v1.27.7   beta.kubernetes.io/arch=amd64,beta.kubernetes.io/os=linux,kubernetes.io/arch=amd64,kubernetes.io/hostname=master,kubernetes.io/os=linux,node-role.kubernetes.io/control-plane=,node.kubernetes.io/exclude-from-external-load-balancers=
node1    Ready    <none>          7d2h   v1.27.7   beta.kubernetes.io/arch=amd64,beta.kubernetes.io/os=linux,**disk=ssd**,**gpu=true**,kubernetes.io/arch=amd64,kubernetes.io/hostname=node1,kubernetes.io/os=linux
node2    Ready    <none>          7d2h   v1.27.7   beta.kubernetes.io/arch=amd64,beta.kubernetes.io/os=linux,**gpu=true**,kubernetes.io/arch=amd64,kubernetes.io/hostname=node2,kubernetes.io/os=linux
node3    Ready    <none>          7d2h   v1.27.7   beta.kubernetes.io/arch=amd64,beta.kubernetes.io/os=linux,**disk=ssd**,kubernetes.io/arch=amd64,kubernetes.io/hostname=node3,kubernetes.io/os=linux

nodelabel 검색

[root@master ~/kube/10/nodelabel]# kubectl get node -L gpu,disk
NAME     STATUS   ROLES           AGE    VERSION   GPU    DISK
master   Ready    control-plane   7d2h   v1.27.7
node1    Ready    <none>          7d2h   v1.27.7   true   ssd
node2    Ready    <none>          7d2h   v1.27.7   true
node3    Ready    <none>          7d2h   v1.27.7          ssd

yaml 파일로 라벨을 통한 nodeSelector

[root@master ~/kube/10/nodelabel]# vi nodeselector.yaml
[root@master ~/kube/10/nodelabel]# cat nodeselector.yaml
apiVersion: v1
kind: Pod
metadata:
  name: nodeselector-pod
spec:
  nodeSelector:
    disk: ssd
    gpu: "true"
  containers:
  - name: nginx-container
    image: nginx:1.14
    ports:
    - containerPort: 80
[root@master ~/kube/10/nodelabel]# kubectl apply -f nodeselector.yaml

▶ nodeSelector에서 지정한 label(disk:ssd, gpu:true)에 모두 해당하는 node1에 생성됨

확인

[root@master ~/kube/10/nodelabel]# kubectl get pod -o wide
NAME               READY   STATUS    RESTARTS   AGE     IP               NODE    NOMINATED NODE   READINESS GATES
nodeselector-pod   1/1     Running   0          2m48s   10.233.102.179   node1   <none>           <none>

nodeSelector에 잘못된 label을 넣었을 경우 예제

[root@master ~/kube/10/nodelabel]# vi wrong_nodeselector.yaml
[root@master ~/kube/10/nodelabel]# cat wrong_nodeselector.yaml
apiVersion: v1
kind: Pod
metadata:
  name: nodeselector-wrong-pod
spec:
  nodeSelector:
    disk: ssd
    gpu: "true"
    mem: high
  containers:
  - name: nginx-container
    image: nginx:1.14
    ports:
    - containerPort: 80
[root@master ~/kube/10/nodelabel]# kubectl apply -f wrong_nodeselector.yaml
pod/nodeselector-wrong-pod created
[root@master ~/kube/10/nodelabel]# kubectl get pod
NAME                     READY   STATUS    RESTARTS   AGE
nodeselector-pod         1/1     Running   0          4m32s
nodeselector-wrong-pod   0/1     Pending   0          3s
[root@master ~/kube/10/nodelabel]# kubectl describe pod nodeselector-wrong-pod
Name:             nodeselector-wrong-pod
Namespace:        default
Priority:         0
Service Account:  default
Node:             <none>
Labels:           <none>
Annotations:      <none>
Status:           Pending
IP:
IPs:              <none>
Containers:
  nginx-container:
    Image:        nginx:1.14
    Port:         80/TCP
    Host Port:    0/TCP
    Environment:  <none>
    Mounts:
      /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-2j2r5 (ro)
Conditions:
  Type           Status
  PodScheduled   False
Volumes:
  kube-api-access-2j2r5:
    Type:                    Projected (a volume that contains injected data from multiple sources)
    TokenExpirationSeconds:  3607
    ConfigMapName:           kube-root-ca.crt
    ConfigMapOptional:       <nil>
    DownwardAPI:             true
QoS Class:                   BestEffort
Node-Selectors:              disk=ssd
                             gpu=true
                             mem=high
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
  ----     ------            ----  ----               -------
  Warning  FailedScheduling  11s   default-scheduler  0/4 nodes are available: 1 node(s) had untolerated taint {node-role.kubernetes.io/control-plane: }, 3 node(s) didn't match Pod's node affinity/selector. preemption: 0/4 nodes are available: 4 Preemption is not helpful for scheduling..

▶ 해당 레이블을 가진 노드가 없기 때문에 생성되지 않고 pending 상태

Annotation

주석 또는 특정 내용 기록 시 사용

[root@master ~/kube/10/annotations]# vi annotation-pod.yaml
[root@master ~/kube/10/annotations]# cat annotation-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: annotation-pod
  annotations:
    builder: "JHA(test1234@gmail.com)"
    buildDate: "20250315"
    imageRegistry: https://hub.docker.com
spec:
  containers:
  - name: nginx-container
    image: nginx:1.14
    ports:
    - containerPort: 80

[root@master ~/kube/10/annotations]# kubectl apply -f annotation-pod.yaml
pod/annotation-pod configured
[root@master ~/kube/10/annotations]# kubectl describe pod annotation-pod
Name:             annotation-pod
Namespace:        default
Priority:         0
Service Account:  default
Node:             node2/192.168.2.62
Start Time:       Sat, 15 Mar 2025 13:51:26 +0900
Labels:           <none>
Annotations:      buildDate: 20250315
                  builder: JHA(test1234@gmail.com)
                  cni.projectcalico.org/containerID: 0202ca7d4da08f4fefbc83490aeb5fb46798cd2d25d6ed76a1a4ca18178a0785
                  cni.projectcalico.org/podIP: 10.233.75.4/32
                  cni.projectcalico.org/podIPs: 10.233.75.4/32
                  imageRegistry: https://hub.docker.com