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

When installing a provider clusterctl reads a YAML file that is published in the provider repository. While executing this operation, clusterctl can substitute certain variables with the ones provided by the user.

The same mechanism also applies when clusterctl reads the cluster templates YAML published in the repository, e.g. when injecting the Kubernetes version to use, or the number of worker machines to create.

The user can provide values using OS environment variables, but it is also possible to add variables in the clusterctl config file:

1. Values for environment variable substitution

AWS_B64ENCODED_CREDENTIALS: XXXXXXXX The format of keys should always be UPPERCASE_WITH_UNDERSCORE for both OS environment variables and in the clusterctl config file (NOTE: this limitation derives from Viper, the library we are using internally to retrieve variables).

In case a variable is defined both in the config file and as an OS environment variable, the environment variable takes precedence.

4 Cert-Manager 설정

While doing init, clusterctl checks if there is a version of cert-manager already installed. If not, clusterctl will install a default version.

By default, cert-manager will be fetched from https://github.com/cert-manager/cert-manager/releases; however, if the user wants to use a different repository, it is possible to use the following configuration:

cert-manager:

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

Note: It is possible to use the ${HOME} and ${CLUSTERCTL_REPOSITORY_PATH} environment variables in url.

Similarly, it is possible to override the default version installed by clusterctl by configuring:

cert-manager:

 ...
 version: "v1.1.1"

For situations when resources are limited or the network is slow, the cert-manager wait time to be running can be customized by adding a field to the clusterctl config file, for example:

cert-manager:

 ...
 timeout: 15m

The value string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as “300ms”, “-1.5h” or “2h45m”. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”.

If no value is specified, or the format is invalid, the default value of 10 minutes will be used.

Please note that the configuration above will be considered also when doing clusterctl upgrade plan or clusterctl upgrade plan.

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 레이트 리미팅 회피하기

Follow this

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 디버깅/로깅

To have more verbose logs you can use the -v flag when running the clusterctl and set the level of the logging verbose with a positive integer number, ie. -v 3.

If you do not want to use the flag every time you issue a command you can set the environment variable CLUSTERCTL_LOG_LEVEL or set the variable in the clusterctl config file located by default at $XDG_CONFIG_HOME/cluster-api/clusterctl.yaml.

10 업데이트 확인 생략

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

11 참고

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