[golang] kubernetes Operator 만들기 Kubebuilder API

반응형

 

Kubebuilder API 생성

이번에는 kubebuilder CLI를 이용해서 api를 생성해보는 실습을 공식 doc 예시를 바탕으로 진행해 보았다.

 

사전 용어

Kubernetes에서 API에 대해 이야기할 때 groups, versions, kinds, resources.의 4가지 용어를 자주 사용합니다.

 

그룹 및 버전

Kubernetes의 API 그룹은 단순히 관련 기능의 집합입니다. 각 그룹에는 이름에서 알 수 있듯이 시간이 지남에 따라 API의 작동 방식을 변경할 수 있는 하나 이상의 버전이 있습니다.

 

종류 및 리소스

각 API 그룹 버전에는 하나 이상의 API 유형이 포함되어 있으며 이를 Kinds라고 합니다. Kind는 버전 간에 양식을 변경할 수 있지만 각 양식은 다른 양식의 모든 데이터를 저장할 수 있어야 합니다(필드 또는 주석에 데이터를 저장할 수 있습니다). 이는 이전 API 버전을 사용하면 새로운 데이터가 손실되거나 손상되지 않는다는 것을 의미합니다.

 

가끔 리소스에 대한 언급도 들을 수 있습니다. 리소스는 API에서 Kind를 단순히 사용하는 것입니다. 종종 Kinds와 리소스 간에 일대일 매핑이 있습니다. 예를 들어 포드 리소스는 Pod Kind에 해당합니다. 그러나 때때로 동일한 Kind가 여러 리소스에 의해 반환될 수도 있습니다. 예를 들어 Scale Kind는 배포/스케일 또는 복제 세트/스케일과 같은 모든 스케일 하위 리소스에 의해 반환됩니다. 이것이 Kubernetes HorizonPodAutoscaler가 다른 리소스와 상호 작용할 수 있도록 하는 것입니다. 그러나 CRD의 경우 각 Kind는 단일 리소스에 해당합니다.

 

리소스는 항상 소문자이며 관례에 따라 Kind의 소문자 형태입니다.

 

Go에서 어떻게 사용하는지?

우리가 kind의 특정한 group-version을 제공하면 그것을 GroupVersionKind, 줄여서 GVK라고 부른다.

 

어떻게 API를 만드는가?

간단하게 kubebuilder create api 명령을 사용해 API를 생성할 수 있다.

 

Kind를 CR과 CRD로 만드는걸 목표로 한다.

Go 구조는 데이터에 대한 스키마뿐만 아니라 새로운 유형이라고 불리는 데이터를 추적하는 CRD를 생성하는 데 사용됩니다. 그런 다음 컨트롤러가 관리할 사용자 지정 객체의 인스턴스를 만들 수 있습니다.

우리의 API와 리소스는 클러스터에서 우리의 솔루션을 나타냅니다. 기본적으로, CRD는 우리의 맞춤형 객체의 정의이고, CR은 그것의 예시입니다.

 

new API 추가하기

kubebuilder create api를 이용해 새로운 Kind와 controller의 템플릿을 구성할 수 있다.

kubebuilder create api --group batch --version v1 --kind CronJob

 

y를 두번 눌러서 Resource와 Controller를 생성한다.

 

각 group-version에 대해 이 명령을 처음 호출하면 새 group-version에 대한 디렉토리가 생성됩니다.

 

또한 CronJob Kind의 api/v1/cronjob_types.go 파일을 추가했습니다. 다른 종류의 명령어를 호출할 때마다 해당 파일이 추가됩니다

 

.

meta/v1 API group을 import한걸 확인할 수 있고 이는 Kubernetes의 대부분의 api를 포함한다.

// api.v1.groupversion_info.go
package v1

import (
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

 

 

다음으로, 우리는 우리 종류의 Spec과 Status에 대한 유형을 정의합니다. Kubernetes는 원하는 상태(Spec)를 실제 클러스터 상태(다른 개체의 Status) 및 외부 상태와 조정한 후 관찰한 것(Status)을 기록함으로써 기능합니다.

따라서 모든 함수 개체는 Spec과 Status를 포함합니다.

ConfigMap과 같은 몇몇 유형은 원하는 상태를 인코딩하지 않기 때문에 이 패턴을 따르지 않지만

대부분의 유형은 이 패턴을 따릅니다.

//api.api.v1.cronjob_types.go

// EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!
// NOTE: json tags are required.  Any new fields you add must have json tags for the fields to be serialized.

// CronJobSpec defines the desired state of CronJob
type CronJobSpec struct {
    // INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
    // Important: Run "make" to regenerate code after modifying this file
}

// CronJobStatus defines the observed state of CronJob
type CronJobStatus struct {
    // INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
    // Important: Run "make" to regenerate code after modifying this file
}

 

 

다음으로 실제 Kinds, CronJob 및 CronJobList에 해당하는 유형을 정의합니다.

CronJob은 우리의 루트 유형이며, CronJob kind에 대해 설명합니다.

모든 Kubernetes 개체와 마찬가지로 TypeMeta(API 버전 및 Kind를 설명함)를 포함하며 이름, 네임스페이스, 레이블 등을 포함하는 ObjectMeta도 포함합니다.

CronJobList는 단순히 여러 개의 CronJob을 위한 컨테이너입니다.

LIST와 같이 대량 작업에 사용되는 Kind입니다.일반적으로 우리는 이 중 어느 것도 수정하지 않습니다.

모든 수정은 사양 또는 상태에 따라 이루어집니다.

 

 

그 작은 +kubebuilder:object:root comment를 마커라고 합니다.

잠시 후에 더 많이 볼 수 있겠지만 컨트롤러 도구(우리 코드 및 YAML 생성기)에 추가 정보를 알려주는 추가 메타데이터 역할을 한다는 것을 알아야 합니다.

 

이 특정 유형은 개체 생성기에 이 유형이 Kind를 나타낸다고 말합니다.

그런 다음 개체 생성기는 runtime.Object 인터페이스를 생성합니다. 이것은 Kinds를 나타내는 모든 유형이 구현해야 하는 표준 인터페이스입니다.

 

마지막으로 API 그룹에 대한 Go 타입을 추가한다 (init)

//api.api.v1.cronjob_types.go

//+kubebuilder:object:root=true
//+kubebuilder:subresource:status
c
// CronJob is the Schema for the cronjobs API
type CronJob struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    Spec   CronJobSpec   `json:"spec,omitempty"`
    Status CronJobStatus `json:"status,omitempty"`
}

//+kubebuilder:object:root=true

// CronJobList contains a list of CronJob
type CronJobList struct {
    metav1.TypeMeta `json:",inline"`
    metav1.ListMeta `json:"metadata,omitempty"`
    Items           []CronJob `json:"items"`
}

func init() {
    SchemeBuilder.Register(&CronJob{}, &CronJobList{})
}

 

이상으로 kubebuilder create api 명령어로 자동 생성되는 템플릿 구성에 대해 알아 보았다.

 

 

 

Reperence

https://book.kubebuilder.io/cronjob-tutorial/cronjob-tutorial

Tutorial: Building CronJob - The Kubebuilder Book