Cluster API - 부트스트랩 제공자 사양

1 개요[ | ]

Bootstrap Provider Specification
부트스트랩 제공자 사양

https://cluster-api.sigs.k8s.io/developer/providers/bootstrap

부트스트랩 제공자는 Kubernetes 노드를 부트스트랩하는 데 사용되는 부트스트랩 데이터를 생성합니다.

예를 들어, Kubeadm 부트스트랩 제공자는 노드를 부트스트랩하기 위해 cloud-init 파일을 사용합니다.

2 데이터 타입[ | ]

2.1 부트스트랩 API 리소스[ | ]

부트스트랩 제공자는 부트스트랩 리소스를 위한 API 타입을 정의해야 합니다. 이 타입은 다음과 같은 조건을 만족해야 합니다:

1. 쿠버네티스 API 서버에서 제공하는 API 그룹에 속해야 합니다.
2. CustomResourceDefinition(CRD)으로 구현되어야 합니다.
- CRD 이름은 sigs.k8s.io/cluster-api/util/contract.CalculateCRDName(Group, Kind)에서 생성된 형식을 가져야 합니다.
3. 네임스페이스 스코프여야 합니다.
4. 표준 쿠버네티스 "타입 메타데이터"와 "객체 메타데이터"를 가져야 합니다.
5. 부트스트랩 프로바이더와 관련된 필드를 포함하는 spec 필드가 있어야 합니다.
6. 다음과 같은 필드가 포함된 status 필드가 있어야 합니다:
- 필수 필드:
  - ready (boolean): 부트스트랩 데이터가 생성되어 준비되었음을 나타냅니다.
  - dataSecretName (string): 생성된 부트스트랩 데이터를 저장하는 비밀(Secret)의 이름입니다.
- 선택적 필드:
  - failureReason (string): 부트스트랩 데이터를 조정하는 데 치명적인 문제가 있음을 나타내며, 프로그래밍적으로 해석하기 적합한 값이어야 합니다.
  - failureMessage (string): 부트스트랩 데이터를 조정하는 데 치명적인 문제가 있음을 나타내며, failureReason보다 더 설명적인 값이어야 합니다.

참고: dataSecretName은 status의 일부이기 때문에 Cluster, Machine 및/또는 부트스트랩 리소스의 데이터에서 결정적으로 재생성할 수 있어야 합니다. 이름이 무작위로 생성되는 경우 리소스와 관련된 비밀을 한 관리 클러스터에서 다른 클러스터로 이동하는 것이 항상 가능하지는 않습니다.

2.2 BootstrapTemplate 리소스[ | ]

Bootstrap 리소스에 대해, 해당하는 BootstrapTemplate 리소스를 추가해야 합니다:

// PhippyBootstrapConfigTemplateSpec는 PhippyBootstrapConfigTemplate의 원하는 상태를 정의합니다.
type PhippyBootstrapConfigTemplateSpec struct {
	Template PhippyBootstrapTemplateResource `json:"template"`
}

// +kubebuilder:object:root=true
// +kubebuilder:resource:path=phippybootstrapconfigtemplates,scope=Namespaced,categories=cluster-api,shortName=pbct
// +kubebuilder:storageversion

// PhippyBootstrapConfigTemplate는 Phippy Bootstrap API의 스키마입니다.
type PhippyBootstrapConfigTemplate struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec PhippyBootstrapConfigTemplateSpec `json:"spec,omitempty"`
}

type PhippyBootstrapConfigTemplateResource struct {
	// 표준 객체의 메타데이터.
	// 참고 정보: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
	// +optional
	ObjectMeta clusterv1.ObjectMeta `json:"metadata,omitempty"`

	Spec PhippyBootstrapConfigSpec `json:"spec"`
}

템플릿의 CRD 이름은 sigs.k8s.io/cluster-api/util/contract.CalculateCRDName(Group, Kind)에서 생성된 형식을 가져야 합니다.

2.3 List 리소스[ | ]

리소스가 있다면, 그에 대한 리스트 리소스도 추가합니다. 예시:

//+kubebuilder:object:root=true

// PhippyBootstrapConfigList는 PhippyBootstrapConfig 객체 리스트를 포함합니다.
type PhippyBootstrapConfigList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []PhippyBootstrapConfig `json:"items"`
}

//+kubebuilder:object:root=true

// PhippyBootstrapConfigTemplateList는 PhippyBootstrapConfigTemplate 객체 리스트를 포함합니다.
type PhippyBootstrapConfigTemplateList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []PhippyBootstrapConfigTemplate `json:"items"`
}

2.4 부트스트랩 시크릿[ | ]

부트스트랩 데이터가 포함된 Secret은 다음 조건을 충족해야 합니다:

