개발자를 위한 clusterctl 편집하기

==개요==
;clusterctl for Developers
;개발자를 위한 clusterctl
* 이 문서에서는 개발 작업흐름 중에 <code>clusterctl</code>을 사용하는 방법을 설명합니다.

==전제조건==
* Cluster API 개발 셋업 (go, git, kind v0.9 이상, Docker v19.03 이상 등)
* Cluster API GitHub 리포지토리의 로컬 클론
* 설치하려는 제공자에 대한 GitHub 리포지토리의 로컬 클론

==clusterctl 빌드==
Cluster API의 로컬 복제본 루트에서, 다음을 실행하여 clusterctl 바이너리를 빌드할 수 있습니다.

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

빌드 결과물은 bin/폴더에 저장됩니다. 이를 사용하려면 전체경로를 지정하거나 별칭을 생성하거나 $PATH 아래의 폴더에 복사해야 합니다.

==로컬 아티팩트 사용==
clusterctl은 기본적으로 제공자 리포지토리에 게시된 아티팩트를 사용합니다. 개발 작업흐름 중에 로컬 워크스테이션의 아티팩트를 사용할 수 있습니다.

그렇게 하는 데에는 두 가지 옵션이 있습니다.
* 게시된 단일 아티팩트를 로컬 아티팩트로 오버라이드하려는 경우, 오버라이드 레이어를 사용하세요.
* 게시된 아티팩트를 사용하지 않고 대신 로컬 아티팩트를 사용하려면, 로컬 리포지토리를 생성하세요.

로컬 아티팩트를 생성하려면, 다음 지침을 따르세요.

===로컬에서 아키팩트 빌드===
CAPI 코어 제공자, kubeadm 부트스트랩 제공자, kubeadm 제어 플레인 제공자, Docker 인프라 제공자를 위한 아티팩트를 빌드하려면 다음을 수행하십시오.

<syntaxhighlight lang='bash'>
make docker-build REGISTRY=gcr.io/k8s-staging-cluster-api PULL_POLICY=IfNotPresent
</syntaxhighlight>

