Kubebuilder 퀵스타트 편집하기

==개요==
;Quick Start
;퀵 스타트

==전제조건==
* go 버전 v1.20.0+
* docker 버전 17.03+.
* kubectl 버전 v1.11.3+.
* Kubernetes v1.11.3+ 클러스터 접근

버전 및 지원가능성
Kubebuilder가 생성한 프로젝트에는 생성 시 정의된 버전으로 도구를 설치하는 Makefile이 포함되어 있습니다. 해당 도구는 다음과 같습니다.
* [[kustomize]]
* [[controller-gen]]
Makefile및 파일 에 정의된 버전은 go.mod테스트된 버전이므로 지정된 버전을 사용하는 것이 좋습니다.

==설치==
[[kubebuilder]]를 설치합니다.

<syntaxhighlight lang='bash'>
# download kubebuilder and install locally.
curl -L -o kubebuilder "https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)"
chmod +x kubebuilder && mv kubebuilder /usr/local/bin/
</syntaxhighlight>

마스터 브랜치 사용

<code><nowiki>https://go.kubebuilder.io/dl/master/$(go env GOOS)/$(go env GOARCH)</nowiki></code>에서 설치하여 마스터 스냅샷으로 작업할 수 있습니다.

쉘 자동 완성 활성화

Kubebuilder는 명령어 <code>kubebuilder completion <bash|fish|powershell|zsh></code>을 통해 자동완성 지원을 제공하므로, 타이핑을 많이 줄일 수 있습니다. 자세한 내용은 [[kubebuilder 자동완성|자동완성]] 문서를 참조하세요.

==프로젝트 생성==
디렉토리를 생성한 다음 디렉토리 내에서 init 명령을 실행하여 새 프로젝트를 초기화합니다. 예제를 따릅니다.

<syntaxhighlight lang='bash'>
mkdir -p ~/projects/guestbook
cd ~/projects/guestbook
kubebuilder init --domain my.domain --repo my.domain/guestbook
</syntaxhighlight>

$GOPATH에서 개발

