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 파일 생성

다음으로, tilt-settings.yaml 파일을 생성하고 이를 cluster-api의 로컬 복사본에 붙입니다. 다음은 CAPI 리포지토리의 컴포넌트를 사용하는 예시입니다.

default_registry: gcr.io/your-project-name-here
enable_providers:
- docker
- kubeadm-bootstrap
- kubeadm-control-plane

tilt를 사용하여 자체 리포지토리가 있는 제공자를 시작하려면, 여기서는 Cluster API Provider AWS를 사용하며, tilt-settings.yaml는 다음과 같은 형식이어야 합니다.

default_registry: gcr.io/your-project-name-here
provider_repos:
- ../cluster-api-provider-aws
enable_providers:
- aws
- kubeadm-bootstrap
- kubeadm-control-plane

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

3.2.1 tilt-settings 필드

allowed_contexts (Array, default=[]): Tilt가 사용할 수 있는 kubeconfig 컨텍스트 목록. 자세한 내용은 allow_k8s_contexts에 있는 Tilt 문서를 참조하세요.

default_registry (String, default=[]): 이미지를 push해야 하는 경우 사용할 이미지 레지스트리. 자세한 내용은 Tilt 문서를 참조하세요. 로컬 레지스트리를 사용하지 않는 경우, 이 값이 필요합니다. 또한 Cluster API Tiltfile은 실수로 gcr.io/k8s-staging-cluster-api에 push되는 것을 방지합니다.

build_engine (String, default=”docker”): The engine used to build images. Can either be docker or podman. NB: the default is dynamic and will be “podman” if the string “Podman Engine” is found in docker version (or in podman version if the command fails).

kind_cluster_name (String, default=”capi-test”): The name of the kind cluster to use when preloading images.

provider_repos (Array[]String, default=[]): A list of paths to all the providers you want to use. Each provider must have a tilt-provider.yaml or tilt-provider.json file describing how to build the provider.

enable_providers (Array[]String, default=[‘docker’]): A list of the providers to enable. See available providers for more details.

template_dirs (Map{String: Array[]String}, default={”docker”: [ “./test/infrastructure/docker/templates”]}): A map of providers to directories containing cluster templates. An example of the field is given below. See Deploying a workload cluster for how this is used.

template_dirs:
  docker:
  - ./test/infrastructure/docker/templates
  - <other-template-dir>
  azure:
  - <azure-template-dir>
  aws:
  - <aws-template-dir>
  gcp:
  - <gcp-template-dir>

kustomize_substitutions (Map{String: String}, default={}): An optional map of substitutions for ${}-style placeholders in the provider’s yaml. These substitutions are also used when deploying cluster templates. See Deploying a workload cluster.

Note: When running E2E tests locally using an existing cluster managed by Tilt, the following substitutions are required for successful tests:

kustomize_substitutions:
  CLUSTER_TOPOLOGY: "true"
  EXP_KUBEADM_BOOTSTRAP_FORMAT_IGNITION: "true"
  EXP_RUNTIME_SDK: "true"
  EXP_MACHINE_SET_PREFLIGHT_CHECKS: "true"

AWS

For example, if the yaml contains ${AWS_B64ENCODED_CREDENTIALS}, you could do the following:

kustomize_substitutions:
  AWS_B64ENCODED_CREDENTIALS: "your credentials here"

deploy_observability ([string], default=[]): If set, installs on the dev cluster one of more observability tools. Important! This feature requires the helm command to be available in the user’s path.

Supported values are:

• grafana*: To create dashboards and query loki, prometheus and tempo.
• kube-state-metrics: For exposing metrics for Kubernetes and CAPI resources to prometheus.
• loki: To receive and store logs.
• metrics-server: To enable kubectl top node/pod.
• prometheus*: For collecting metrics from Kubernetes.
• promtail: For providing pod logs to loki.
• parca*: For visualizing profiling data.
• tempo: To store traces.
• visualizer*: Visualize Cluster API resources for each cluster, provide quick access to the specs and status of any resource.

*: 참고: UI는 tilt 콘솔의 링크를 통해 액세스할 수 있습니다.

additional_kustomizations (map[string]string, default={}): 세팅된 경우 kustomize를 사용하여 빌드된 추가 리소스를 클러스터에 설치합니다. 예시:

additional_kustomizations:
  capv-metrics: ../cluster-api-provider-vsphere/config/metrics

debug (Map{string: Map} default{}): 제공자의 지명 설정 맵. key는 제공자 이름입니다.

지원하는 세팅:

• port (int, default=0 (disabled)): If set to anything other than 0, then Tilt will run the provider with delve and port forward the delve server to localhost on the specified debug port. This can then be used with IDEs such as Visual Studio Code, Goland and IntelliJ.

• continue (bool, default=true): By default, Tilt will run delve with --continue, such that any provider with debugging turned on will run normally unless specifically having a breakpoint entered. Change to false if you do not want the controller to start at all by default.

• profiler_port (int, default=0 (disabled)): If set to anything other than 0, then Tilt will enable the profiler with --profiler-address and set up a port forward. A “profiler” link will be visible in the Tilt Web UI for the controller.

• metrics_port (int, default=0 (disabled)): If set to anything other than 0, then Tilt will port forward to the default metrics port. A “metrics” link will be visible in the Tilt Web UI for the controller.

• race_detector (bool, default=false) (Linux amd64 only): If enabled, Tilt will compile the specified controller with cgo and statically compile in the system glibc and enable the race detector. Currently, this is only supported when building on Linux amd64 systems. You must install glibc-static or have libc.a available for this to work.