1. API 리소스의 status.dataSecretName을 이름으로 사용해야 합니다.
2. cluster.x-k8s.io/cluster-name 레이블이 클러스터 이름으로 설정되어 있어야 합니다.
3. API 리소스에 대한 컨트롤러 소유자 참조를 가져야 합니다.
4. 부트스트랩 데이터를 포함하는 단일 key, value를 가져야 합니다.

3 동작[ | ]

부트스트랩 제공자는 부트스트랩 리소스의 변경사항에 대응해야 합니다. 이 과정은 일반적으로 맞춤조정(reconciliation)이라고 합니다. 제공자는 신규, 업데이트, 삭제된 리소스를 감시하고 적절히 대응해야 합니다.

다음 다이어그램은 부트스트랩 제공자의 일반적인 로직을 보여줍니다:

1. 리소스에 머신 소유자가 없는 경우, 맞춤조정에서 종료합니다.
- 클러스터 API 머신 맞춤조정자는 Machine의 spec.bootstrap.configRef 필드의 값을 기반으로 이를 채웁니다.
2. 리소스에 status.failureReason 또는 status.failureMessage가 설정된 경우, 맞춤조정에서 종료합니다.
3. 이 리소스가 속한 Cluster를 찾을 수 없는 경우, 맞춤조정에서 종료합니다.
4. 부트스트랩 데이터 시크릿의 이름을 결정적으로 생성합니다.
5. 이전 단계에서 생성된 이름으로 Secret을 조회하려고 시도합니다.
- 존재하지 않는 경우, 부트스트랩 데이터를 생성하고 Secret을 생성합니다.
6. status.dataSecretName에 생성된 이름을 세팅합니다.
7. status.ready를 true로 세팅합니다.
8 .리소스를 패치하여 변경사항을 영구적으로 저장합니다.

4 센티널 파일[ | ]

부트스트랩 제공자의 부트스트랩 데이터는 Kubernetes 노드의 부트스트래핑이 성공적으로 완료되면 /run/cluster-api/bootstrap-success.complete(Windows 머신의 경우 C:\run\cluster-api\bootstrap-success.complete)를 생성해야 합니다. 이를 통해 인프라 제공자는 부트스트랩 실패를 감지하고 조치할 수 있습니다.

5 생성 시 노드 테인트[ | ]

부트스트랩 공급자는 선택적으로 워커 노드가 생성될 때 node.cluster.x-k8s.io/uninitialized:NoSchedule 테인트를 추가할 수 있습니다. 이 테인트은 클러스터 API에 의해 노드가 초기화되기 전에 워크로드가 노드에 예약되는 것을 방지하기 위해 사용됩니다. 현재 노드 초기화는 머신에서 노드로 레이블을 동기화하는 작업으로 구성됩니다. 레이블이 초기 동기화되면 노드에서 테인트가 제거됩니다.

6 RBAC[ | ]

6.1 제공자 컨트롤러[ | ]

부트스트랩 제공자는 정의한 타입뿐만 아니라 관리하는 부트스트랩 데이터 Secret 리소스에 대한 RBAC 권한이 필요합니다. kubebuilder를 사용하여 새 API 타입을 생성하는 경우 이러한 권한은 자동으로 설정됩니다. 예를 들어, Kubeadm 부트스트랩 제공자는 KubeadmConfig 타입에 대해 다음과 같은 설정을 사용합니다:

// +kubebuilder:rbac:groups=bootstrap.cluster.x-k8s.io,resources=kubeadmconfigs;kubeadmconfigs/status,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups="",resources=secrets,verbs=get;list;watch;create;update;patch;delete

부트스트랩 제공자는 또한 Cluster와 같은 다른 타입에 대한 RBAC 권한이 필요할 수 있습니다. 읽기 전용 액세스가 필요한 경우 권한을 get, list, watch로 제한할 수 있습니다. Cluster 리소스를 조회하기 위해 다음 설정을 사용할 수 있습니다:

// +kubebuilder:rbac:groups=cluster.x-k8s.io,resources=clusters;clusters/status,verbs=get;list;watch

6.2 Cluster API 컨트롤러[ | ]

Machine 리소스에 대한 Cluster API 컨트롤러는 bootstrap.cluster.x-k8s.io API 그룹의 모든 리소스에 대해 읽기/쓰기 RBAC 권한으로 설정됩니다. 이 그룹은 SIG Cluster Lifecycle에서 후원하는 제공자 하위 프로젝트의 모든 부트스트랩 제공자를 나타냅니다. 만약 SIG에서 후원하지 않는 제공자를 작성하고 있다면, 귀하의 API 그룹에서 부트스트랩 리소스에 대한 읽기/쓰기 액세스를 부여하는 새로운 RBAC 권한을 Cluster API manager-role 역할에 추가해야 합니다.

참고로, 쓰기 권한은 Machine 컨트롤러가 부트스트랩 리소스에 소유자 참조와 레이블을 설정할 수 있도록 허용합니다. 이는 이러한 리소스를 일반적으로 변경하는 데 사용되지 않습니다.