[Kubernetes] CRD, 커스텀 리소스, 그리고 컨트롤러

🔊 해당 포스팅은 시작하세요! 도커/쿠버네티스 서적을 읽고 개인적인 목적 하에 작성되는 글입니다. 포스팅에 사용되는 모든 자료는 제가 직접 재구성하였음을 알립니다.
 

Kubernetes

---

이번 포스팅에서는 쿠버네티스에서 커스텀 리소스, CRD, 그리고 컨트롤러에 대해 알아본다. 직전 포스팅까지 우리는 모두 쿠버네티스에서 자체적으로 제공하는 리소스 오브젝트를 생성해왔다. 파드, 레플리카셋, 디플로이먼트, HPA, 스토리지 클래스, PV, PVC 등등 이런 리소스 오브젝트들은 쿠버네티스를 설치하기만 하면 기본적으로 내장되어 있어 사용할 수 있는 오브젝트들이다. 

 

하지만 이렇게 기본적으로 쿠버네티스에서 제공하는 리소스 오브젝트 말고도 우리가 직접 새로운 리소스의 종류를 만들어서 쿠버네티스에서도 사용할 수 있다. 이렇게 직접 만든 리소스를 커스텀 리소스(Custom Resource)라고 부른다. 사실 커스텀 리소스를 제대로 사용하고 이해하기 위해서는 컨트롤러라는 별도의 컴포넌트를 이해하고 구현할 줄 알아야 한다. 쿠버네티스에서의 컨트롤러는 이른바 Cloud-native Infrastructure 이라고 하는 생태계에서 자주 쓰이는 개념을 내포하고 있다. 커스텀 리소스를 본격적으로 알아보기 전에 우리는 이 '컨트롤러' 라고 하는 개념에 대해서 얕게나마라도 배우고 넘어가도록 하자.

1. 쿠버네티스의 2가지 동작 방식 : 명령(Imperative) 과 선언(Declarative)!

쿠버네티스에서는 리소스를 동작시키게 하는 방식이 2가지가 존재한다. 명령형과 선언적 이 2가지이다. 우선 예전으로 돌아가서 도커를 배울 때 우리는 docker run ~ 또는 docker build ~ 와 같은 명령어를 수행했었다. 결론부터 이야기하면 이런 방식은 명령형 방식에 속한다. 즉, docker run, docker build 와 같은 특정 명령을 처리하는 주체와 통신해서 그 주체가 작업을 수행하고 결과값을 돌려받는 방식을 명령형 방식이라고 한다. 쿠버네티스에서도 명령형 방식이 지원되는데, 일례로 kubectl run ~, kubectl create ~ 와 같은 명령어들이다.

 

반면에 직전 쿠버네티스 시리즈 포스팅까지 배워오면서 리소스를 동작시킬 때 모두 우리는 kubectl apply -f ~ 라는 명령어를 사용했다. 이러한 명령어를 선언적 방식이라고 하는데, 대체 '어떤 것'을 선언한다는 것일까? 우리에게 그동안 익숙해왔던 kubectl apply -f 명령어를 다시 떠올려보자. kubectl apply -f 명령어 뒤에 우리는 어떤 것을 명시했었나? 바로 YAML 파일의 경로이다. 그리고 그 YAML 파일에는 우리가 생성 또는 적용하고자 하는 사항을 명시한 매니페스트 파일이었다. 이렇게 선언형 방식은 최종적으로 도달해야 하는 상태 즉, 우리가 명시한 YAML 파일 내용의 상태를 정의한 뒤, 현재 상태가 도달해야 하는 상태와 다를 경우 현재 상태를 도달해야 하는 상태로 일치시키도록 하는 방법이다.(참고로 도달해야 하는 상태를 '바람직한 상태' 라고도 하며 Desired State 라고 한다) 쿠버네티스에서는 둘 중 선언적 방식을 지향한다.

 

조금 더 세부적으로 들어가서, 명령형과 선언적 방식 각각 어떻게 동작하는지 순서를 살펴보도록 하자. 먼저 명령형 방식은 명령어(ex. kubectl create ~)를 요청하면 그 요청은 kube-api server 파드로 인입되어 create 명령어 뒤에 명시한 동작들 예를 들어, 파드를 생성한다거나 HPA를 생성한다거나 등의 특정 리소스를 생성하도록 동작한다. 하지만 이러한 명령형 방식은 이미 생성한 리소스를 또 생성하려고 하면 에러가 발생하게 된다. 예를 들어, kubectl create ~ 명령어로 "zedd" 라는 이름의 파드를 생성한 뒤, 또 kubectl create 명령어로 "zedd" 라는 이름의 파드를 생성하려고 하면 에러가 발생한다. 이렇게 명령형 방식은 "쿠버네티스야, 너 이러쿵 저러쿵 동작해!" 라고 직접적으로 어떻게 행동할지 명시를 해주기 때문에 이미 생성된 리소스를 또 생성하려고 하면 에러가 발생한다.

 

