Clusterctl 설정 파일

1 개요

clusterctl Configuration File

clusterctl 설정 파일

clusterctl 설정 파일은 $XDG_CONFIG_HOME/cluster-api/clusterctl.yaml에 있습니다. 다음과 같은 데에 사용할 수 있습니다.

• 제공자 및 제공자 리포지토리 목록을 커스터마이징합니다.
• 제공자를 설치하거나 클러스터를 생성할 때 변수 치환에 사용할 설정값을 제공합니다.
• 에어갭 환경에 대한 이미지 오버라이드를 정의합니다.

2 제공자 리포지토리

clusterctl CLI는 clusterctl 제공자 컨트랙트를 구현한 제공자와 작동하도록 설계되었습니다.

각 제공자는 릴리스 애셋이 게시되는 잘 알려진 장소인 제공자 리포지토리를 정의해야 합니다.

기본적으로, clusterctl은 SIG Cluster Lifecycle이 후원하는 제공자와 함께 제공됩니다. 지원되는 제공자 목록과 해당 리포지토리 설정을 얻으려면 clusterctl config repositories를 사용하십시오.

사용자는 다음 예시와 같이, clusterctl 설정 파일을 사용하여 사용가능한 제공자 목록을 커스터마이징할 수 있습니다.

providers:
  # 커스텀 제공자 추가
  - name: "my-infra-provider"
    url: "https://github.com/myorg/myrepo/releases/latest/infrastructure-components.yaml"
    type: "InfrastructureProvider"
  # 사전정의된 제공자 오버라이드
  - name: "cluster-api"
    url: "https://github.com/myorg/myforkofclusterapi/releases/latest/core-components.yaml"
    type: "CoreProvider"
  # 셀프호스팅 GitLab(호스트는 "gitlab."으로 시작해야 함)에 있는 커스텀 제공자 추가
  - name: "my-other-infra-provider"
    url: "https://gitlab.example.com/api/v4/projects/myorg%2Fmyrepo/packages/generic/myrepo/v1.2.3/infrastructure-components.yaml"
    type: "InfrastructureProvider"
  # 셀프호스팅 GitLab(호스트는 "gitlab."으로 시작해야 함)에 있는 사전정의된 프로바이더 오버라이드
  - name: "kubeadm"
    url: "https://gitlab.example.com/api/v4/projects/external-packages%2Fcluster-api/packages/generic/cluster-api/v1.1.3/bootstrap-components.yaml"
    type: "BootstrapProvider"

제공자 리포지토리를 셋업하는 방법에 대한 지침은 제공자 컨트랙트를 참조하세요.

참고: url에서 ${HOME} 및 ${CLUSTERCTL_REPOSITORY_PATH} 환경변수를 사용할 수 있습니다.

3 변수

제공자를 설치할 때 clusterctl은 제공자 리포지토리에 게시된 YAML 파일을 읽습니다. 이 작업을 실행하는 동안 clusterctl은 특정 변수를 사용자가 제공한 변수로 대체할 수 있습니다.

clusterctl이 저장소에 게시된 클러스터 템플릿 YAML을 읽을 때도 동일한 메커니즘이 적용됩니다(예: 사용할 Kubernetes 버전을 삽입할 때 또는 생성할 작업자 머신 수를 주입할 때)

사용자는 OS 환경변수를 사용하여 값을 제공할 수 있지만, clusterctl 설정 파일에 변수를 추가하는 것도 가능합니다.

# 환경변수 대체 값
AWS_B64ENCODED_CREDENTIALS: XXXXXXXX

키 형식은 OS 환경변수와 clusterctl 설정 파일 모두에 대해 항상 UPPERCASE_WITH_UNDERSCORE여야 합니다(참고: 이 제한은 변수를 조회하기 위해 내부적으로 사용하는 라이브러리인 Viper에서 파생됩니다).

변수가 설정 파일과 OS 환경변수 모두에 정의된 경우 환경변수가 우선합니다.

4 Cert-Manager 설정

init를 수행하는 동안, clusterctl은 cert-manager 버전이 이미 설치되어 있는지 확인합니다. 설치되지 않은 경우 clusterctl은 기본 버전을 설치합니다.

기본적으로, cert-manager는 https://github.com/cert-manager/cert-manager/releases에서 가져옵니다. 그러나 사용자가 다른 리포지토리를 사용하려는 경우, 다음 설정을 사용할 수 있습니다.

cert-manager:
  url: "/Users/foo/.config/cluster-api/dev-repository/cert-manager/latest/cert-manager.yaml"

참고: url에서 ${HOME} 및 ${CLUSTERCTL_REPOSITORY_PATH} 환경변수를 사용할 수 있습니다.

비슷하게, 다음과 같이 설정하여 clusterctl에 의해 설치된 기본 버전을 오버라이드할 수 있습니다.

cert-manager:
  ...
  version: "v1.1.1"

리소스가 제한되어 있거나 네트워크가 느린 상황의 경우, clusterctl 설정 파일에 필드를 추가하여 실행될 cert-manager 대기 시간을 커스터마이징할 수 있습니다. 예시:

cert-manager:
  ...
  timeout: 15m

값 문자열은 "300ms", "-1.5h", "2h45m"과 같은 선택적 소수점와 단위 접미사가 있는 부호 있는 십진수열일 수 있습니다. 유효한 시간 단위는 "ns", "us"(또는 "μs"), "ms", "s", "m", "h"입니다.

