위키
포럼
도구
바뀐글
랜덤

Cluster API 퀵스타트

1 개요[ | ]

Quick Start
퀵스타트

이 튜토리얼에서는 Cluster API를 사용하여 하나 이상의 Kubernetes 클러스터를 생성하는 방법에 대한 기본사항을 다룹니다.

경고

아직 v1beta1 또는 v1alpha4를 지원하지 않는 제공자를 사용하는 경우, 대신 릴리스 0.3 또는 릴리스 0.4 퀵스타트 지침을 따르세요.

2 설치[ | ]

두 가지 주요 퀵스타트 경로가 있습니다: clusterctl 또는 Cluster API Operator 사용.

이 글에서는 clusterctl CLI 도구를 사용하여 클러스터 API 관리 클러스터의 수명주기를 처리하는 경로를 설명합니다.

clusterctl 명령줄 인터페이스는 간단한 "1일차 경험"과 Cluster API를 통한 빠른 시작을 제공하기 위해 특별히 설계되었습니다. 제공자 구성요소를 정의하는 YAML 파일을 가져오고 설치하는 작업을 자동화합니다.

추가적으로 사용자가 잘못 설정하는 것을 방지하거나 업그레이드와 같은 2일차 작업을 관리하는 데 도움이 되는 제공자 관리에 대한 일련의 모범사례를 나타냅니다.

Cluster API Operator는 clusterctl을 기반으로 구축된 Kubernetes Operator이며 클러스터 관리자가 선언적 접근방식을 사용하여 관리 클러스터 내에서 Cluster API 제공자의 수명주기를 처리할 수 있도록 설계되었습니다. Cluster API 배포 및 관리에 대한 사용자 경험을 개선하여 GitOps를 통해 일상적인 작업을 더 쉽게 처리하고 워크플로우를 자동화하는 것을 목표로 합니다. 이 도구를 실험해 보려면, CAPI Operator 퀵스타트을 보세요.

2.1 공통 전제조건[ | ]

2.2 설치 및 Kubernetes 클러스터 설정[ | ]

2.2.1 Kind 클러스터 생성[ | ]

2.2.2 Calico CNI 설치[ | ]

2.3 clusterctl 설치[ | ]

리눅스

리눅스에서 curl을 사용하여 clusterctl 바이너리 설치

확실하지 않은 경우 uname -a를 실행하여 컴퓨터 아키텍처를 확인할 수 있습니다.

AMD64용 다운로드: 

curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.7.1/clusterctl-linux-amd64 -o clusterctl

ARM64용 다운로드: 

curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.7.1/clusterctl-linux-arm64 -o clusterctl

PPC64LE용 다운로드: 

curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.7.1/clusterctl-linux-ppc64le -o clusterctl

clusterctl 설치: 

sudo install -o root -g root -m 0755 clusterctl /usr/local/bin/clusterctl

설치한 버전이 최신인지 확인: 

clusterctl version
맥OS
homebrew
윈도우

2.4 관리 클러스터 초기화[ | ]

이제 clusterctl이 설치되고 모든 필수 구성요소가 준비되었으므로, clusterctl init를 사용하여 Kubernetes 클러스터를 관리 클러스터로 변환해 보겠습니다.

이 명령어는 설치할 제공자 목록을 입력으로 받아들입니다. 처음 실행될 때, clusterctl init는 자동으로 cluster-api 코어 제공자 목록에 추가하고, 따로 지정하지 않은 경우 kubeadm 부트스트랩과 kubeadm 컨트롤 플레인 제공자도 추가합니다.

2.4.1 기능 게이트 활성화하기[ | ]

clusterctl init를 실행하기 전에 환경변수를 export하여 기능 게이트를 활성화할 수 있습니다. 예를 들어, 관리형 토폴로지 및 ClusterClass에 대한 지원을 활성화하는 데 필요한 ClusterTopology 기능은 다음을 통해 활성화할 수 있습니다. 

export CLUSTER_TOPOLOGY=true

실험적 기능에 대한 추가 문서는 실험적 기능에서 찾을 수 있습니다.

2.4.2 일반 제공자를 위한 초기화[ | ]

사용하려는 인프라 제공자에 따라, Cluster API를 시작하기 전에, 몇 가지 추가 전제조건을 충족해야 합니다. 일반 제공자에 대해 기대되는 설정은 아래를 참조하세요.

Akamai (Linode)
export LINODE_TOKEN=<your-access-token>

# 관리 클러스터 초기화
clusterctl init --infrastructure linode-linode
AWS
Azure
CloudStack
DigitalOcean
Docker

