Tilt를 사용한 클러스터 API 개발

1 개요

Developing Cluster API with Tilt

Tilt를 사용한 클러스터 API 개발

이 문서에서는 간편한 배포와 빠른 반복 빌드를 제공하는 단순화된 워크플로우를 위해 kind와 Tilt를 사용하는 방법을 설명합니다 .

2 전제조건

1. Docker: v19.03 이상
2. kind: v0.22.0 이상
3. Tilt: v0.30.8 이상
4. kustomize: make kustomize를 통해 제공
5. envsubst: make envsubst를 통해 제공
6. helm: v3.7.1 이상
7. Cluster API 저장소를 로컬로 클론
8. 로컬로 배포하려는 제공자도 클론

3 시작하기

3.1 kind 클러스터 생성

로컬 Docker 레지스트리와 함께 KIND 클러스터를 생성하는 스크립트 및 CAPD를 실행하기 위한 올바른 마운트가 hack/ 폴더에 포함되어 있습니다.

사전설정된 클러스터를 생성하려면 다음을 실행하세요:

./hack/kind-install-for-capd.sh

다음을 사용하여 클러스터의 상태를 확인할 수 있습니다:

kubectl cluster-info --context kind-capi-test

3.2 tilt-settings 파일 생성

3.2.1 tilt-settings 필드

디버거 연결

Visual Studio

위의 예제를 사용할 때, 다음 시작 설정을 사용하여 Visual Studio Code에서 core CAPI controller를 디버깅할 수 있습니다.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Core CAPI Controller",
      "type": "go",
      "request": "attach",
      "mode": "remote",
      "remotePath": "",
      "port": 30000,
      "host": "127.0.0.1",
      "showLog": true,
      "trace": "log",
      "logOutput": "rpc"
    }
  ]
}

Goland / IntelliJ

위의 예시를 활용하면 포트 30000을 가리키는 Go Remote 실행/디버그 설정을 설정할 수 있습니다.

3.3 kind 클러스터 생성하고 Tilt 실행!

사전설정된 kind 클러스터를 생성하고(아직 수행하지 않은 경우) 개발 환경을 시작하려면 다음을 실행합니다.

make tilt-up

그러면 명령줄 HUD와 웹 브라우저 인터페이스가 열립니다. 어느 위치에서나 Tilt의 상태를 모니터링할 수 있습니다. 잠시 후에 개발환경이 실행되고 이제 클러스터를 생성할 수 있습니다. 사용가능한 워커 클러스터 설정 예시가 있습니다. 이는 특정 요구에 맞게 커스터마이징할 수 있습니다.

3.4 워크로드 클러스터 배포

kind 관리 클러스터가 Tilt로 실행되고 나면, tilt-settings.yaml 파일(기본값 ./test/infrastructure/docker/templates)의 template_dirs 필드에 지정된 디렉토리의 YAML 템플릿을 기반으로 Tilt 웹 UI에 워크로드 클러스터를 배포할 수 있습니다.

템플릿 이름은 clusterctl 컨벤션에 따라 지정되어야 합니다:

• 템플릿 파일의 이름은 cluster-template-{name}.yaml로 지정되어야 합니다. 해당 파일은 레이블 그룹 {provider-label}.templates (예: CAPD.templates) 아래의 Tilt 웹UI에서 액세스할 수 있습니다.
• 클러스터 클래스 파일의 이름은 clusterclass-{name}.yaml로 지정되어야 합니다. 해당 파일은 레이블 그룹 {provider-label}.clusterclasses (예: CAPD.clusterclasses) 아래의 Tilt 웹UI에서 액세스할 수 있습니다.

Tilt 웹UI 버튼 세트에서 해당 항목 중 하나를 선택하면, 변수 대체를 커스터마이징하기 위한 드롭다운을 사용하여 클러스터를 생성하거나, 클러스터를 삭제할 수 있습니다. 변수 대체에 대한 커스텀 값은 tilt-settings.yaml의 kustomize_substitutions를 사용하여 설정할 수 있습니다. 예시:

kustomize_substitutions:
  NAMESPACE: "default"
  KUBERNETES_VERSION: "v1.29.2"
  CONTROL_PLANE_MACHINE_COUNT: "1"
  WORKER_MACHINE_COUNT: "3"
# 참고: kustomize 대체에서는 값이 문자열일 것으로 기대합니다. 값을 따옴표로 묶으면 문자열이 됩니다.

3.5 kind 클러스터와 개발환경 정리

Tilt를 중지한 후, 다음을 실행하여 kind 클러스터 및 개발환경을 정리할 수 있습니다.

make clean-kind

자동생성된 모든 파일을 제거하려면, 다음을 실행하세요.

make clean

tilt-settings.yaml에서 deploy_observability을 사용하여 배포된 차트의 새 버전을 가져오려면, make clean 또는 make clean-charts를 실행해야 합니다.

4 clusterctl 사용

tilt로 워커 클러스터를 생성한 경우, clusterctl을 관리 작업에 사용해서는 안됩니다. 이는 tilt는 clusterctl init처럼 관리 클러스터에서 제공자를 초기화하지 않기 때문에, clusterctl config와 같은 일부 clusterctl 명령어가 작동하지 않기 때문입니다.

이러한 한계점은 컨트롤러 로직에 대한 빠른 개발-테스트 반복을 실행하는 동안 수용가능한 절충안입니다. 대신 clusterctl 테스트 워크플로우에 관심이 있다면, clusterctl 개발자 지침을 참조해야 합니다.

5 사용가능 제공자

현재 Tiltfile에 정의된 제공자는 다음과 같습니다:

