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 컨트롤러가 부트스트랩 리소스에 소유자 참조와 레이블을 설정할 수 있도록 허용합니다. 이는 이러한 리소스를 일반적으로 변경하는 데 사용되지 않습니다.