Clusterctl 제공자 컨트랙트

1 개요

clusterctl Provider Contract

clusterctl 제공자 컨트랙트

clusterctl 명령어는 다음 규칙을 준수하는 모든 제공자와 작동하도록 설계되었습니다.

1.1 제공자 리포지토리

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

제공자 리포지토리에는 다음 파일이 포함되어야 합니다.

• 메타데이터 YAML
• 컴포넌트 YAML

또한, 제공자 리포지토리에는 다음 파일이 포함되어야 합니다.

• 워크로드 클러스터 템플릿

선택적으로, 제공자 리포지토리에는 다음 파일이 포함될 수 있습니다.

• ClusterClass 정의

사전정의된 제공자 목록

clusterctl 명령어는 더 간단하고 바로 사용가능한 사용자 경험을 제공하는 사전정의된 제공자 리포지토리 목록과 함께 제공됩니다. 제공자 구현자로서, 이 목록에 추가되는 데 관심이 있는 경우 다음 단락을 참조하십시오.

제공자 목록 커스터마이징

clusterctl 설정을 변경하여 제공자 목록을 커스터마이징할 수 있습니다.

1.2 clusterctl에 제공자 추가하기

Cluster API 프로젝트로서, 우리는 제공자의 유지관리자가 clusterctl과 함께 제공되는 사전정의된 제공자 목록에 자신의 프로젝트를 추가할 수 있도록 함으로써 모든 오픈소스 CAPI 제공자에 대한 가시성을 제공하게 되어 기쁩니다.

중요! 그것은 가시성일뿐

제공자의 유지관리자는 자신의 프로젝트에 대한 궁극적인 책임을 집니다.

clusterctl 제공자 목록에 제공자를 추가한다고 해도, 어떤 형태로든 Cluster API 유지관리자에 의한 품질평가, 시장조사, 권한부여, 인정, 지원을 암시하는 것은 아닙니다.

clusterctl과 함께 제공되는 사전정의된 제공자 목록에 새 제공자를 추가하는 프로세스입니다.

• 가능한 한 빨리, Cluster API 리포지토리에 새 제공자를 추가하려는 의도를 선언하는 이슈를 생성합니다. 각 공급자는 Clusterctl과 함께 제공되는 사전 정의된 공급자 목록에 고유한 이름 및 유형을 가지고 있어야 합니다. 공급자의 이름은 위 문제에서 선언되어야 하며 다음 명명 규칙을 따라야 합니다.
  • 이름은 소문자 영숫자 문자 또는 '-'로 구성되어야 하며 영숫자 문자로 시작하고 끝나야 합니다.
  • 이름의 길이는 63자를 초과할 수 없습니다.
  • kubernetes-sigs org에 없는 제공자의 경우, 충돌을 방지하기 위해 clusterctl 이름 앞에 제공자의 GitHub org 이름과 그 뒤에 오는 이름을 붙여야 합니다 - (아래 참조).
