개발자를 위한 clusterctl

1 개요

clusterctl for Developers
개발자를 위한 clusterctl

이 문서에서는 개발 작업흐름 중에 clusterctl을 사용하는 방법을 설명합니다.

2 전제조건

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

3 clusterctl 빌드

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

make clusterctl

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

4 로컬 아티팩트 사용

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

그렇게 하는 데에는 두 가지 옵션이 있습니다.

게시된 단일 아티팩트를 로컬 아티팩트로 오버라이드하려는 경우, 오버라이드 레이어를 사용하세요.
게시된 아티팩트를 사용하지 않고 대신 로컬 아티팩트를 사용하려면, 로컬 리포지토리를 생성하세요.

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

4.1 로컬에서 아키팩트 빌드

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

make docker-build REGISTRY=gcr.io/k8s-staging-cluster-api PULL_POLICY=IfNotPresent

4.2 clusterctl-settings.json 파일 생성

다음으로, clusterctl-settings.json 파일을 생성하여 Cluster API의 로컬 클론에 둡니다. 이 파일은 create-local-repository.py에서 사용됩니다. 예시는 다음과 같습니다.

{
  "providers": ["cluster-api","bootstrap-kubeadm","control-plane-kubeadm", "infrastructure-aws", "infrastructure-docker"],
  "provider_repos": ["../cluster-api-provider-aws"]
}

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

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

4.3 로컬 리포지토리 생성

4.3.1 사용가능한 제공자

현재 스크립트에는 다음 제공자가 정의되어 있습니다.

cluster-api
bootstrap-kubeadm
control-plane-kubeadm
infrastructure-docker

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

{
  "name": "infrastructure-aws",
  "config": {
    "componentsFile": "infrastructure-components.yaml",
    "nextVersion": "v0.5.0"
  }
}

5 kind 관리 클러스터 생성

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

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

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

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

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

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

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

kubectl get deploy -A | grep  "cap\|cert"
capd-system

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

6 Docker 제공자에 대한 추가 참고사항

6.1 적절한 Kubernetes 버전 선택

--kubernetes-version을 선택할 때 kindest/node 이미지를 사용할 수 있는지 확인하세요.

예를 들어, docker hub에 vX.Y.Z 버전에 대한 이미지가 없다고 가정하면, --kubernetes-version=vX.Y.Z를 사용한 CAPD 워크로드 클러스터 생성은 실패합니다. 자세한 내용은 이슈 3795번을 참조하세요.

6.2 Docker Desktop을 사용할 때 워크로드 클러스터에 대한 kubeconfig 얻기

macOS, Linux 또는 Windows의 Docker Desktop의 경우 kind를 사용하여 kubeconfig를 조회합니다.

kind get kubeconfig --name capi-quickstart > capi-quickstart.kubeconfig

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

clusterctl get kubeconfig capi-quickstart > capi-quickstart.kubeconfig

6.3 Docker Desktop와 clusterctl을 사용할 때 kubeconfig 고치기

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

clusterctl get kubeconfig capi-quickstart > capi-quickstart.kubeconfig

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

# 액세스할 수 없는 컨테이너 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

7 참고

https://cluster-api.sigs.k8s.io/clusterctl/developers