===clusterctl-settings.json 파일 생성===
다음으로, <code>clusterctl-settings.json</code> 파일을 생성하여 Cluster API의 로컬 클론에 둡니다. 이 파일은 [[#로컬 리포지토리 생성|create-local-repository.py]]에서 사용됩니다. 예시는 다음과 같습니다.

<syntaxhighlight lang='json'>
{
  "providers": ["cluster-api","bootstrap-kubeadm","control-plane-kubeadm", "infrastructure-aws", "infrastructure-docker"],
  "provider_repos": ["../cluster-api-provider-aws"]
}
</syntaxhighlight>

'''providers''' (Array[]String, default=[]): 활성화할 제공자 목록. 자세한 내용은 [[#사용가능한 제공자|사용가능한 제공자]]를 참조하세요.

'''provider_repos''' (Array[]String, default=[]): 사용하려는 모든 제공자에 대한 경로 목록. 각 제공자에는 제공자 애셋을 빌드하는 방법을 설명하는 <code>clusterctl-settings.json</code> 파일이 있어야 합니다.

===로컬 리포지토리 생성===
Cluster API의 로컬 복사본 루트에서 create-local-repository hack을 실행합니다.

<syntaxhighlight lang='bash'>
cmd/clusterctl/hack/create-local-repository.py
</syntaxhighlight>

스크립트는 설치하려는 제공자의 소스 폴더에서 읽고 제공자의 애셋을 빌드한 다음 <code>$XDG_CONFIG_HOME/cluster-api/dev-repository/</code> 아래에 있는 로컬 리포지토리 폴더에 둡니다. 또한 명령어 출력은 필요한 모든 플래그와 함께 <code>clusterctl init</code> 명령어를 제공합니다. 출력은 다음과 비슷할 것입니다.

<syntaxhighlight lang='bash'>
clusterctl 로컬 오버라이드는 cluster-api, bootstrap-kubeadm, control-plane-kubeadm, infrastructure-docker, infrastructure-aws 제공자에 대한 로컬 리포지토리에서 생성됩니다.
이를 사용하려면 다음을 실행하십시오.

clusterctl init \
   --core cluster-api:v0.3.8 \
   --bootstrap kubeadm:v0.3.8 \
   --control-plane kubeadm:v0.3.8 \
   --infrastructure aws:v0.5.0 \
   --infrastructure docker:v0.3.8 \
   --config $XDG_CONFIG_HOME/cluster-api/dev-repository/config.yaml
</syntaxhighlight>

이 명령어는 clusterctl이 로컬 리포지토리를 사용하도록 하는 데 필요한 모든 설정이 포함된 $XDG_CONFIG_HOME/cluster-api/dev-repository/config.yaml 설정 파일을 사용합니다(머신에 $XDG_CONFIG_HOME이 설정되지 않은 경우 $HOME으로 대체됩니다).

;경고

개발 세션 중에 구동 중인 모든 clusterctl 명령어에 --config ...를 전달해야 합니다.

위의 설정 파일은 오버라이드 레이어 폴더의 위치를 변경하여 개발 세션이 다른 로컬 아티팩트에 의해 하이재킹되지 않도록 합니다.

Docker와 인메모리 제공자를 제외하고, 로컬 리포지토리 폴더에는 클러스터 템플릿이 포함되어 있지 않으므로, 템플릿을 로컬 리포지토리에 복사하지 않으면 <code>clusterctl generate cluster</code> 명령어가 실패합니다.

;야간 빌드
Cluster API 야간 빌드를 사용하여 테스트를 실행하려면 야간 빌드 폴더를 전달하여 hack을 실행할 수 있습니다(필요에 따라 버킷 이름 끝에 있는 날짜를 변경하세요).

<syntaxhighlight lang='bash'>
cmd/clusterctl/hack/create-local-repository.py https://storage.googleapis.com/artifacts.k8s-staging-cluster-api.appspot.com/components/nightly_main_20240101
</syntaxhighlight>

참고: 이는 코어 Cluster API 야간 빌드에서만 작동합니다.

====사용가능한 제공자====
현재 스크립트에는 다음 제공자가 정의되어 있습니다.
* <code>cluster-api</code>
* <code>bootstrap-kubeadm</code>
* <code>control-plane-kubeadm</code>
* <code>infrastructure-docker</code>


Cluster API의 로컬 클론에서 <code>clusterctl-settings.json</code>을 편집하여 더 많은 제공자를 추가할 수 있습니다. 각 <code>privider_repo</code>에는 제공자 애셋을 빌드하는 방법을 설명하는 자체 <code>clusterctl-settings.json</code>이 있어야 합니다.

<syntaxhighlight lang='json'>
{
  "name": "infrastructure-aws",
  "config": {
    "componentsFile": "infrastructure-components.yaml",
    "nextVersion": "v0.5.0"
  }
}
</syntaxhighlight>

==kind 관리 클러스터 생성==
kind는 관리 클러스터로 사용할 Kubernetes 클러스터를 제공할 수 있습니다. 자세한 내용은 Kubernetes 클러스터 설치 및/또는 구성을 참조하세요.

clusterctl init을 실행하기 전에, 모든 필요한 이미지가 kind 클러스터에서 사용가능한지 확인해야 합니다.

이는 Docker Hub 또는 gcr.io와 같은 일부 이미지 저장소에 게시된 이미지의 경우 항상 해당되지만, 로컬로 빌드된 이미지의 경우에는 해당되지 않습니다. 이 경우 <code>kind load</code>를 사용하여 로컬로 빌드된 이미지를 이동할 수 있습니다. 예를 들어...

<syntaxhighlight lang='bash'>
kind load docker-image gcr.io/k8s-staging-cluster-api/cluster-api-controller-amd64:dev
kind load docker-image gcr.io/k8s-staging-cluster-api/kubeadm-bootstrap-controller-amd64:dev
kind load docker-image gcr.io/k8s-staging-cluster-api/kubeadm-control-plane-controller-amd64:dev
kind load docker-image gcr.io/k8s-staging-cluster-api/capd-manager-amd64:dev
</syntaxhighlight>

관리 클러스터의 kubelet에 컨트롤러 이미지를 사용할 수 있도록 합니다.

kind 클러스터가 준비되고 필요한 모든 이미지가 준비되면 create-local-repository.py 스크립트에서 생성된 clusterctl init 명령어를 실행합니다.

필요시, 구성요소가 제대로 실행되고 있는지 확인할 수도 있습니다. 정확한 구성요소는 초기화한 제공자에 따라 다릅니다. 다음은 Docker 제공자가 설치되는 출력 예시입니다.

<syntaxhighlight lang='console'>
kubectl get deploy -A | grep  "cap\|cert"
capd-system
</syntaxhighlight>
<syntaxhighlight lang='console'>
capd-controller-manager                         1/1     1            1           25m
capi-kubeadm-bootstrap-system       capi-kubeadm-bootstrap-controller-manager       1/1     1            1           25m
capi-kubeadm-control-plane-system   capi-kubeadm-control-plane-controller-manager   1/1     1            1           25m
capi-system                         capi-controller-manager                         1/1     1            1           25m
cert-manager                        cert-manager                                    1/1     1            1           27m
cert-manager                        cert-manager-cainjector                         1/1     1            1           27m
cert-manager                        cert-manager-webhook                            1/1     1            1           27m
</syntaxhighlight>

==Docker 제공자에 대한 추가 참고사항==
===적절한 Kubernetes 버전 선택===
<code>--kubernetes-version</code>을 선택할 때 <code>kindest/node</code> 이미지를 사용할 수 있는지 확인하세요.

예를 들어, [https://hub.docker.com/r/kindest/node/tags docker hub]에 <code>vX.Y.Z</code> 버전에 대한 이미지가 없다고 가정하면, <code>--kubernetes-version=vX.Y.Z</code>를 사용한 CAPD 워크로드 클러스터 생성은 실패합니다. 자세한 내용은 [https://github.com/kubernetes-sigs/cluster-api/issues/3795 이슈 3795번]을 참조하세요.

===Docker Desktop을 사용할 때 워크로드 클러스터에 대한 kubeconfig 얻기===
macOS, Linux 또는 Windows의 Docker Desktop의 경우 kind를 사용하여 kubeconfig를 조회합니다.

<syntaxhighlight lang='bash'>
kind get kubeconfig --name capi-quickstart > capi-quickstart.kubeconfig
</syntaxhighlight>

Linux용 Docker 엔진은 기본 clusterctl 접근방식으로 작동합니다.

<syntaxhighlight lang='bash'>
clusterctl get kubeconfig capi-quickstart > capi-quickstart.kubeconfig
</syntaxhighlight>

===Docker Desktop와 clusterctl을 사용할 때 kubeconfig 고치기===
macOS 또는 Windows의 Docker 데스크톱 또는 Linux의 Docker 데스크톱(Docker 엔진은 잘 작동함)에서 <code>clusterctl</code>을 사용하여 kubeconfig를 검색할 때 Docker 제공자로 생성된 워크로드 클러스터에 대한 kubeconfig를 가져오려면 몇 가지 추가 단계를 수행해야 합니다.

<syntaxhighlight lang='bash'>
clusterctl get kubeconfig capi-quickstart > capi-quickstart.kubeconfig
</syntaxhighlight>

kubeconfig를 고치려면 다음을 실행하세요.

<syntaxhighlight lang='bash'>
# 액세스할 수 없는 컨테이너 IP 대신, 로드 밸런서의 노출된 포트를 kubeconfig에 지정합니다.
sed -i -e "s/server:.*/server: https:\/\/$(docker port capi-quickstart-lb 6443/tcp | sed "s/0.0.0.0/127.0.0.1/")/g" ./capi-quickstart.kubeconfig
</syntaxhighlight>

==참고==
* https://cluster-api.sigs.k8s.io/clusterctl/developers

[[분류: cluster-api]]
[[분류: clusterctl]]