프로젝트가 [https://golang.org/doc/code.html#GOPATH GOPATH] 내에서 초기화되면, 암시적으로 호출되는 <code>go mod init</code>가 모듈 경로를 보간합니다. 그렇지 않으면 <code>--repo=<module path></code>을 지정해야 합니다.

Go 모듈 시스템에 익숙하지 않다면 [https://blog.golang.org/using-go-modules Go 모듈 블로그 게시물]을 읽어보세요 .

==API 생성==
다음 명령어를 실행하여 새 API(그룹/버전) <code>webapp/v1</code>와 이에 대한 새 Kind(CRD) <code>Guestbook</code>을 생성합니다.

<syntaxhighlight lang='bash'>
kubebuilder create api --group webapp --version v1 --kind Guestbook
</syntaxhighlight>

Press Options

y리소스 만들기 [y/n] 및 컨트롤러 만들기 [y/n]를 누르면 api/v1/guestbook_types.go internal/controllers/guestbook_controller.go이 종류(CRD)에 대해 조정 비즈니스 로직이 구현되는 파일이 생성됩니다.

Create Resource [y/n]과 Create Controller [y/n]에서 y를 누르면, 각각 API가 정의된 <code>api/v1/guestbook_types.go</code> 파일과, Kind(CRD)를 구현하는 reconciliation 비즈니스 로직이 있는 <code>internal/controllers/guestbook_controller.go</code> 파일이 생성됩니다.

선택사항: API 정의 및 reconciliation 비즈니스 로직을 편집합니다. 자세한 내용은 [https://book.kubebuilder.io/cronjob-tutorial/api-design API 설계] 및 [https://book.kubebuilder.io/cronjob-tutorial/controller-overview 컨트롤러란 무엇인가]를 참조하세요 .

API 정의를 편집하는 경우 다음을 사용하여 커스텀 리소스(CR) 또는 커스텀 리소스 정의(CRD)와 같은 매니페스트를 생성합니다.

<syntaxhighlight lang='bash'>
make manifests
</syntaxhighlight>

예시를 보려면 여기를 클릭하세요. (api/v1/guestbook_types.go)
<syntaxhighlight lang='go'>
// GuestbookSpec은 원하는 방명록 상태를 정의합니다
type GuestbookSpec struct {
    // 추가 사양 필드 삽입 - 원하는 클러스터 상태
    // 중요: 이 파일을 수정한 후 코드를 재생성하려면 "make"를 실행하세요

    // 인스턴스 수량
    // +kubebuilder:validation:Minimum=1
    // +kubebuilder:validation:Maximum=10
    Size int32 `json:"size"`

    // GuestbookSpec 설정을 위한 ConfigMap 이름
    // +kubebuilder:validation:MaxLength=15
    // +kubebuilder:validation:MinLength=1
    ConfigMapName string `json:"configMapName"`

    // +kubebuilder:validation:Enum=Phone;Address;Name
    Type string `json:"alias,omitempty"`
}

// GuestbookStatus는 관찰된 Guestbook 상태를 정의합니다
type GuestbookStatus struct {
    // 추가 상태 필드 삽입 - 클러스터의 관찰된 상태를 정의합니다
    // 중요: 이 파일을 수정한 후 코드를 다시 생성하려면 "make"를 실행하세요.

    // 액티브 Guestbook 노드의 PodName.
    Active string `json:"active"`

    // 스탠바이 Guestbook 노드의 PodName.
    Standby []string `json:"standby"`
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:resource:scope=Cluster

// Guestbook은 guestbooks API의 스키마입니다
type Guestbook struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    Spec   GuestbookSpec   `json:"spec,omitempty"`
    Status GuestbookStatus `json:"status,omitempty"`
}
</syntaxhighlight>

==테스트==
실행하려면 Kubernetes 클러스터가 필요합니다. [[KIND]]를 사용하여 테스트용 로컬 클러스터를 가져오거나 원격 클러스터에 대해 실행할 수 있습니다.

사용된 컨텍스트

컨트롤러는 kubeconfig 파일의 현재 컨텍스트(즉, <code>kubectl cluster-info</code>에 표시되는 모든 컨텍스트)를 자동으로 사용합니다.

클러스터에 CRD를 설치합니다.

<syntaxhighlight lang='bash'>
make install
</syntaxhighlight>

빠른 피드백과 코드 수준 디버깅을 위해, 컨트롤러를 실행하세요(이것은 포그라운드에서 실행되므로, running 상태를 유지하려면 새 터미널로 전환하세요).

<syntaxhighlight lang='bash'>
make run
</syntaxhighlight>

==커스텀 리소스 인스턴스 설치==
Create Resource [y/n]에서 <code>y</code>를 누르면, 샘플에 있는 CRD에 대한 CR이 생성됩니다(API 정의를 변경했다면 편집을 먼저 해야 합니다).

<syntaxhighlight lang='bash'>
kubectl apply -k config/samples/
</syntaxhighlight>

==클러스터에서 실행==
컨트롤러를 다른 클러스터에서 패키징되고 테스트될 준비가 되었다면,

<code>IMG</code>에 위치를 지정하여 이미지를 빌드하고 푸시합니다.

<syntaxhighlight lang='bash'>
make docker-build docker-push IMG=<some-registry>/<project-name>:tag
</syntaxhighlight>

<code>IMG</code>에 지정된 이미지를 사용하여 클러스터에 컨트롤러를 배포합니다.

<syntaxhighlight lang='bash'>
make deploy IMG=<some-registry>/<project-name>:tag
</syntaxhighlight>

레지스트리 퍼미션

이 이미지는 지정한 개인 레지스트리에 게시되어야 합니다. 그리고 작업 환경에서 이미지를 가져오려면 액세스 권한이 필요합니다. 위 명령어가 작동하지 않으면 레지스트리에 대한 적절한 권한이 있는지 확인하십시오.

RBAC 오류

RBAC 오류가 발생하면 자신에게 클러스터 관리자 권한을 부여하거나 관리자로 로그인해야 할 수도 있습니다. 본인의 케이스가 해당될 수 있으니, [https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control#iam-rolebinding-bootstrap GKE 클러스터 v1.11.x 이하에서 Kubernetes RBAC를 사용하기 위한 전제조건]을 참조하세요.

==CRD 언인스톨==
클러스터에서 CRD를 삭제하려면:

<syntaxhighlight lang='bash'>
make uninstall
</syntaxhighlight>

==컨트롤러 언디플로이==
클러스터에서 컨트롤러를 언디플로이합니다.

<syntaxhighlight lang='bash'>
make undeploy
</syntaxhighlight>

==다음 단계==
이제 더 상세한 개요를 보려면 [[Kubebuilder 아키텍처|아키텍처 개념도]]를 참조하고 [[kubebuilder 튜토리얼: CronJob 구축|CronJob 튜토리얼]]을 따라 데모 예제 프로젝트를 개발하여 작동방식을 이해해 보세요.

이미지 배포 플러그인을 사용하여 API 및 컨트롤러 코드 생성

[[kubebuilder/plugins/deploy-image-plugin-v1-alpha|이미지 배포]] 플러그인을 확인하세요. 이 플러그인을 사용하면 API/컨트롤러를 스캐폴드하여 가이드와 모범사례에 따라 클러스터에 피연산자(이미지)를 배포하고 관리할 수 있습니다. 사용자가 생성된 코드를 커스터마이징할 수 있도록 하면서도 목표 달성의 복잡성을 간소화합니다.

==참고==
* https://book.kubebuilder.io/quick-start

[[분류: kubebuilder]]