반면에 선언적 방식은 이와 다르게 동작한다. 예를 들어, kubectl apply -f ~ 명령어를 입력하는 순간 똑같이 kube-api server 파드로 요청이 인입되지만, 그 이후의 단계가 명령형 방식과 다르다. 일단 그림으로 살펴보자.

 

 

먼저 etcd 라는 쿠버네티스의 모든 상태 정보가 저장되는 저장소로 요청이 들어간 뒤, 쿠버네티스 컨트롤러하고 하는 컴포넌트가 실질적으로 어떤 동작을 수행할지 내부적으로 결정한다. 사실 kubectl apply -f 명령어는 뒤에 선언하는 YAML 파일이 최종적으로 완성해야 할 상태라고 알려주는 것 뿐이지, kubectl apply 명령어 자체가 쿠버네티스에게 어떤 동작을 취해서 어떤 리소스를 만들게 명령하는 직접적인 주체가 아니다.

 

쿠버네티스 컨트롤러라는 것은 노드 컨트롤러, 디플로이먼트 컨트롤러 등 여러가지가 별도로 존재할 수도 있겠지만 쿠버네티스에서는 복잡성을 줄이고자 이런 별도의 컨트롤러들이 모두 한 곳에서 수행되고 관리될 수 있도록 쿠버네티스 컨트롤러 매니저라는 컴포넌트가 존재한다. 이 컨트롤러 매니저는 쿠버네티스의 핵심 컴포넌트이기 때문에 kube-system 이라는 네임스페이스에 파드로 존재한다.  따라서 이 컨트롤러 매니저가 Watch를 수행하다가, 우리가 kubectl apply -f 명령어와 함께 바람직한 상태를 명시한 YAML 파일을 명시해주면 컨트롤러 매니저는 해당 YAML 파일을 보고 그에 맞는 노드 컨트롤러 또는 디플로이먼트 컨트롤러 등을 사용해 리소스를 생성하게 된다.

2. 나만의 리소스를 쿠버네티스에서 사용하자 : 커스텀 리소스(Custom Resource)

이제 본격적으로 나만의 리소스를 쿠버네티스에서도 사용할 수 있는 커스텀 리소스에 대해서 알아보도록 하자. 어떤 리소스 오브젝트의 매니페스트를 보았을 때, 간단하게 커스텀 리소스인지 아닌지 구분하는 방법 중 하나는 매니페스트 파일의 apiVersion 값을 보면 된다. 기존에 배웠던 쿠버네티스트 리소스 오브젝트의 매니페스트와는 달리 커스텀 리소스의 매니페스트의 apiVersion 값엔 유독 특이한 값들이 명시되어 있다. 마치 URL 도메인 같기도 하고, 어쨌건 뭔가 특이하다.

 

# prometheus 스택의 PodMonitor 라는 커스텀 리소스의 매니페스트
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: example-app
  labels:
    team: frontend
spec:
  selector:
    matchLabels:
      app: example-app
  podMetricsEndpoints:
  - port: web

 

커스텀 리소스를 사용하는 방법에는 크게 2가지가 있다. 첫번째는 파드, 디플로이먼트, 서비스 등과 같은 쿠버네티스에서 제공하는 리소스 오브젝트들을 추상화함으로써 쿠버네티스 리소스를 묶어 놓은 패키지처럼 사용하는 방법이 있다. 두번째는 쿠버네티스와 전혀 상관이 없는 로직을 커스텀 리소스와 연동하는 방법이다. 

 

실제로 대표적인 커스텀 리소스 중 하나로 Prometheus Operator를 보면 kustomize, helm 과 같은 명령어로 한 번에 Prometheus 와 관련된 리소스들을 생성할 수 있다. 이렇게 하면 복잡하고 많은 리소스에 대한 관리의 복잡성을 줄임으로써 쿠버네티스 오브젝트를 맘껏 확장해 사용할 수 있게 된다.

 

하지만 이렇게 편리한 커스텀 리소스를 가져다 사용하는 입장에서는 당연히 편리하겠지만, 이러한 편리한 커스텀 리소스를 직접 만드는 단계는 꽤나 쉽지 않은 과정을 거쳐야 한다.(역시 모두의 편의를 위해 누군가는 뒤에서 고생을...) 어쨌거나 구체적으로 커스텀 리소스를 생성하기 위한 단계는 크게 아래와 같다.

 