• clusterctl과 Cluster API 책에 필요한 변경사항을 적용하여 PR을 만듭니다. (예: #9798, 9720)

Cluster API 유지관리자는 새 제공자 추가에 대한 이슈/PR을 검토합니다. 다음 Cluster API 마이너 릴리스의 코드 동결 기한 전에 PR이 병합되면, 변경사항이 릴리스에 포함되고, 그렇지 않으면 다음 마이너 릴리스에 포함됩니다. 또한 유지관리자는 현재 Cluster API 마이너 릴리스 브랜치로 백포트하여 다음 패치 릴리스에 포함시키는 것이 가능한지/편리한지를 고려할 것입니다.

클로즈드 소스 제공자는 어떻습니까?

클로즈드 소스 제공자는 clusterctl과 함께 제공되는 사전정의된 제공자 목록에 추가할 수 없습니다. 그러나, 이러한 제공자도 clusterctl 설정을 변경하여 사용할 수 있습니다.

제공자의 GitHub org 접두어

kubernetes-sigs org에 없는 제공자에 대한 접두어 추가 필요는 2024년 1월부터 clusterctl의 사전정의된 제공자 목록에 추가되는 모든 제공자에 적용됩니다. 이 규칙은 기존의 사전정의된 제공자에 소급적용되지 않지만, 향후 이를 재검토할 여지는 남겨두었습니다.

kubernetes-sigs org에 없는 제공자에 대한 접두어 추가해 필요는 clusterctl 설정을 변경하여 추가된 제공자에는 적용되지 않습니다.

1.3 GitHub에 제공자 리포지토리 생성하기

GitHub 릴리스를 사용하여 다른 사람이 사용할 수 있도록 제공자 아티팩트를 패키징할 수 있습니다.

다음과 같은 경우 GitHub 릴리스를 제공자 저장소로 사용할 수 있습니다.

• 릴리스 태그가 시맨틱 버전 번호입니다.
• 컴포넌트 YAML, 메타데이터 YAML, 최종적으로 워크로드 클러스터 템플릿이 릴리스 애셋에 포함됩니다.

릴리스 생성 방법에 대한 자세한 내용은 GitHub 문서를 참조하세요.

기본적으로 clusterctl는 go 프록시를 사용하여 GitHub API에 대한 추가 API 호출을 방지하기 위해 사용가능한 버전을 감지합니다. go 자체에 대한 GOPROXY 변수를 사용하여 go 프록시 URL을 설정할 수 있습니다(기본값은 https://proxy.golang.org). GitHub 클라이언트로 즉시 대체하고 go 프록시를 사용하지 않으려면 환경변수를 GOPROXY=off 또는 GOPROXY=direct로 설정할 수 있습니다. 제공자가 Go의 시맨틱 버저닝을 따르지 않으면, clusterctl은 올바른 버전을 감지하는 데 실패할 수 있습니다. 이러한 경우 GOPROXY=off를 통해 go proxy 기능을 비활성화하는 것을 고려해야 합니다.

1.4 GitLab에 제공자 리포지토리 생성하기

제공자 아티팩트에 GitLab 일반 패키지를 사용할 수 있습니다.

제공자 URL은 https://{host}/api/v4/projects/{projectSlug}/packages/generic/{packageName}/{defaultVersion}/{componentsPath} 형식이어야 합니다. 여기서:

• {host}는 gitlab으로 시작해야 합니다 (gitlab.com, gitlab.example.org, ...)
• {projectSlug}는 프로젝트 아이디(42) 또는 이스케이프된 전체 경로(myorg%2Fmyrepo)입니다
• {defaultVersion}는 유효한 시맨틱 버전 번호입니다
• 컴포넌트 YAML, 메타데이터 YAML, 최종적으로 워크로드 클러스터 템플릿이 동일한 패키지 버전에 포함됩니다

일반 패키지를 만드는 방법에 대한 자세한 내용은 GitLab 문서를 참조하세요.

이는 GitLabracadabra와 함께 사용하여 clusterctl에서 직접 인터넷에 액세스하는 것을 방지하고 GitLab을 아티팩트 저장소로 사용할 수 있습니다. 예를 들어, 코어 제공자의 경우:

• 다음 액션 파일을 사용하세요.

external-packages/cluster-api:
  packages_enabled: true
  package_mirrors:
  - github:
      full_name: kubernetes-sigs/cluster-api
      tags:
      - v1.2.3
      assets:
      - clusterctl-linux-amd64
      - core-components.yaml
      - bootstrap-components.yaml
      - control-plane-components.yaml
      - metadata.yaml

• 다음 clusterctl 설정을 사용하세요.

providers:
  #  자체호스팅 GitLab에 사전정의된 제공자 오버라이드
  - name: "cluster-api"
    url: "https://gitlab.example.com/api/v4/projects/external-packages%2Fcluster-api/packages/generic/cluster-api/v1.2.3/core-components.yaml"
    type: "CoreProvider"

제한사항: GitLab에서 호스팅되는 제공자 아티팩트는 모든 버전 가져오기를 지원하지 않습니다. 따라서, 업그레이드를 위해 버전을 명시적으로 설정해야 합니다.

1.5 로컬 제공자 리포지토리 생성하기

clusterctl은 로컬 파일시스템에 정의된 리포지토리에서 읽기를 지원합니다.

각 호스팅 릴리스에 대해 <version> 하위 폴더가 있는 <provider-label> 폴더를 생성하여 로컬 리포지토리를 정의할 수 있습니다. 하위폴더 이름은 유효한 시맨틱 버전 번호여야 합니다. 예시:

~/local-repository/infrastructure-aws/v0.5.2

각 버전 하위폴더에는 해당 컴포넌트 YAML, 메타데이터 YAML, 최종적으로 워크로드 클러스터 템플릿이 포함되어야 합니다.

2 메타데이터 YAML

제공자는 메타데이터 YAML 파일을 생성하고 이를 제공자의 리포지토리에 게시해야 합니다.

메타데이터 YAML 파일은 각 제공자의 릴리스 시리즈를 문서화하고 각 릴리스 시리즈를 클러스터 API(컨트랙트)의 API 버전에 매핑합니다.

예를 들어, Cluster API의 경우:

apiVersion: clusterctl.cluster.x-k8s.io/v1alpha3
kind: Metadata
releaseSeries:
- major: 0
  minor: 3
  contract: v1alpha3
- major: 0
  minor: 2
  contract: v1alpha2

사용자 경험에 대한 참고사항

v1alpha4 이전의 clusterctl 버전의 경우, 제공자 구현자가 clusterctl의 빌트인 메타데이터만 업데이트하고 새 릴리스에서 metadata.yaml을 제공하지 않는 경우, 사용자는 제공자를 올바르게 설치하기 위해 clusterctl을 최신 릴리스 버전으로 업데이트해야 합니다.

관련 예시로, 이슈 3418의 세부정보를 참조하세요.

위에 설명된 문제를 해결하기 위해, 최신 제공자 릴리스를 가져오려고 최신 버전의 clusterctl을 사용해야 하는 번거로움을 방지하기 위해, clusterctl 내에 포함된 메타데이터가 제거되었습니다(v1alpha4부터).

자세한 내용은 이슈 3515의 세부정보를 참조하세요.

3 컴포넌트 YAML

제공자는 컴포넌트 YAML 파일을 생성하고 이를 제공자의 리포지토리에 게시해야 합니다. 이 파일은 제공자 자체(CRD, 컨트롤러, RBAC 등)를 설치하는 데 필요한 모든 컴포넌트가 포함된 단일 YAML입니다.

다음 규칙이 적용됩니다.

3.1 명명 규칙

다음을 강력히 권장합니다.

• 코어 제공자는 core-components.yaml이라는 파일을 릴리스합니다.
• 인프라 제공자는infrastructure-components.yaml이라는 파일을 릴리스합니다.
• 부트스트랩 제공자는 bootstrap-components.yaml이라는 파일을 릴리스합니다.
• 컨트롤 플레인 제공자는 control-plane-components.yaml이라는 파일을 릴리스합니다.
• IPAM 제공자는 ipam-components.yaml이라는 파일을 릴리스합니다.
• 런타임 확장 제공자는 runtime-extension-components.yaml이라는 파일을 릴리스합니다.
• 애드온 제공자는 addon-components.yaml이라는 파일을 릴리스합니다.

3.2 타겟 네임스페이스

The instance components should contain one Namespace object, which will be used as the default target namespace when creating the provider components.

All the objects in the components YAML MUST belong to the target namespace, with the exception of objects that are not namespaced, like ClusterRoles/ClusterRoleBinding and CRD objects.

Warning If the generated component YAML doesn’t contain a Namespace object, the user will be required to provide one to clusterctl init using the --target-namespace flag.

In case there is more than one Namespace object in the components YAML, clusterctl will generate an error and abort the provider installation.

3.3 컨트롤러 & 네임스페이스 감시

Each provider is expected to deploy controllers/runtime extension server using a Deployment.

While defining the Deployment Spec, the container that executes the controller/runtime extension server binary MUST be called manager.

For controllers only, the manager MUST support a --namespace flag for specifying the namespace where the controller will look for objects to reconcile; however, clusterctl will always install providers watching for all namespaces (--namespace=""); for more details see support for multiple instances for more context.

While defining Pods for Deployments, canonical names should be used for images.

3.4 변수

The components YAML can contain environment variables matching the format ${VAR}; it is highly recommended to prefix the variable name with the provider name e.g. ${AWS_CREDENTIALS}

Warning clusterctl currently supports variables with leading/trailing spaces such as: ${ VAR }, ${ VAR},${VAR }. However, these formats will be deprecated in the near future. e.g. v1alpha4.

Formats such as ${VAR$FOO} are not supported.

clusterctl uses the library drone/envsubst to perform variable substitution.

1. If `VAR` is not set or empty, the default value is used. This is true for
2. all the following formats.

${VAR:=default} ${VAR=default} ${VAR:-default} Other functions such as substring replacement are also supported by the library. See drone/envsubst for more information.

Additionally, each provider should create user facing documentation with the list of required variables and with all the additional notes that are required to assist the user in defining the value for each variable.

3.5 레이블

컴포넌트 YAML의 컴포넌트에는 cluster.x-k8s.io/provider와 제공자 이름으로 레이블이 지정되어야 합니다. 이렇게 하면 kubectl apply에서 clusterctl으로 더 쉽게 전환할 수 있습니다 .

참고로 다음 제공자에 적용되는 레이블을 고려해 볼 수 있습니다.

제공자 이름	레이블
CAPI	cluster.x-k8s.io/provider=cluster-api
CABPK	cluster.x-k8s.io/provider=bootstrap-kubeadm
CABPM	cluster.x-k8s.io/provider=bootstrap-microk8s
CABPKK3S	cluster.x-k8s.io/provider=bootstrap-kubekey-k3s
CABPOCNE	cluster.x-k8s.io/provider=bootstrap-ocne
CABPK0S	cluster.x-k8s.io/provider=bootstrap-k0smotron
CACPK	cluster.x-k8s.io/provider=control-plane-kubeadm
CACPM	cluster.x-k8s.io/provider=control-plane-microk8s
CACPN	cluster.x-k8s.io/provider=control-plane-nested
CACPKK3S	cluster.x-k8s.io/provider=control-plane-kubekey-k3s
CACPOCNE	cluster.x-k8s.io/provider=control-plane-ocne
CACPK0S	cluster.x-k8s.io/provider=control-plane-k0smotron
CAPA	cluster.x-k8s.io/provider=infrastructure-aws
CAPB	cluster.x-k8s.io/provider=infrastructure-byoh
CAPC	cluster.x-k8s.io/provider=infrastructure-cloudstack
CAPD	cluster.x-k8s.io/provider=infrastructure-docker
CAPIM	cluster.x-k8s.io/provider=infrastructure-in-memory
CAPDO	cluster.x-k8s.io/provider=infrastructure-digitalocean
CAPG	cluster.x-k8s.io/provider=infrastructure-gcp
CAPH	cluster.x-k8s.io/provider=infrastructure-hetzner
CAPHV	cluster.x-k8s.io/provider=infrastructure-hivelocity
CAPIBM	cluster.x-k8s.io/provider=infrastructure-ibmcloud
CAPKK	cluster.x-k8s.io/provider=infrastructure-kubekey
CAPK	cluster.x-k8s.io/provider=infrastructure-kubevirt
CAPM3	cluster.x-k8s.io/provider=infrastructure-metal3
CAPN	cluster.x-k8s.io/provider=infrastructure-nested
CAPO	cluster.x-k8s.io/provider=infrastructure-openstack
CAPOCI	cluster.x-k8s.io/provider=infrastructure-oci
CAPP	cluster.x-k8s.io/provider=infrastructure-packet
CAPT	cluster.x-k8s.io/provider=infrastructure-tinkerbell
CAPV	cluster.x-k8s.io/provider=infrastructure-vsphere
CAPVC	cluster.x-k8s.io/provider=infrastructure-vcluster
CAPVCD	cluster.x-k8s.io/provider=infrastructure-vcd
CAPX	cluster.x-k8s.io/provider=infrastructure-nutanix
CAPZ	cluster.x-k8s.io/provider=infrastructure-azure
CAPOSC	cluster.x-k8s.io/provider=infrastructure-outscale
CAPK0S	cluster.x-k8s.io/provider=infrastructure-k0smotron
CAIPAMIC	cluster.x-k8s.io/provider=ipam-in-cluster

4 워크로드 클러스터 템플릿

An infrastructure provider could publish a cluster templates file to be used by clusterctl generate cluster. This is single YAML with all the objects required to create a new workload cluster.

With ClusterClass enabled it is possible to have cluster templates with managed topologies. Cluster templates with managed topologies require only the cluster object in the template and a corresponding ClusterClass definition.

The following rules apply:

4.1 네이밍 컨벤션

Cluster templates MUST be stored in the same location as the component YAML and follow this naming convention:

The default cluster template should be named cluster-template.yaml. Additional cluster template should be named cluster-template-{flavor}.yaml. e.g cluster-template-prod.yaml {flavor} is the name the user can pass to the clusterctl generate cluster --flavor flag to identify the specific template to use.

Each provider SHOULD create user facing documentation with the list of available cluster templates.

4.2 타겟 네임스페이스

The cluster template YAML MUST assume the target namespace already exists.

All the objects in the cluster template YAML MUST be deployed in the same namespace.

4.3 변수

The cluster templates YAML can also contain environment variables (as can the components YAML).

Additionally, each provider should create user facing documentation with the list of required variables and with all the additional notes that are required to assist the user in defining the value for each variable.

4.3.1 공통 변수

The clusterctl generate cluster command allows user to set a small set of common variables via CLI flags or command arguments.

Templates writers should use the common variables to ensure consistency across providers and a simpler user experience (if compared to the usage of OS environment variables or the clusterctl config file).

CLI flag Variable name Note --target-namespace ${NAMESPACE} The namespace where the workload cluster should be deployed --kubernetes-version ${KUBERNETES_VERSION} The Kubernetes version to use for the workload cluster --controlplane-machine-count ${CONTROL_PLANE_MACHINE_COUNT} The number of control plane machines to be added to the workload cluster --worker-machine-count ${WORKER_MACHINE_COUNT} The number of worker machines to be added to the workload cluster Additionally, the value of the command argument to clusterctl generate cluster <cluster-name> (<cluster-name> in this case), will be applied to every occurrence of the ${ CLUSTER_NAME } variable.

5 ClusterClass 정의

An infrastructure provider could publish a ClusterClass definition file to be used by clusterctl generate cluster that will be used along with the workload cluster templates. This is a single YAML with all the objects required that make up the ClusterClass.

The following rules apply:

5.1 네이밍 컨벤션

ClusterClass definitions MUST be stored in the same location as the component YAML and follow this naming convention:

The ClusterClass definition should be named clusterclass-{ClusterClass-name}.yaml, e.g clusterclass-prod.yaml. {ClusterClass-name} is the name of the ClusterClass that is referenced from the Cluster.spec.topology.class field in the Cluster template; Cluster template files using a ClusterClass are usually simpler because they are no longer required to have all the templates.

Each provider should create user facing documentation with the list of available ClusterClass definitions.

5.2 타겟 네임스페이스

The ClusterClass definition YAML MUST assume the target namespace already exists.

The references in the ClusterClass definition should NOT specify a namespace.

It is recommended that none of the objects in the ClusterClass YAML should specify a namespace.

Even if technically possible, it is strongly recommended that none of the objects in the ClusterClass definitions are shared across multiple definitions; this helps in preventing changing an object inadvertently impacting many ClusterClasses, and consequently, all the Clusters using those ClusterClasses.

5.3 변수

Currently the ClusterClass definitions SHOULD NOT have any environment variables in them.

ClusterClass definitions files should not use variable substitution, given that ClusterClass and managed topologies provide an alternative model for variable definition.

5.4 참고

A ClusterClass definition is automatically included in the output of clusterctl generate cluster if the cluster template uses a managed topology and a ClusterClass with the same name does not already exists in the Cluster.

6 OwnerReferences 체인

Each provider is responsible to ensure that all the providers resources (like e.g. VSphereCluster, VSphereMachine, VSphereVM etc. for the vsphere provider) MUST have a Metadata.OwnerReferences entry that links directly or indirectly to a Cluster object.

Please note that all the provider specific resources that are referenced by the Cluster API core objects will get the OwnerReference set by the Cluster API core controllers, e.g.:

The Cluster controller ensures that all the objects referenced in Cluster.Spec.InfrastructureRef get an OwnerReference that links directly to the corresponding Cluster. The Machine controller ensures that all the objects referenced in Machine.Spec.InfrastructureRef get an OwnerReference that links to the corresponding Machine, and the Machine is linked to the Cluster through its own OwnerReference chain. That means that, practically speaking, provider implementers are responsible for ensuring that the OwnerReferences are set only for objects that are not directly referenced by Cluster API core objects, e.g.:

All the VSphereVM instances should get an OwnerReference that links to the corresponding VSphereMachine, and the VSphereMachine is linked to the Cluster through its own OwnerReference chain.

7 추가 참고사항

7.1 컴포넌트 YAML 변환

Provider authors should be aware of the following transformations that clusterctl applies during component installation:

Variable substitution; Enforcement of target namespace: The name of the namespace object is set; The namespace field of all the objects is set (with exception of cluster wide objects like e.g. ClusterRoles); All components are labeled;

7.2 클러스터 템플릿 변환

Provider authors should be aware of the following transformations that clusterctl applies during components installation:

Variable substitution; Enforcement of target namespace: The namespace field of all the objects are set;

7.3 외부 객체 링크

The clusterctl command requires that both the components YAML and the cluster templates contain all the required objects.

If, for any reason, the provider authors/YAML designers decide not to comply with this recommendation and e.g. to

implement links to external objects from a component YAML (e.g. secrets, aggregated ClusterRoles NOT included in the component YAML) implement link to external objects from a cluster template (e.g. secrets, configMaps NOT included in the cluster template) The provider authors/YAML designers should be aware that it is their responsibility to ensure the proper functioning of clusterctl when using non-compliant component YAML or cluster templates.

7.4 이동

Provider authors should be aware that clusterctl move command implements a discovery mechanism that considers:

All the Kind defined in one of the CRDs installed by clusterctl using clusterctl init (identified via the clusterctl.cluster.x-k8s.io label); For each CRD, discovery collects: All the objects from the namespace being moved only if the CRD scope is Namespaced. All the objects if the CRD scope is Cluster. All the ConfigMap objects from the namespace being moved. All the Secret objects from the namespace being moved and from the namespaces where infrastructure providers are installed. After completing discovery, clusterctl move moves to the target cluster only the objects discovered in the previous phase that are compliant with one of the following rules:

The object is directly or indirectly linked to a Cluster object (linked through the OwnerReference chain). The object is a secret containing a user provided certificate (linked to a Cluster object via a naming convention). The object is directly or indirectly linked to a ClusterResourceSet object (through the OwnerReference chain). The object is directly or indirectly linked to another object with the clusterctl.cluster.x-k8s.io/move-hierarchy label, e.g. the infrastructure Provider ClusterIdentity objects (linked through the OwnerReference chain). The object has the clusterctl.cluster.x-k8s.io/move label or the clusterctl.cluster.x-k8s.io/move-hierarchy label, e.g. the CPI config secret. Note. clusterctl.cluster.x-k8s.io/move and clusterctl.cluster.x-k8s.io/move-hierarchy labels could be applied to single objects or at the CRD level (the label applies to all the objects).

Please note that during move:

Namespaced objects, if not existing in the target cluster, are created. Namespaced objects, if already existing in the target cluster, are updated. Namespaced objects are removed from the source cluster. Global objects, if not existing in the target cluster, are created. Global objects, if already existing in the target cluster, are not updated. Global objects are not removed from the source cluster. Namespaced objects which are part of an owner chain that starts with a global object (e.g. a secret containing credentials for an infrastructure Provider ClusterIdentity) are treated as Global objects.

경고

When using the “move” label, if the CRD is a global resource, the object is copied to the target cluster but not removed from the source cluster. It is up to the user to remove the source object as necessary.

If moving some of excluded object is required, the provider authors should create documentation describing the exact move sequence to be executed by the user.

Additionally, provider authors should be aware that clusterctl move assumes all the provider’s Controllers respect the Cluster.Spec.Paused field introduced in the v1alpha3 Cluster API specification. If a provider needs to perform extra work in response to a cluster being paused, clusterctl move can be blocked from creating any resources on the destination management cluster by annotating any resource to be moved with clusterctl.cluster.x-k8s.io/block-move.

경고: 상태 서브리소스는 복원되지 않습니다

Every object’s Status subresource, including every nested field (e.g. Status.Conditions), is never restored during a move operation. A Status subresource should never contain fields that cannot be recreated or derived from information in spec, metadata, or external systems.

Provider implementers should not store non-ephemeral data in the Status. Status should be able to be fully rebuilt by controllers by observing the current state of resources.

8 참고

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