경고: Docker 제공자는 프로덕션용으로 설계되지 않았으며 개발 환경 전용입니다.

Docker 제공자는 ClusterClass 기반 클러스터를 배포하기 위해 ClusterTopology와 MachinePool 기능이 필요합니다. ClusterClass를 사용하면 Kubernetes 버전에 따라 설정을 조정할 수 있으므로 이 퀵스타트에서는 ClusterClass 기반 클러스터 템플릿만 지원합니다. 이는, Kubernetes 버전에 따라 다른 cgroupDriver를 사용해야 하므로, v1.24 미만의 Kubernetes 클러스터를 설치하고 v1.23에서 v1.24로 업그레이드하는 데에 필요합니다. 

# 실험적 클러스터 토폴로지 기능 활성화
export CLUSTER_TOPOLOGY=true

# 관리 클러스터 초기화
clusterctl init --infrastructure docker
Equinix Metal
GCP
Hetzner
Hivelocity
IBM Cloud
K0smotron
KubeKey
KubeVirt
Metal3
Nutanix
OCI
OpenStack
# 관리 클러스터 초기화
clusterctl init --infrastructure openstack
Outscale
Proxmox
VCD
vcluster
clusterctl init --infrastructure vcluster

vcluster용 클러스터 API 공급자 퀵스타트 가이드를 따르세요.

Virtink
vSphere
# 원격 vSphere 엔드포인트 접근에 사용되는 사용자명
export VSPHERE_USERNAME="vi-admin@vsphere.local"
# 원격 vSphere 엔드포인트 접근에 사용되는 패스워드
# bash history에 패스워드를 남기지 않으려면,
# 이것을 `$XDG_CONFIG_HOME/cluster-api/clusterctl.yaml`에 세팅할 수도 있다.
export VSPHERE_PASSWORD="admin!23"

# 마지막으로, 관리 클러스터 초기화
clusterctl init --infrastructure vsphere

vSphere에 관한 전제조건, 자격증명 관리, 권한에 대한 자세한 내용은, vSphere 프로젝트를 참조하세요.

clusterctl init의 출력결과는 아래와 비슷할 겁니다. 

Fetching providers
Installing cert-manager Version="v1.11.0"
Waiting for cert-manager to be available...
Installing Provider="cluster-api" Version="v1.0.0" TargetNamespace="capi-system"
Installing Provider="bootstrap-kubeadm" Version="v1.0.0" TargetNamespace="capi-kubeadm-bootstrap-system"
Installing Provider="control-plane-kubeadm" Version="v1.0.0" TargetNamespace="capi-kubeadm-control-plane-system"
Installing Provider="infrastructure-docker" Version="v1.0.0" TargetNamespace="capd-system"

Your management cluster has been initialized successfully!

You can now create your first workload cluster by running the following:

  clusterctl generate cluster [name] --kubernetes-version [version] | kubectl apply -f -
환경변수의 대안

이 퀵스타트 가이드 전체에서 환경변수를 사용하여 파라미터를 세팅하는 방법에 대한 지침을 제공했습니다. 가이드의 나머지 부분에 나오는 대부분의 환경변수는 $XDG_CONFIG_HOME/cluster-api/clusterctl.yaml에 세팅할 수도 있습니다.

자세한 내용은 clusterctl init을 참조하세요.

2.5 첫번째 워크로드 클러스터 생성[ | ]

관리 클러스터가 준비되면 첫번째 워크로드 클러스터를 생성할 수 있습니다.

2.5.1 워크로드 클러스터 설정 준비하기[ | ]

clusterctl generate cluster 명령어는 워크로드 클러스터를 생성하기 위한 YAML 템플릿을 반환합니다.

내 클러스터에 어느 제공자가 사용됩니까?

clusterctl generate cluster 명령어는 사용자 경험을 단순화하기 위해 스마트한 기본값을 사용합니다. 예를 들어, aws 인프라 제공자만 배포된 경우, 클러스터를 생성할 때 이를 감지하여 사용합니다.

내 클러스터에 어떤 토폴로지가 사용됩니까?

clusterctl generate cluster 명령어는 기본적으로 인프라 제공자가 제공하는 클러스터 템플릿을 사용합니다. 자세한 내용은 제공자의 문서를 참조하세요.

클러스터 템플릿 대신 다른 대안 소스를 사용하는 방법에 대한 자세한 내용은 clusterctl generate cluster 명령어 설명서를 참조하세요.

2.5.2 일반 제공자를 위한 필요 설정[ | ]

사용하려는 인프라 제공자에 따라, Cluster API로 클러스터를 설정하기 전에 몇 가지 추가 전제조건을 충족해야 합니다. 아래에는 일반 제공자에 대한 지침이 제공됩니다.

