"Cluster API - 부트스트랩 제공자 사양"의 두 판 사이의 차이

(새 문서: ==개요== ;Bootstrap Provider Specification ;부트스트랩 프로바이더 사양 https://cluster-api.sigs.k8s.io/developer/providers/bootstrap ---- ==데이터 타입== ===Bootstr...)
 
 
(같은 사용자의 중간 판 14개는 보이지 않습니다)
1번째 줄: 1번째 줄:
==개요==
==개요==
[[분류: Cluster API]]
;Bootstrap Provider Specification
;Bootstrap Provider Specification
;부트스트랩 프로바이더 사양
;부트스트랩 제공자 사양
https://cluster-api.sigs.k8s.io/developer/providers/bootstrap
https://cluster-api.sigs.k8s.io/developer/providers/bootstrap
----
----
부트스트랩 제공자는 Kubernetes 노드를 부트스트랩하는 데 사용되는 부트스트랩 데이터를 생성합니다.
예를 들어, Kubeadm 부트스트랩 제공자는 노드를 부트스트랩하기 위해 [[cloud-init]] 파일을 사용합니다.
==데이터 타입==
==데이터 타입==
===Bootstrap API resource===
===부트스트랩 API 리소스===
===BootstrapTemplate Resources===
부트스트랩 제공자는 부트스트랩 리소스를 위한 API 타입을 정의해야 합니다. 이 타입은 다음과 같은 조건을 만족해야 합니다:
===List Resources===
* 1. 쿠버네티스 API 서버에서 제공하는 API 그룹에 속해야 합니다.
===Bootstrap Secret===
* 2. CustomResourceDefinition(CRD)으로 구현되어야 합니다.
==Behavior==
** CRD 이름은 <code>sigs.k8s.io/cluster-api/util/contract.CalculateCRDName(Group, Kind)</code>에서 생성된 형식을 가져야 합니다.
==Sentinel File===
* 3. 네임스페이스 스코프여야 합니다.
==Taint Nodes at creation===
* 4. 표준 쿠버네티스 "타입 메타데이터"와 "객체 메타데이터"를 가져야 합니다.
* 5. 부트스트랩 프로바이더와 관련된 필드를 포함하는 <code>spec</code> 필드가 있어야 합니다.
* 6. 다음과 같은 필드가 포함된 <code>status</code> 필드가 있어야 합니다:
** 필수 필드:
*** <code>ready</code> (boolean): 부트스트랩 데이터가 생성되어 준비되었음을 나타냅니다.
*** <code>dataSecretName</code> (string): 생성된 부트스트랩 데이터를 저장하는 비밀(Secret)의 이름입니다.
** 선택적 필드:
*** <code>failureReason</code> (string): 부트스트랩 데이터를 조정하는 데 치명적인 문제가 있음을 나타내며, 프로그래밍적으로 해석하기 적합한 값이어야 합니다.
*** <code>failureMessage</code> (string): 부트스트랩 데이터를 조정하는 데 치명적인 문제가 있음을 나타내며, <code>failureReason</code>보다 더 설명적인 값이어야 합니다.
 
참고: <code>dataSecretName</code>은 <code>status</code>의 일부이기 때문에 <code>Cluster</code>, <code>Machine</code> 및/또는 부트스트랩 리소스의 데이터에서 결정적으로 재생성할 수 있어야 합니다. 이름이 무작위로 생성되는 경우 리소스와 관련된 비밀을 한 관리 클러스터에서 다른 클러스터로 이동하는 것이 항상 가능하지는 않습니다.
 
===BootstrapTemplate 리소스===
Bootstrap 리소스에 대해, 해당하는 BootstrapTemplate 리소스를 추가해야 합니다:
 
<syntaxhighlight lang='go'>
// 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"`
}
</syntaxhighlight>
 
템플릿의 CRD 이름은 <code>sigs.k8s.io/cluster-api/util/contract.CalculateCRDName(Group, Kind)</code>에서 생성된 형식을 가져야 합니다.
 
===List 리소스===
리소스가 있다면, 그에 대한 리스트 리소스도 추가합니다. 예시:
 
<syntaxhighlight lang='go'>
//+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"`
}
</syntaxhighlight>
 
===부트스트랩 시크릿===
부트스트랩 데이터가 포함된 <code>Secret</code>은 다음 조건을 충족해야 합니다:
* 1. API 리소스의 <code>status.dataSecretName</code>을 이름으로 사용해야 합니다.
* 2. <code>cluster.x-k8s.io/cluster-name</code> 레이블이 클러스터 이름으로 설정되어 있어야 합니다.
* 3. API 리소스에 대한 컨트롤러 소유자 참조를 가져야 합니다.
* 4. 부트스트랩 데이터를 포함하는 단일 key, value를 가져야 합니다.
 
==동작==
부트스트랩 제공자는 부트스트랩 리소스의 변경사항에 대응해야 합니다. 이 과정은 일반적으로 맞춤조정(reconciliation)이라고 합니다. 제공자는 신규, 업데이트, 삭제된 리소스를 감시하고 적절히 대응해야 합니다.
 
다음 다이어그램은 부트스트랩 제공자의 일반적인 로직을 보여줍니다:
 
[[파일: bootstrap-provider.png]]
 