1. 현재 상태를 커스텀 리소스에 대한 바람직한 상태로 변화시킬 수 있는 컨트롤러를 구현하고 실행한다
2. 커스텀 리소스의 상세 정보를 정의하는 CRD(Custom Resource Definition) 리소스를 생성한다
3. CRD에 정의된 데이터에 맞춰 커스텀 리소스를 생성한다
4. 1번에서 실행한 컨트롤러는 생성된 커스텀 리소스를 감지하고, 커스텀 리소스가 원하는 바람직한 상태가 되도록 컨트롤러가 작업을 수행한다

위 단계 속에서 등장한 개념들을 하나씩 살펴보도록 하자. 먼저 CRD이다.

2-1. 커스텀 리소스에 대한 명세서 : CRD(Custom Resource Definition)

CRD는 말 그대로 커스텀 리소스에 대한 정의를 적어놓은 명세서와 같은 것이다. 그래서 실제로 CRD는 YAML 파일로 정의되며, 쿠버네티스에서 기본적으로 제공하는 CustomResourceDefinition 이라는 이름의 리소스 오브젝트를 기반으로 매니페스트를 생성한다. CRD를 정의하는 예시 매니페스트를 하나 살펴보자.

 

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: mycrds.zedd.com
spec:
  group: zedd.com
  scope: Namespaced
  names:
    plural: mycrds
    singular: mycrd
    kind: Zedd
    shortNames: ["z"]
  versions:
    - name: v1alpha1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          required: ["spec"]
          properties:
            spec:
              required: ["myvalue"]
              type: object
              properties:
                myvalue:
                  type: "string"
                  minimum: 1

 

위 매니페스트의 의미를 하나씩 순차적으로 알아보자.

 

• metadata.name: CRD의 이름을 의미. 즉, 위 매니페스트로 생성되는 CRD의 고유한 이름을 의미한다
• spec.group: 커스텀 리소스의  API 그룹을 의미. 이 값과 하단에서 알아볼 spec.names.plural 값을 concatenate한 값이 metadata.name과 일치해야 한다. 정확히는 "spec.names.plural 값 + `.` + spec.group" 문자열을 합친 것이 metadata.name과 일치해야 함
• spec.scope: Namespaced :: 커스텀 리소스가 네임스페이스에 종속적인 리소스인지 여부를 나타냄
• spec.names.plural: 커스텀 리소스의 복수형을 나타내는 이름(단적인 예로, 우리가 kubectl get pods 라고 명령어를 수행하는데, 이 때 'pods'가 파드라는 리소스의 복수형을 의미)
• spec.names.singular: 커스텀 리소스의 단수형을 나타내는 이름
• spec.names.kind: YAML 파일에서 정의할 때 kind 항목에 나타낼 커스텀 리소스 이름
• spec.names.shortNames: ["z"] :: 커스텀 리소스 이름의 줄임말(ex. 디플로이먼트를 kubectl get deploy 만 해도 출력되도록 한느 것처럼)
• spec.versions[0].name: 커스텀 리소스의 API 버전. 참고로 해당 값은 spec.group에 명시된 값을 함께 이용하여 커스텀 리소스가 속할 API 그룹과 버전을 설정함. 보통은 "{API 그룹}/{버전}" 형태로 정의함. 따라서 위 예시에서는 "zedd.com/valpha1"이 됨.
• spec.versions[0].schema.openAPIV3Schema: 해당 영역에 커스텀 리소스에 대한 데이터를 정의함
• spec.versions[0].schema.required: ["spec"] :: 해당 커스텀 리소스를 정의할 때는 반드시 'spec' 영역이 존재해야 한다는 조건을 명시
• spec.versions[0].schema.properties: 커스텀 리소스에 저장될 데이터 형식을 의미
  • properties 영역을 보면 required에 명시한 것처럼 spec 영역이 있고, 또 다른 required가 등자하는데, 이는 "myvalue" 라는 값이 꼭 있어야 하고, 이 myvalue 라는 값에 대해서 또 properties를 정의하는데, 이 때는 또 문자열(string) 형태이어야 하고, 최소 1글자 이상이어야 함을 의미함

위와 같은 매니페스트를 정의하고 똑같이 kubectl apply -f 명령어를 수행하면 CRD가 생성이 된다. 그리고 이 생성된 CRD를 이용해서 우리는 커스텀 리소스를 생성할 수 있다. 방금 위에서 정의한 CRD가 생성되었다고 가정하고, 이 CRD를 활용하는 커스텀 리소스를 생성하는 예시 매니페스트는 다음과 같다.

 

