"Kustomize 활용법 (feat. GitOps 로 가는 여정)" 라는 글이 올라온 것을 보고 예전에 정리했었던 글이 기억나 올려본다.

kustomize의 기본을 이해하는데 도움이 될 것이다.

팀에서는 내부 yaml 관리를 위해 kustomize를 사용하고 있다.

OPA Gatekeeper에서 제공하는 라이브러리인 https://github.com/open-policy-agent/gatekeeper-library 를 사용하기 위해서도 kustomize를 이해해야 한다.

본 페이지에서는 kustomize에 대해 간단하게 그 역할과 사용법을 정리한다.

kustomize?

kustomize는 kustomization파일을 통해 쿠버네티스 객체를 사용자화하는 도구이다.

1.14 이후로는 kubectl에서 kustomzation 파일을 사용한 이 객체들을 관리할 수 있다.

kustomization 파일을 통해 리소스를 확인하거나 이를 클러스터에 적용할 수 있다.

# 리소스확인
kubectl kustomize <kustomization_directory>
# 이 리소스를 적용하려면 kubectl apply를 --kustomize 또는 -k 플래그와 함께 실행한다.
kubectl apply -k <kustomization_directory>

구체적으로는 다음의 기능을 갖고있으며 실제 사용되는 예시를 살펴보자.

• 다른 소스에서 자원들을 생성

• 자원들에 대한 교차 편집 필드 지정

• 자원들의 세트를 구성하고 사용자 정의

자원 생성

Configmap이나 Secret은 pod와 같은 다른 객체에서 설정으로 사용하거나 민감한 정보를 저장하는데 사용한다.

이러한 정보는 클러스터 외부에 존재하는 경우들이 있는데 (.properties 또는 ssh-key) 이러한 사용을 지원하기위해 kustomize는 secretGenerator나 configMapGenerator를 제공한다.

configMapGenerator 사용예시

• 파일 사용

  # create some files
  siim@dev:~/my/kustomize$ cat <<EOF >application.properties
  FOO=Bar
  EOF
  
  # create kustomize file
  siim@dev:~/my/kustomize$ cat <<EOF >./kustomization.yaml
  configMapGenerator:
  - name: example-configmap-1
    files:
    - application.properties
  EOF
  
  # kustomize
  siim@dev:~/my/kustomize$ kubectl kustomize .
  apiVersion: v1
  data:
    application.properties: |
      FOO=Bar
  kind: ConfigMap
  metadata:
    name: example-configmap-1-g4hk9g2ff8

• 환경변수의 활용

  # 환경파일을 지정하지만 BAZ 값은 넣지 않음
  siim@dev:~/my/kustomize$ cat <<EOF >.env
  FOO=Bar
  BAZ
  EOF
  
  # kustomize의 configMapGenerator는 환경변수(env)를 사용하도록 함, 파일은 앞에 것
  siim@dev:~/my/kustomize$ cat <<EOF >./kustomization.yaml
  configMapGenerator:
  - name: example-configmap-1
    envs:
    - .env
  EOF
  
  # 그냥 적용하면 BAZ에 아무것도 넣지 않았으므로 ""로 치환됨
  siim@dev:~/my/kustomize$ kubectl kustomize ./           
  apiVersion: v1
  data:
    BAZ: ""
    FOO: Bar
  kind: ConfigMap
  metadata:
    name: example-configmap-1-kg88t442dc
  
  # 값을 지정하면서 호출하면 그 값이 들어감 Qux..
  siim@dev:~/my/kustomize$ BAZ=Qux kubectl kustomize ./
  apiVersion: v1
  data:
    BAZ: Qux
    FOO: Bar
  kind: ConfigMap
  metadata:
    name: example-configmap-1-892ghb99c8

• 직접 값을 나열

  # kustomization 파일에 직접기입
  siim@dev:~/my/kustomize$ cat <<EOF >./kustomization.yaml
  configMapGenerator:
  - name: example-configmap-2
    literals:
    - FOO=Bar
  EOF
  
  siim@dev:~/my/kustomize$ kubectl kustomize ./
  apiVersion: v1
  data:
    FOO: Bar
  kind: ConfigMap
  metadata:
    name: example-configmap-2-42cfbf598f

secretGenerator 사용예시

• 파일사용

  siim@dev:~/my/kustomize$ cat <<EOF >./password.txt
  username=admin
  password=secret
  EOF
  
  siim@dev:~/my/kustomize$ cat <<EOF >./kustomization.yaml
  secretGenerator:
  - name: example-secret-1
    files:
    - password.txt
  EOF
  
  siim@dev:~/my/kustomize$ kubectl kustomize ./
  apiVersion: v1
  data:
    password.txt: dXNlcm5hbWU9YWRtaW4KcGFzc3dvcmQ9c2VjcmV0Cg==
  kind: Secret
  metadata:
    name: example-secret-1-2kdd8ckcc7
  type: Opaque