* 1. 리소스에 머신 소유자가 없는 경우, 맞춤조정에서 종료합니다.
** 클러스터 API 머신 맞춤조정자는 <code>Machine</code>의 <code>spec.bootstrap.configRef</code> 필드의 값을 기반으로 이를 채웁니다.
* 2. 리소스에 <code>status.failureReason</code> 또는 <code>status.failureMessage</code>가 설정된 경우, 맞춤조정에서 종료합니다.
* 3. 이 리소스가 속한 <code>Cluster</code>를 찾을 수 없는 경우, 맞춤조정에서 종료합니다.
* 4. 부트스트랩 데이터 시크릿의 이름을 결정적으로 생성합니다.
* 5. 이전 단계에서 생성된 이름으로 <code>Secret</code>을 조회하려고 시도합니다.
** 존재하지 않는 경우, 부트스트랩 데이터를 생성하고 <code>Secret</code>을 생성합니다.
* 6. <code>status.dataSecretName</code>에 생성된 이름을 세팅합니다.
* 7. <code>status.ready</code>를 true로 세팅합니다.
* 8 .리소스를 패치하여 변경사항을 영구적으로 저장합니다.
 
==센티널 파일==
부트스트랩 제공자의 부트스트랩 데이터는 Kubernetes 노드의 부트스트래핑이 성공적으로 완료되면 <code>/run/cluster-api/bootstrap-success.complete</code>(Windows 머신의 경우 <code>C:\run\cluster-api\bootstrap-success.complete</code>)를 생성해야 합니다. 이를 통해 인프라 제공자는 부트스트랩 실패를 감지하고 조치할 수 있습니다.
 
==생성 시 노드 테인트==
부트스트랩 공급자는 선택적으로 워커 노드가 생성될 때 <code>node.cluster.x-k8s.io/uninitialized:NoSchedule</code> 테인트를 추가할 수 있습니다. 이 테인트은 클러스터 API에 의해 노드가 초기화되기 전에 워크로드가 노드에 예약되는 것을 방지하기 위해 사용됩니다. 현재 노드 초기화는 머신에서 노드로 레이블을 동기화하는 작업으로 구성됩니다. 레이블이 초기 동기화되면 노드에서 테인트가 제거됩니다.
 
==RBAC==
==RBAC==
===Provider controller===
===제공자 컨트롤러===
===Cluster API controllers===
부트스트랩 제공자는 정의한 타입뿐만 아니라 관리하는 부트스트랩 데이터 <code>Secret</code> 리소스에 대한 RBAC 권한이 필요합니다. <code>kubebuilder</code>를 사용하여 새 API 타입을 생성하는 경우 이러한 권한은 자동으로 설정됩니다. 예를 들어, Kubeadm 부트스트랩 제공자는 <code>KubeadmConfig</code> 타입에 대해 다음과 같은 설정을 사용합니다:
 
<syntaxhighlight lang='go'>
// +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
</syntaxhighlight>
 
부트스트랩 제공자는 또한 <code>Cluster</code>와 같은 다른 타입에 대한 RBAC 권한이 필요할 수 있습니다. 읽기 전용 액세스가 필요한 경우 권한을 <code>get</code>, <code>list</code>, <code>watch</code>로 제한할 수 있습니다. <code>Cluster</code> 리소스를 조회하기 위해 다음 설정을 사용할 수 있습니다:
 
<syntaxhighlight lang='go'>
// +kubebuilder:rbac:groups=cluster.x-k8s.io,resources=clusters;clusters/status,verbs=get;list;watch
</syntaxhighlight>
 
===Cluster API 컨트롤러===
<code>Machine</code> 리소스에 대한 Cluster API 컨트롤러는 <code>bootstrap.cluster.x-k8s.io</code> API 그룹의 모든 리소스에 대해 읽기/쓰기 RBAC 권한으로 설정됩니다. 이 그룹은 SIG Cluster Lifecycle에서 후원하는 제공자 하위 프로젝트의 모든 부트스트랩 제공자를 나타냅니다. 만약 SIG에서 후원하지 않는 제공자를 작성하고 있다면, 귀하의 API 그룹에서 부트스트랩 리소스에 대한 읽기/쓰기 액세스를 부여하는 새로운 RBAC 권한을 Cluster API <code>manager-role</code> 역할에 추가해야 합니다.
 
참고로, 쓰기 권한은 <code>Machine</code> 컨트롤러가 부트스트랩 리소스에 소유자 참조와 레이블을 설정할 수 있도록 허용합니다. 이는 이러한 리소스를 일반적으로 변경하는 데 사용되지 않습니다.

2024년 7월 17일 (수) 01:45 기준 최신판

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보다 더 설명적인 값이어야 합니다.

참고: dataSecretNamestatus의 일부이기 때문에 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)이라고 합니다. 제공자는 신규, 업데이트, 삭제된 리소스를 감시하고 적절히 대응해야 합니다.

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

Bootstrap-provider.png

  • 1. 리소스에 머신 소유자가 없는 경우, 맞춤조정에서 종료합니다.
    • 클러스터 API 머신 맞춤조정자는 Machinespec.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 컨트롤러가 부트스트랩 리소스에 소유자 참조와 레이블을 설정할 수 있도록 허용합니다. 이는 이러한 리소스를 일반적으로 변경하는 데 사용되지 않습니다.

문서 댓글 ({{ doc_comments.length }})
{{ comment.name }} {{ comment.created | snstime }}