그렇지 않은 경우, 클러스터 템플릿에 필요한 변수 목록을 검색하는 방법에 대한 자세한 내용은 clusterctl generate cluster 명령어 문서를 참조하세요.

Docker

경고: Docker 제공자는 프로덕션용으로 설계되지 않았으며 개발 환경 전용입니다.

Docker 제공자는 클러스터 템플릿에 대한 추가 설정이 필요하지 않습니다.

그러나, 특별한 네트워크 세팅이 필요한 경우 다음 환경변수를 세팅할 수 있습니다. 

# 서비스 CIDR 목록, 기본값 ["10.128.0.0/12"]
export SERVICE_CIDR=["10.96.0.0/12"]

# 파드 CIDR 목록, 기본값 ["192.168.0.0/16"]
export POD_CIDR=["192.168.0.0/16"]

# 서비스 도메인, 기본값 "cluster.local"
export SERVICE_DOMAIN="k8s.test"

기본적으로 활성화된 파드 보안 표준을 비활성화하는 것도 가능하지만 권장되지 않습니다. 

export POD_SECURITY_STANDARD_ENABLED="false"

2.5.3 클러스터 설정 생성[ | ]

이 튜토리얼에서는, 클러스터 이름을 capi-quickstart로 하겠습니다.

Docker

경고: Docker 제공자는 프로덕션용으로 설계되지 않았으며 개발 환경 전용입니다. 

clusterctl generate cluster capi-quickstart --flavor development \
  --kubernetes-version v1.29.2 \
  --control-plane-machine-count=3 \
  --worker-machine-count=3 \
  > capi-quickstart.yaml
vcluster
KubeVirt
Other providers...

그러면 사전정의된 Cluster API 객체(Cluster, Machine, MachineDeployment 등) 목록이 포함된 capi-quickstart.yaml이라는 YAML 파일이 생성됩니다.

선택한 편집기를 사용하여 파일을 수정할 수 있습니다.

자세한 내용은 clusterctl generate cluster를 참조하세요.

2.5.4 워크로드 클러스터 적용[ | ]

준비가 되면, 다음 명령어를 실행하여 클러스터 매니페스트를 적용합니다. 

kubectl apply -f capi-quickstart.yaml

출력결과는 아래와 비슷할 것입니다. 

cluster.cluster.x-k8s.io/capi-quickstart created
dockercluster.infrastructure.cluster.x-k8s.io/capi-quickstart created
kubeadmcontrolplane.controlplane.cluster.x-k8s.io/capi-quickstart-control-plane created
dockermachinetemplate.infrastructure.cluster.x-k8s.io/capi-quickstart-control-plane created
machinedeployment.cluster.x-k8s.io/capi-quickstart-md-0 created
dockermachinetemplate.infrastructure.cluster.x-k8s.io/capi-quickstart-md-0 created
kubeadmconfigtemplate.bootstrap.cluster.x-k8s.io/capi-quickstart-md-0 created

2.5.5 워크로드 클러스터 접근하기[ | ]

이제 클러스터가 프로비저닝을 시작합니다. 다음을 통해 상태를 확인할 수 있습니다. 

kubectl get cluster

다음을 실행하여 클러스터와 해당 리소스를 "한 눈에" 볼 수도 있습니다. 

clusterctl describe cluster capi-quickstart

아래와 비슷한 출력결과가 표시될 것입니다. 

NAME              PHASE         AGE   VERSION
capi-quickstart   Provisioned   8s    v1.29.2

첫번째 컨트롤 플레인이 작동하는지 확인합니다. 

kubectl get kubeadmcontrolplane

아래와 비슷한 출력결과가 표시될 것입니다. 

NAME                    CLUSTER           INITIALIZED   API SERVER AVAILABLE   REPLICAS   READY   UPDATED   UNAVAILABLE   AGE    VERSION
capi-quickstart-g2trk   capi-quickstart   true                                 3                  3         3             4m7s   v1.29.2

경고: 다음 단계에서 CNI를 설치할 때까지 컨트롤 플레인은 준비 상태가 되지 않습니다.