• 직접 값을 나열

  siim@dev:~/my/kustomize$ cat <<EOF >./kustomization.yaml
  secretGenerator:
  - name: example-secret-2
    literals:
    - username=admin
    - password=secret
  EOF
  
  siim@dev:~/my/kustomize$ kubectl kustomize ./
  apiVersion: v1
  data:
    password: c2VjcmV0
    username: YWRtaW4=
  kind: Secret
  metadata:
    name: example-secret-2-8c5228dkb9
  type: Opaque

generatorOptions

위 예시들에서 확인할 수 있는 것처럼 kustomize를 사용하여 자원을 만들면 지정한 자원명 뒤에 hash코드가 추가되어 최정 자원명이 생성된다.

이를 하지 않도록 하거나 label과 주석에 임의의 값을 추가하기위해 generatorOptions를 설정할 수 있다.

• suffix를 제거하도록 하고(disablenameSuffixhash) 라벨과 주석을 지정하는 예시

  siim@dev:~/my/kustomize$ cat <<EOF >./kustomization.yaml
  configMapGenerator:
  - name: example-configmap-3
    literals:
    - FOO=Bar
  generatorOptions:
    disableNameSuffixHash: true
    labels:
      type: generated
    annotations:
      note: generated
  EOF
  
  siim@dev:~/my/kustomize$ kubectl kustomize ./
  apiVersion: v1
  data:
    FOO: Bar
  kind: ConfigMap
  metadata:
    annotations:
      note: generated
    labels:
      type: generated
    name: example-configmap-3

필드의 교차편집

나열한 자원에 대해 한꺼번에 다음과 같은 수정을 가할수 있다.

• 모든 자원의 네임스페이스를 동일하게 수정 (namespace:)

• 동일한 prefix나 suffix 추가(namePrefix:, nameSuffix:)

• 동일한 라벨지정 (commonLabels:)

• 동일한 주석지정 (commonAnnotations:)

• 사용예시

  siim@dev:~/my/kustomize$ cat <<EOF >./kustomization.yaml
  namespace: my-namespace
  namePrefix: dev-
  nameSuffix: "-001"
  commonLabels:
    app: bingo
  commonAnnotations:
    oncallPager: 800-555-1212
  resources:
  - deployment.yaml
  EOF
  
  siim@dev:~/my/kustomize$ kubectl kustomize ./
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    annotations:
      oncallPager: 800-555-1212
    labels:
      app: bingo
    name: dev-nginx-deployment-001
    namespace: my-namespace
  spec:
    selector:
      matchLabels:
        app: bingo
    template:
      metadata:
        annotations:
          oncallPager: 800-555-1212
        labels:
          app: bingo
      spec:
        containers:
        - image: nginx
          name: nginx

자원의 구성과 사용자 정의

하나의 파일이나 디렉토리에 자원의 집합을 넣어 관리하는 것이 일반적이다. kustomize는 이를 지원하고 패치나 사용자 정의하여 적용할 수 있도록 한다.

구성측면

resources 필드는 구성내 포함하려는 자원 리스트를 정의한다.

cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
- service.yaml
EOF

사용자정의

patchesStrategicMerge나 patchesJson6092를 통해 패치할 수 있다.

patchesStrategicMerge

Strategic Merge Patch 를 통해 지정된 위치에 값을 재지정한다. 이때 패치 대상은 주어진 이름으로 구분한다.

• 원본파일 (deployment)

  # deployment.yaml 파일 생성
  cat <<EOF > deployment.yaml
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: my-nginx
  spec:
    selector:
      matchLabels:
        run: my-nginx
    replicas: 2
    template:
      metadata:
        labels:
          run: my-nginx
      spec:
        containers:
        - name: my-nginx
          image: nginx
          ports:
          - containerPort: 80
  EOF

• 복제본 조정을 위한 패치

  cat <<EOF > increase_replicas.yaml
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: my-nginx
  spec:
    replicas: 3
  EOF

• 메모리 제한 추가를 위한 패치

  cat <<EOF > set_memory.yaml
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: my-nginx
  spec:
    template:
      spec:
        containers:
        - name: my-nginx
          resources:
            limits:
              memory: 512Mi
  EOF

• kustomize 파일

  cat <<EOF >./kustomization.yaml
  resources:
  - deployment.yaml
  patchesStrategicMerge:
  - increase_replicas.yaml
  - set_memory.yaml
  EOF

• kustomize 결과물: 원본에서 복제본의 개수와 메모리 제한이 바뀌었다

  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: my-nginx
  spec:
    replicas: 3
    selector:
      matchLabels:
        run: my-nginx
    template:
      metadata:
        labels:
          run: my-nginx
      spec:
        containers:
        - image: nginx
          name: my-nginx
          ports:
          - containerPort: 80
          resources:
            limits:
              memory: 512Mi

patchesJson6092

필드에 임의의 행동을 할수 있도록 지원하는 JSON패치를 적용한다.

• 원본파일 (deployment)

  # deployment.yaml 파일 생성
  cat <<EOF > deployment.yaml
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: my-nginx
  spec:
    selector:
      matchLabels:
        run: my-nginx
    replicas: 2
    template:
      metadata:
        labels:
          run: my-nginx
      spec:
        containers:
        - name: my-nginx
          image: nginx
          ports:
          - containerPort: 80
  EOF