예시: 아래 설정 사용:

  debug:
    core:
      continue: false
      port: 30000
      profiler_port: 40000
      metrics_port: 40001

디버거 연결

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 실행/디버그 설정을 설정할 수 있습니다.

deploy_cert_manager (Boolean, default=true): 웹훅 등록에 사용하기 위해 cert-manager를 클러스터에 배포합니다.

trigger_mode (String, default=auto): 변경에 따라 tilt를 자동으로 재빌드할지 여부를 설정하는 옵션 세팅. 자동 재빌드를 비활성화하고 사용자가 UI를 통해 변경된 개별 컴포넌트의 재빌드를 트리거하도록 하려면 수동으로 설정합니다.

extra_args (Object, default={}): 이 제공자에 대해 설정된 메인 바이너리에 전달할 추가 인수에 대한 제공자 매핑. 배열의 각 항목은 지정된 제공자의 매니저에 전달됩니다.

예시:

extra_args:
  kubeadm-bootstrap:
  - --logging-format=json

이 설정을 사용하면, 각 매니저가 다음과 같이 호출됩니다.

manager --logging-format=json

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에서 무시되므로 여기에 배치한 모든 파일은 소스 제어에 체크인되지 않습니다.

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

7 수면 아래에서, “실제 작업”

높은 수준에서 Tiltfile은 다음 작업을 수행합니다.

1. tilt-settings.yaml 읽기
2. 허용되는 Kubernetes 컨텍스트 설정
3. 기본 레지스트리 설정
4. provideres 맵 정의
5. 사용자 정의 Tilt 파일 인클루드
6. cert-manager 배포
7. 제공자 활성화(core + tilt-settings.yaml에 나열된 것)
   1. 로컬에서 local_resource로 매니저 바이너리 빌드
   2. 제공자에 대해 docker_build 호출
   3. 제공자의 config/ 디렉토리에 대해 kustomize 호출

7.1 라이브 업데이트

제공자 맵의 각 제공자에는 live_reload_deps 목록이 있습니다. 이는 Tilt가 변경사항을 모니터링해야 하는 파일 및/또는 디렉토리를 정의합니다. 의존성이 수정되면, Tilt는 로컬 머신에서 제공자 매니저 바이너리를 재빌드하고, 바이너리를 구동 중인 컨테이너에 복사한 다음, 재시작 스크립트를 실행합니다. 이는 각 변경사항에 대해 컨테이너 이미지를 다시 빌드하는 것보다 훨씬 빠릅니다. 또한 각 개발 이미지의 크기를 가능한 한 작게 유지하는 데 도움이 됩니다(컨테이너 이미지에는 전체 Go 도구 체인, 소스 코드, 모듈 의존성 등이 필요하지 않음).

8 Tiltfile IDE 지원

IntelliJ의 경우, Tiltfile의 구문 강조 표시를 TextMate 번들로 설정할 수 있습니다. 지침은 Tiltfile TextMate Bundle을 참조하세요.

VSCode의 경우, Bazel 플러그인을 사용할 수 있으며, 구문 강조 및 자동 포맷팅을 제공합니다. Tiltfile에 대해 이를 활성화하려면 사용자 세팅을 통해 파일 연계를 설정해야 합니다:

"files.associations": {
  "Tiltfile": "starlark",
},

9 Podman 사용

다음 작업을 수행하면 Docker 대신 Podman을 사용할 수 있습니다:

1. podman 유닉스 소켓을 활성화합니다:
   • 리눅스/systemd에서: systemctl --user enable --now podman.socket
   • 맥OS에서: podman machine init으로 podman 머신 생성
2. tilt-settings.yaml에서 build_engine를 podman으로 지정 (선택사항, Docker와 podman이 모두 설치된 경우에만)
3. 환경변수 DOCKER_HOST를 올바른 소켓으로 정의합니다.
   • 리눅스/systemd에서: export DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock
   • 맥OS에서: export DOCKER_HOST=$(podman machine inspect <machine> | jq -r '.[0].ConnectionInfo.PodmanSocket.Path') 여기서 <machine>은 podman 머신 이름
4. tilt up 실행

참고: DOCKER_HOST에 의해 정의된 소켓은 hack/tools/internal/tilt-prepare 명령어에만 사용되며, 이미지 빌드는 podman build / podman push 명령어를 실행합니다.

10 Tilt 트러블슈팅

10.1 Tilt 스턱

연결을 기다리는 동안 tilt가 멈춘 것처럼 보일 때가 있습니다.

docker/podman이 구동 중이고 kubernetes 클러스터에 연결할 수 있는지 확인하세요.

10.2 tilt-prepare 구동 오류

10.2.1 failed to get current context from the KubeConfig file

• kubectl cluster-info를 실행하여 기본 컨텍스트의 클러스터에 연결할 수 있는지 확인하세요.
• kubectl config use-context를 사용하여 올바른 컨텍스트로 전환하세요.
• 컨텍스트가 허용되는지 확인하세요. allowed_contexts 필드를 참조하세요.

10.2.2 Cannot connect to the Docker daemon

• docker 데몬이 실행 중인지 확인하세요 ;) 또는 podman의 경우 Podman 사용을 참조하세요.
• DOCKER_HOST가 지정된 경우:
  • DOCKER_HOST에 올바른 접두어(보통 unix://)가 있는지 확인하세요.
  • fuser / lsof / netstat -u를 사용하여 docker/podman이 $DOCKER_HOST를 리슨하고 있는지 확인하세요.

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