apiVersion: zedd.com/v1alpha1
kind: Zedd
metadata:
  name: my-custom-resource-zedd
spec:
  myvalue: "This is required value in zedd crd"

 

위 매니페스트에 대해서도 kubectl apply -f 명령어를 수행하면 Zedd 라는 커스텀 리소스가 생성된다. 

2-2. CRD, 커스텀 리소스, 컨트롤러 간의 관계

직전 목차까지 해서 CRD와 커스텀 리소스가 무엇인지, 어떻게 생성하는지 살펴보았다. 사실 이 2개의 개념이 아직까지는 혼란스러울 수 있다. 그리고 이 2개의 개념과 더불어 컨트롤러라는 개념도 같이 등장하는데, 우선 이 3가지 개념이 대체 어떤 관계가 있는 것인지 도식화해서 알아볼 필요가 있다.

 

CRD, CR, Controller

 

직전 목차에서 살펴본 것처럼 CRD는 커스텀 리소스를 생성하기 위한 정의를 명시해놓은 것 뿐이다. 예를 들어, 커스텀 리소스 매니페스트에서 apiVersion 값엔 어떤 값을 써야하고, 커스텀 리소스의 이름은 어떻게 할 것이며, 어떤 필드는 필수적으로 넣어야 하고 등등..을 정의한다. 이렇게 해서 CRD와 커스텀 리소스를 생성하면 끝일까? 아니다.

 

사실 커스텀 리소스도 단순한 YAML 파일에 불과하다. 커스텀 리소스를 정의한 YAML 파일에 대해서 kubectl apply -f 명령어를 수행한다고 한들 아무런 일도 일어나지 않는다. 이 커스텀 리소스를 인지하는 컨트롤러가 없다면 말이다.

 

컨트롤러는 커스텀 리소스라는 etcd에 저장된 데이터가 실제로 어떠한 파드라 서비스 등과 같은 형태로 동작하도록 정의한 구현체이다. 예를 들어, 비록 쿠버네티스에서 빌트인으로 제공하는 리소스이지만 레플리카셋이라는 일종의 커스텀 리소스는 "라벨 셀렉터가 일치하는 일정 개수의 파드를 항상 유지하는" 동작이였고, 이 동작을 실질적으로 수행되도록 하는 것은 컨트롤러 매니저라는 쿠버네티스 컴포넌트 내부에서 수행된다. 따라서 우리가 직전 목차에서 "Zedd" 라는 종류의 커스텀 리소스가 실질적인 동작을 수행하게 하려면 이 "Zedd" 라는 커스텀 리소스가 동작을 수행하도록 하는 컨트롤러라는 것이 구현되어 있어야 한다는 것이다. 그리고 이 컨트롤러는 Go언어와 같은 소스코드 레벨의 비즈니스 로직으로 구현되어야 한다.(물론 컨트롤러를 구현하는 것 자체가 쉽지 않기 때문에 Operator SDK나 KubeBuilder와 같은 다양한 프레임크가 존재한다)

 

만약 예를 들어, "Zedd" 라는 커스텀 리소스가 수행하는 목적이 "항상 2개의 파드를 생성하는 것" 이라고 해보자. 이 때, CRD, 커스텀 리소스, 컨트롤러의 동작 과정은 다음과 같다.

 

 

(커스텀 리소스에 대한 컨트롤러가 이미 구현되어 있다고 가정했을 때)가장 먼저 CRD를 생성하고, 다음으로 커스텀 리소스를 생성한다. 이제 컨트롤러는 커스텀 리소스가 생성된 것을 감지하고, 해당 커스텀 리소스가 의도하는 목적을 달성하기 위한 비즈니스 로직을 수행한다. 이 '비즈니스 로직'이란 것은 바로 파드 2개를 생성하는 것이다.

 

이렇게 컨트롤러가 비즈니스 로직을 수행 즉, 쿠버네티스 상에서는 '현재 상태가 바람직한 상태가 되도록 하는'이 동작을 "Reconcile" 이라고 부른다는 점도 알아두자. 그리고 이렇게 CRD를 사용할 수 있도록 컨트롤러를 구현하는 방법을 오퍼레이터(Operator) 패턴이라고 부른다. 

 

이러한 CRD를 사용해서 오퍼레이터 패턴을 활용해서 커스텀 리소스를 사용하는 방법은 쿠버네티스의 기능을 확장할 때 매우 중요하게 여겨지는 원리 중 하나이다. 물론 커스텀 리소스를 사용하는 방법으로 CRD와 오퍼레이터 패턴만을 이용할 수 있는 것은 아니라는 점도 알아두자.