• json 패치파일

  # json 패치 생성
  cat <<EOF > patch.yaml
  - op: replace
    path: /spec/replicas
    value: 3
  EOF

• kustomize 파일

  # kustomization.yaml 생성
  cat <<EOF >./kustomization.yaml
  resources:
  - deployment.yaml
  
  patchesJson6902:
  - target:
      group: apps
      version: v1
      kind: Deployment
      name: my-nginx
    path: patch.yaml
  EOF

• kustomize 결과물: 원본에서 복제본 수가 바뀌었다

  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: my-nginx
  spec:
    replicas: 3
    selector:
      matchLabels:
        run: my-nginx
    template:
      metadata:
        labels:
          run: my-nginx
      spec:
        containers:
        - image: nginx
          name: my-nginx
          ports:
          - containerPort: 80

패치파일 없이

패치파일을 만들지 않고 직접 kustomize.yaml에 기술해서 패치를 적용하는 방법도 있다.

• 이미지 변경 (images)

  cat <<EOF >./kustomization.yaml
  resources:
  - deployment.yaml
  images:
  - name: nginx
    newName: my.image.registry/nginx
    newTag: 1.4.0
  EOF

• 변수의 값을 전달하는 형태: prefix나 suffix를 추가하면서 변화되는 경우 이에 대한 대비

  $(MY_SERVICE_NAME)을 자원과 연결하여 생성되는 값으로 대치

  # deployment.yaml 파일 생성(문서 구분 기호를 따옴표로 감쌈)
  cat <<'EOF' > deployment.yaml
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: my-nginx
  spec:
    selector:
      matchLabels:
        run: my-nginx
    replicas: 2
    template:
      metadata:
        labels:
          run: my-nginx
      spec:
        containers:
        - name: my-nginx
          image: nginx
          command: ["start", "--host", "$(MY_SERVICE_NAME)"]
  EOF
  
  # service.yaml 파일 생성
  cat <<EOF > service.yaml
  apiVersion: v1
  kind: Service
  metadata:
    name: my-nginx
    labels:
      run: my-nginx
  spec:
    ports:
    - port: 80
      protocol: TCP
    selector:
      run: my-nginx
  EOF
  
  cat <<EOF >./kustomization.yaml
  namePrefix: dev-
  nameSuffix: "-001"
  
  resources:
  - deployment.yaml
  - service.yaml
  
  vars:
  - name: MY_SERVICE_NAME
    objref:
      kind: Service
      name: my-nginx
      apiVersion: v1
  EOF

Base와 Overlay

https://kubernetes.io/ko/docs/tasks/manage-kubernetes-objects/kustomization/#base와-overlay

kustomize는 base와 overlay를 통해 결합한다.

base는 로컬이나 원격의 위치를 지정하여 이를 사용하도록 kustomization.yaml 에 정의한다.

overlay는 kustomization.yaml이 있는 위치이고 이를 kustomize한다.

base는 overlay를 알지못하며 overlay에는 여러개의 base를 지정할 수 있다.

• base 생성

  # base를 가지는 디렉터리 생성
  mkdir base
  # base/deployment.yaml 생성
  cat <<EOF > base/deployment.yaml
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: my-nginx
  spec:
    selector:
      matchLabels:
        run: my-nginx
    replicas: 2
    template:
      metadata:
        labels:
          run: my-nginx
      spec:
        containers:
        - name: my-nginx
          image: nginx
  EOF
  
  # base/service.yaml 파일 생성
  cat <<EOF > base/service.yaml
  apiVersion: v1
  kind: Service
  metadata:
    name: my-nginx
    labels:
      run: my-nginx
  spec:
    ports:
    - port: 80
      protocol: TCP
    selector:
      run: my-nginx
  EOF
  # base/kustomization.yaml 생성
  cat <<EOF > base/kustomization.yaml
  resources:
  - deployment.yaml
  - service.yaml
  EOF

• overlay 생성

  mkdir dev
  cat <<EOF > dev/kustomization.yaml
  bases:
  - ../base
  namePrefix: dev-
  EOF
  
  mkdir prod
  cat <<EOF > prod/kustomization.yaml
  bases:
  - ../base
  namePrefix: prod-
  EOF

• kustomize 결과물 (이름의 prefix가 바뀜)

  siim@adm:~/tks/kustomize$ kubectl kustomize dev
  apiVersion: v1
  kind: Service
  metadata:
    labels:
      run: my-nginx
    name: dev-my-nginx
  spec:
  ...
  
  siim@adm:~/tks/kustomize$ kubectl kustomize prod
  apiVersion: v1
  kind: Service
  metadata:
    labels:
      run: my-nginx
    name: prod-my-nginx
  spec:
    ports:
  ...

다단계로 base와 overlay를 수행할 수 있으며 상속과 비슷하게 base는 그 안에 정의된 모든 내역(앞단계의 base에 overlay를 수행한 것)을 포함하고 있다.

kustomize의 기능

kustomize은 다음의 기능들을 제공하며 kustomize.yaml 작성시 필드에 지정해서 사용할 수 있다.