• core: cluster-api 자체
• kubeadm-bootstrap: kubeadm 부트스트랩 제공자
• kubeadm-control-plane: kubeadm 컨트롤플레인 제공자
• docker: Docker 인프라스트럭처 제공자
• in-memory: In-memory 인프라스트럭처 제공자
• test-extension: CAPI E2E 테스트에서 사용하는 런타임 확장기능

다음 문단에 설명된 절차에 따라 제공자를 추가할 수 있습니다.

5.1 tilt-provider 설정

제공자는 빌드 방법을 설명하는 tilt-provider.yaml 파일을 제공해야 합니다. 예시는 다음과 같습니다.

name: aws
config:
  image: "gcr.io/k8s-staging-cluster-api-aws/cluster-api-aws-controller"
  live_reload_deps: ["main.go", "go.mod", "go.sum", "api", "cmd", "controllers", "pkg"]
  label: CAPA

JSON을 선호한다면, 대신 tilt-provider.json 파일을 생성할 수 있습니다. 두 파일이 다 있는 경우 YAML이 선호됩니다.

5.1.1 설정 필드

image: kustomize 파일에서 참조되는 이 제공자의 이미지. 이는 매치되어야 하며, 안되면 Tilt는 빌드를 하지 않습니다.

live_reload_deps: 감시할 파일/디렉토리 목록. 하나라도 변경되면, Tilt는 제공자에 대한 매니저 바이너리를 재빌드하고 구동 중인 컨테이너의 실시간 업데이트를 수행합니다.

version: 제공자 CR에 사용할 버전을 정의할 수 있습니다. 비어 있으면 기본 버전이 사용됩니다.

additional_docker_helper_commands (String, default=””): 헬퍼 이미지 docker 빌드에서 실행할 추가 명령어. 예시:

RUN wget -qO- https://dl.k8s.io/v1.21.2/kubernetes-client-linux-amd64.tar.gz | tar xvz
RUN wget -qO- https://get.docker.com | sh

additional_docker_build_commands (String, default=””): dockerfile에 추가할 추가 명령어. 매니저 이미지는 docker-slim을 사용하므로 파일을 다운로드하려면, additional_helper_image_commands를 사용하십시오. 예시:

COPY --from=tilt-helper /usr/bin/docker /usr/bin/docker
COPY --from=tilt-helper /go/kubernetes/client/bin/kubectl /usr/bin/kubectl

kustomize_folder (String, default=config/default): 제공자의 kustomize 파일이 정의된 폴더. 경로는 제공자 루트 폴더에 대해 상대적입니다.

kustomize_options ([]String, default=[]): 제공자에 대한 yaml 매니페스트를 생성하기 위해 kustomize를 실행할 때 적용할 옵션. 예시: "kustomize_options": [ "--load-restrictor=LoadRestrictionsNone" ]

apply_provider_yaml (Bool, default=true): 제공자 yaml을 적용할지 여부. 제공자에 ./config 폴더가 없거나 클러스터에 적용하지 않으려면 false로 설정하십시오.

go_main (String, default=”main.go”): go main 파일이 폴더의 루트에 있지 않은 경우

label (String, default=provider name): 버전 v0.22.2 이상, 틸트 UI에서 제공자 컴포넌트를 그룹화하는 데 사용되는 레이블(https://blog.tilt.dev/2021/08/09/resource-grouping.html 참조); 관례적으로 제공자 약어를 사용해야 합니다(CAPD, KCP 등).

additional_resources ([]string, default=[]): tilt 클러스터에 로드될 yaml 파일의 경로 목록. 예를 들어 RuntimeExtension 제공자에 대한 ExtensionConfig 객체를 배포하기 위해 이를 사용합니다.

resource_deps ([]string, default=[]): 현재 제공자 전에 설치될 tilt 리소스 이름 목록. 예를 들어 이 제공자가 클러스터 API 이후에 설치되도록 하려면, 이를 [“capi_controller”]로 지정합니다.

6 Tilt 커스터마이징

Tilt의 동작을 커스터마이징해야 하는 경우, cluster-api의 tilt.d 디렉토리에 파일을 만들 수 있습니다. 이 파일은 git에서 무시되므로 여기에 배치한 모든 파일은 소스 제어에 체크인되지 않습니다.

이러한 파일은 제공자 맵이 정의된 후와 모든 헬퍼 함수 정의 뒤에 포함됩니다. 이는 "실제 작업"이 일어나기 직전입니다.

10 Tilt 트러블슈팅

10.3 레지스트리 pull/push 오류

10.3.1 connection refused / denied / not found

default_registry 필드가 이미지를 가져오고 푸시할 수 있는 유효한 레지스트리인지 확인하십시오 .

10.3.2 server gave HTTP response to HTTPS client

기본적으로 localhost:5000을 제외한 모든 레지스트리는 HTTPS를 통해 액세스됩니다.

HTTP 레지스트리를 실행하는 경우 docker/podman에서 레지스트리를 설정해야 할 수도 있습니다.

예를 들어, podman에서는 localhost:5001 레지스트리 설정을 다음 내용으로 /etc/containers/registries.conf.d 내에 선언해야 합니다.

[[registry]]
location = "localhost:5001"
insecure = true

주의: macOS에서는 이 설정을, podman machine ssh <machine>를 실행하여, podman 머신 내에서 수행해야 합니다.

10.4 Errors loading images in kind

다음을 실행하여 kind에 이미지를 수동으로 로드할 수 있습니다.

kind load docker-image --name=<kind_cluster> <image>

10.4.1 image: "..." not present locally

Podman을 구동 중인 경우, 다음 버그가 있을 수 있습니다: https://github.com/kubernetes-sigs/kind/issues/2760

워크어라운드는 podman 실행파일에 대한 docker 심링크를 만들고 이미지를 다시 로드하는 것입니다.

11 참고

• https://cluster-api.sigs.k8s.io/developer/tilt