첫번째 컨트롤 플레인 노드가 실행되고 나면, [[Cluster APII 용어집#워크로드 클러스터|워크로드 클러스터] Kubeconfig를 조회할 수 있습니다.

기본값
clusterctl get kubeconfig capi-quickstart > capi-quickstart.kubeconfig
Docker

For Docker Desktop on macOS, Linux or Windows use kind to retrieve the kubeconfig. Docker Engine for Linux works with the default clusterctl approach. 

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

Note: To use the default clusterctl method to retrieve kubeconfig for a workload cluster created with the Docker provider when using Docker Desktop see Additional Notes for the Docker provider.

2.6 클라우드 제공자 설치[ | ]

Kubernetes 트리 내 클라우드 제공자 구현은 외부 클라우드 제공자를 위해 제거됩니다("트리 외부"라고도 함). 이를 위해서는 이전에 kube-controller-manager에서 구동되었던 모든 클라우드 관련 컨트롤러를 실행하는 역할을 담당하는 cloud-controller-manager라는 새로운 구성요소를 배포해야 합니다. 자세한 내용은 이 블로그 게시물을 참조하세요.

Azure

워크로드 클러스터에 공식 cloud-provider-azure 헬름 차트를 설치합니다. 

helm install --kubeconfig=./capi-quickstart.kubeconfig --repo https://raw.githubusercontent.com/kubernetes-sigs/cloud-provider-azure/master/helm/repo cloud-provider-azure --generate-name --set infra.clusterName=capi-quickstart --set cloudControllerManager.clusterCIDR="192.168.0.0/16"

자세한 내용은 CAPZ 책을 참조하세요.

OpenStack

OpenStack 외부 클라우드 제공자를 배포하기 전에, OpenStack 환경과의 통합을 위해 cloud.conf 파일을 설정하십시오. 

cat > cloud.conf <<EOF
[Global]
auth-url=<your_auth_url>
application-credential-id=<your_credential_id>
application-credential-secret=<your_credential_secret>
region=<your_region>
domain-name=<your_domain_name>
EOF

cloud.conf 파일 설성에 대한 자세한 내용은, OpenStack Cloud Controller Manager 문서를 참조하세요.

다음으로, 이 설정을 사용하여 Kubernetes Secret을 생성하여 클라우드 환경 세부정보를 안전하게 저장하세요. 예를 들어 다음을 사용하여 이 Secret을 만들 수 있습니다. 

kubectl -n kube-system create secret generic cloud-config --from-file=cloud.conf

이제, 외부 클라우드 제공자를 배포할 준비가 되었습니다! 

kubectl apply -f https://raw.githubusercontent.com/kubernetes/cloud-provider-openstack/master/manifests/controller-manager/cloud-controller-manager-roles.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes/cloud-provider-openstack/master/manifests/controller-manager/cloud-controller-manager-role-bindings.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes/cloud-provider-openstack/master/manifests/controller-manager/openstack-cloud-controller-manager-ds.yaml

다른 방법으로는, 헬름 차트를 참조하세요.

2.7 CNI 솔루션 배포[ | ]

여기서는 Calico를 예시로 사용했습니다.

Azure

워크로드 클러스터에 공식 Calico Helm 차트를 설치합니다. 

helm repo add projectcalico https://docs.tigera.io/calico/charts --kubeconfig=./capi-quickstart.kubeconfig && \
helm install calico projectcalico/tigera-operator --kubeconfig=./capi-quickstart.kubeconfig -f https://raw.githubusercontent.com/kubernetes-sigs/cluster-api-provider-azure/main/templates/addons/calico/values.yaml --namespace tigera-operator --create-namespace

잠시 후, 노드가 구동되고 준비 상태에 있어야 합니다. kubectl get node를 사용하여 상태를 확인합니다. 

kubectl --kubeconfig=./capi-quickstart.kubeconfig get nodes
vcluster
KubeVirt
다른 제공자...

2.8 클린업[ | ]

워크로드 클러스터 삭제. 

kubectl delete cluster capi-quickstart

중요: 인프라를 적절하게 클린업하려면 항상 클러스터 객체를 삭제해야 합니다. 전체 클러스터 템플릿을 kubectl delete -f capi-quickstart.yaml으로 삭제하면 보류 중(pending)인 리소스가 수동으로 클린업될 수 있습니다.

관리 클러스터 삭제 

kind delete cluster

3 다음 단계[ | ]

  • 두 번째 워크로드 클러스터를 만듭니다. 위에 설명된 단계를 따르세요. 단, 두 번째 워크로드 클러스터에는 다른 이름을 제공해야 합니다.
  • 워크로드 클러스터에 애플리케이션을 배포합니다. 포인터에 대해 CNI 배포 단계를 사용하세요 .
  • clusterctl 지원 작업에 대한 자세한 내용은 clusterctl 설명서를 참조하세요 .

4 참고[ | ]

원본 주소 "https://zetawiki.com/w/index.php?title=Cluster_API_퀵스타트&oldid=899394"
문서 댓글 ({{ doc_comments.length }})
{{ comment.name }} {{ comment.created | snstime }}