값이 지정되지 않거나, 형식이 유효하지 않은 경우, 기본값인 10분이 사용됩니다.

위의 설정은 clusterctl upgrade plan이나 clusterctl upgrade apply을 수행할 때도 고려됩니다.

5 Migrating to user-managed cert-manager

You may want to migrate to a user-managed cert-manager further down the line, after initialising cert-manager on the management cluster through clusterctl.

clusterctl looks for the label clusterctl.cluster.x-k8s.io/core=cert-manager on all api resources in the cert-manager namespace. If it finds the label, clusterctl will manage the cert-manager deployment. You can list all the resources with that label by running:

kubectl api-resources --verbs=list -o name | xargs -n 1 kubectl get --show-kind --ignore-not-found -A --selector=clusterctl.cluster.x-k8s.io/core=cert-manager If you want to manage and install your own cert-manager, you’ll need to remove this label from all API resources.

Warning Cluster API has a direct dependency on cert-manager. It’s possible you could encounter issues if you use a different version to the Cluster API default version.

6 GitHub 레이트 리미팅 회피하기

이것을 따르십시오.

7 오버라이드 레이어

Warning!

Overrides only provide file replacements; instead, provider version resolution is based only on the actual repository structure.

clusterctl uses an overrides layer to read in injected provider components, cluster templates and metadata. By default, it reads the files from $XDG_CONFIG_HOME/cluster-api/overrides.

The directory structure under the overrides directory should follow the template:

<providerType-providerName>/<version>/<fileName> For example,

├── bootstrap-kubeadm │ └── v1.1.5 │ └── bootstrap-components.yaml ├── cluster-api │ └── v1.1.5 │ └── core-components.yaml ├── control-plane-kubeadm │ └── v1.1.5 │ └── control-plane-components.yaml └── infrastructure-aws

   └── v0.5.0
           ├── cluster-template-dev.yaml
           └── infrastructure-components.yaml

For developers who want to generate the overrides layer, see Build artifacts locally.

Once these overrides are specified, clusterctl will use them instead of getting the values from the default or specified providers.

One example usage of the overrides layer is that it allows you to deploy clusters with custom templates that may not be available from the official provider repositories. For example, you can now do:

clusterctl generate cluster mycluster --flavor dev --infrastructure aws:v0.5.0 -v5 The -v5 provides verbose logging which will confirm the usage of the override file.

Using Override="cluster-template-dev.yaml" Provider="infrastructure-aws" Version="v0.5.0" Another example, if you would like to deploy a custom version of CAPA, you can make changes to infrastructure-components.yaml in the overrides folder and run,

clusterctl init --infrastructure aws:v0.5.0 -v5

... Using Override="infrastructure-components.yaml" Provider="infrastructure-aws" Version="v0.5.0" ... If you prefer to have the overrides directory at a different location (e.g. /Users/foobar/workspace/dev-releases) you can specify the overrides directory in the clusterctl config file as

overridesFolder: /Users/foobar/workspace/dev-releases Note: It is possible to use the ${HOME} and ${CLUSTERCTL_REPOSITORY_PATH} environment variables in overridesFolder.

8 이미지 오버라이드

Warning!

Image override is an advanced feature and wrong configuration can easily lead to non-functional clusters. It’s strongly recommended to test configurations on dev/test environments before using this functionality in production.

This feature must always be used in conjunction with version tag when executing clusterctl commands.

When working in air-gapped environments, it’s necessary to alter the manifests to be installed in order to pull images from a local/custom image repository instead of public ones (e.g. gcr.io, or quay.io).

The clusterctl configuration file can be used to instruct clusterctl to override images automatically.

This can be achieved by adding an images configuration entry as shown in the example:

images:

 all:
   repository: myorg.io/local-repo

Please note that the image override feature allows for more fine-grained configuration, allowing to set image overrides for specific components, for example:

images:

 all:
   repository: myorg.io/local-repo
 cert-manager:
   tag: v1.5.3

In this example we are overriding the image repository for all the components and the image tag for all the images in the cert-manager component.

If required to alter only a specific image you can use:

images:

 all:
   repository: myorg.io/local-repo
 cert-manager/cert-manager-cainjector:
   tag: v1.5.3

9 디버깅/로깅

더 자세한 로그를 얻으려면 clusterctl을 실행할 때 -v 플래그를 사용하고 양의 정수로 로깅 수준을 세팅할 수 있습니다(예: -v 3).

명령어를 실행할 때마다 플래그를 사용하지 않으려면 환경변수 CLUSTERCTL_LOG_LEVEL을 설정하거나 기본적으로 $XDG_CONFIG_HOME/cluster-api/clusterctl.yaml에 있는 clusterctl 설정 파일에 변수를 세팅할 수 있습니다.

10 업데이트 확인 생략

clusterctl은 사용될 때마다 자동으로 새 버전을 확인합니다. clusterctl이 새 업데이트를 확인하지 않도록 하려면 환경변수 CLUSTERCTL_DISABLE_VERSIONCHECK를 "true"로 설정하거나 기본적으로 $XDG_CONFIG_HOME/cluster-api/clusterctl.yaml에 있는 clusterctl 설정 파일에 변수를 세팅할 수 있습니다.

11 참고

• https://cluster-api.sigs.k8s.io/clusterctl/configuration