Cluster API 퀵스타트 편집하기

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

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

;경고
아직 v1beta1 또는 v1alpha4를 지원하지 않는 [https://cluster-api.sigs.k8s.io/reference/providers 제공자]를 사용하는 경우, 대신 [https://release-0-3.cluster-api.sigs.k8s.io/user/quick-start 릴리스 0.3] 또는 [https://release-0-4.cluster-api.sigs.k8s.io/user/quick-start 릴리스 0.4] 퀵스타트 지침을 따르세요.

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

이 글에서는 <code>clusterctl</code> CLI 도구를 사용하여 클러스터 API [[Cluster API 용어집#관리 클러스터|관리 클러스터]]의 수명주기를 처리하는 경로를 설명합니다.

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

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

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

===공통 전제조건===
* 로컬 환경에 [[kubectl 설치]] 및 셋업
* [[kind]]와 [[Docker 설치]]
* [[Helm 설치]]

===설치 및 Kubernetes 클러스터 설정===
====Kind 클러스터 생성====
====Calico CNI 설치====
===clusterctl 설치===
;리눅스

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

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

AMD64용 다운로드:

<syntaxhighlight lang='bash'>
curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.7.1/clusterctl-linux-amd64 -o clusterctl
</syntaxhighlight>

ARM64용 다운로드:

<syntaxhighlight lang='bash'>
curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.7.1/clusterctl-linux-arm64 -o clusterctl
</syntaxhighlight>

PPC64LE용 다운로드:

<syntaxhighlight lang='bash'>
curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.7.1/clusterctl-linux-ppc64le -o clusterctl
</syntaxhighlight>

clusterctl 설치:

<syntaxhighlight lang='bash'>
sudo install -o root -g root -m 0755 clusterctl /usr/local/bin/clusterctl
</syntaxhighlight>

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

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

;맥OS

;homebrew

;윈도우

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

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

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

<syntaxhighlight lang='bash'>
export CLUSTER_TOPOLOGY=true
</syntaxhighlight>

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

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

;Akamai (Linode)

<syntaxhighlight lang='bash'>
export LINODE_TOKEN=<your-access-token>

# 관리 클러스터 초기화
clusterctl init --infrastructure linode-linode
</syntaxhighlight>

;AWS

;Azure

;CloudStack

;DigitalOcean

;Docker

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

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

<syntaxhighlight lang='bash'>
# 실험적 클러스터 토폴로지 기능 활성화
export CLUSTER_TOPOLOGY=true

# 관리 클러스터 초기화
clusterctl init --infrastructure docker
</syntaxhighlight>

;Equinix Metal

;GCP

;Hetzner

;Hivelocity

;IBM Cloud

;K0smotron

;KubeKey

;KubeVirt

;Metal3

;Nutanix

;OCI

;OpenStack

<syntaxhighlight lang='bash'>
# 관리 클러스터 초기화
clusterctl init --infrastructure openstack
</syntaxhighlight>

;Outscale

;Proxmox

;VCD

;vcluster

<syntaxhighlight lang='bash'>
clusterctl init --infrastructure vcluster
</syntaxhighlight>

[https://github.com/loft-sh/cluster-api-provider-vcluster/blob/main/docs/quick-start.md vcluster용 클러스터 API 공급자 퀵스타트 가이드]를 따르세요.

;Virtink

;vSphere

<syntaxhighlight lang='console'>
# 원격 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
</syntaxhighlight>

vSphere에 관한 전제조건, 자격증명 관리, 권한에 대한 자세한 내용은, [https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/blob/master/docs/getting_started.md  vSphere 프로젝트]를 참조하세요.
----

<code>clusterctl init</code>의 출력결과는 아래와 비슷할 겁니다.
<syntaxhighlight lang='console'>
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 -
</syntaxhighlight>

;환경변수의 대안

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

자세한 내용은 <code>[[clusterctl init]]</code>을 참조하세요.

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

====워크로드 클러스터 설정 준비하기====
<code>clusterctl generate cluster</code> 명령어는 [[Cluster API 용어집#워크로드 클러스터|워크로드 클러스터]]를 생성하기 위한 YAML 템플릿을 반환합니다.

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

;내 클러스터에 어떤 토폴로지가 사용됩니까?
<code>clusterctl generate cluster</code> 명령어는 기본적으로 인프라 제공자가 제공하는 클러스터 템플릿을 사용합니다. 자세한 내용은 제공자의 문서를 참조하세요.

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

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

그렇지 않은 경우, 클러스터 템플릿에 필요한 변수 목록을 검색하는 방법에 대한 자세한 내용은 <code>clusterctl generate cluster</code> [https://cluster-api.sigs.k8s.io/clusterctl/commands/generate-cluster 명령어] 문서를 참조하세요.

;Docker

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

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

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

<syntaxhighlight lang='bash'>
# 서비스 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"
</syntaxhighlight>

기본적으로 활성화된 [https://cluster-api.sigs.k8s.io/security/pod-security-standards 파드 보안 표준]을 비활성화하는 것도 가능하지만 권장되지 않습니다.

<syntaxhighlight lang='bash'>
export POD_SECURITY_STANDARD_ENABLED="false"
</syntaxhighlight>

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

;Docker

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

<syntaxhighlight lang='bash'>
clusterctl generate cluster capi-quickstart --flavor development \
  --kubernetes-version v1.29.2 \
  --control-plane-machine-count=3 \
  --worker-machine-count=3 \
  > capi-quickstart.yaml
</syntaxhighlight>

;vcluster
;KubeVirt
;Other providers...

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

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

자세한 내용은 [https://cluster-api.sigs.k8s.io/clusterctl/commands/generate-cluster clusterctl generate cluster]를 참조하세요.

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

<syntaxhighlight lang='bash'>
kubectl apply -f capi-quickstart.yaml
</syntaxhighlight>

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

<syntaxhighlight lang='console'>
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
</syntaxhighlight>

====워크로드 클러스터 접근하기====
이제 클러스터가 프로비저닝을 시작합니다. 다음을 통해 상태를 확인할 수 있습니다.
<syntaxhighlight lang='bash'>
kubectl get cluster
</syntaxhighlight>

다음을 실행하여 클러스터와 해당 리소스를 "한 눈에" 볼 수도 있습니다.
<syntaxhighlight lang='bash'>
clusterctl describe cluster capi-quickstart
</syntaxhighlight>

아래와 비슷한 출력결과가 표시될 것입니다.
<syntaxhighlight lang='console'>
NAME              PHASE         AGE   VERSION
capi-quickstart   Provisioned   8s    v1.29.2
</syntaxhighlight>

첫번째 컨트롤 플레인이 작동하는지 확인합니다.
<syntaxhighlight lang='bash'>
kubectl get kubeadmcontrolplane
</syntaxhighlight>

아래와 비슷한 출력결과가 표시될 것입니다.
<syntaxhighlight lang='console'>
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
</syntaxhighlight>

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

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

;기본값

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

;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.

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

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.

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

;Azure

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

<syntaxhighlight lang='bash'>
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"
</syntaxhighlight>

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

;OpenStack

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

<syntaxhighlight lang='bash'>
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
</syntaxhighlight>

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

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

<syntaxhighlight lang='bash'>
kubectl -n kube-system create secret generic cloud-config --from-file=cloud.conf
</syntaxhighlight>

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

<syntaxhighlight lang='bash'>
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
</syntaxhighlight>

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

===CNI 솔루션 배포===
여기서는 Calico를 예시로 사용했습니다.

;Azure

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

<syntaxhighlight lang='bash'>
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
</syntaxhighlight>

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

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

;vcluster

;KubeVirt

;다른 제공자...

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

==참고==
* https://cluster-api.sigs.k8s.io/user/quick-start

[[분류: cluster-api]]