Provider Managed Kubernetes and Driver API - cloud-barista/cb-spider GitHub Wiki

PMKS(Provider Managed Kubernetes) and Driver API

- CB-Spider PMKS(Provider Managed Kubernetes) Specification V0.5
- V0.5 : WebTool(CB-Waterstrider) 통합 개발 용

검토의견: https://github.com/cloud-barista/cb-spider/issues/716
제공현황: PMKS 개발 및 이슈 현황

1. CB-Spider PMKS Overview

CB-Spider는 연동 대상 클라우드(CSP)가 제공하는 관리형 K8S(Provider Managed K8S 또는 Managed K8S)를
- 동일한 인터페이스를 사용하여 제어할 수 있는 PMKS 제어 기능을 제공한다.
K8S가 필요한 CB-Spider 사용자(인프라 관리자 또는 서비스 개발자)는 아래 그림과 같이,
- ① CB-Spider 인터페이스를 활용하여 동일한 방법으로
  - 원하는 대상 클라우드에 K8S 인스턴스 생성을 요청할 수 있다.
- ② 사용자의 요청은 Spider의 대상 연동 드라이버를 통해서
  - 대상 클라우드의 API를 호출하여 대상 클라우드의 관리형 K8S 인스턴스가 생성된다.
- ③ 사용자는 생성된 K8S에 대하여 K8S CLI(kubectl) 또는 API 등의 풍부한 K8S 인터페이스를 사용하여
  - 사용자의 워크로드를 배포 및 관리할 수 있다.
  - 또한, Lens 및 Kubesphere와 같은 K8S IDE에 연동하여 생성된 K8S의 기능을 편리하게 활용할 수도 있다.

2. CB-Spider PMKS Components

사용자에 의해 생성된 하나의 PMKS 인스턴스는 아래 그림에서 보는 바와 같이 Cluster라고 한다.
Cluster는 크게 Control plane, Node Group, Addons 및 Endpoint로 구성된다.

컴포넌트별 세부 내용은 다음과 같다.

(1) 컨트롤 플레인(Control Plane)

- 컨트롤 플레인은 Cluster의 전체 동작 및 실행을 관장하는 마스터로서의 역할을 담당하는 컴포넌트들의 모임이며, 
- 관리형 K8S의 경우에는 컨트롤 플레인의 관리 주체는 CSP의 Cloud 플랫폼(CloudOS)이며,
- CSP 사용자(=CB-Spider 사용자)는 상태 확인 및 제어를 할 수 없다.
- 참고로, Control plane은 kube-apiserver, etcd, kube-scheduler 및 kube-controller-manager, Cloud Controller Manager 등으로 구성된다.

(2) 노드 그룹(Node Group)

- 하나의 노드 그룹은 동일한 이미지와 규격으로 생성된 VM들로 구성되며, 
- 하나의 Cluster는 서로 다른 종류의 여러 개의 노드 그룹을 포함할 수 있다. 
- 이와 같은 이질적인 노드 그룹 구성을 통하여 하나의 Cluster에서 다양한 종류의 워크로드의 실행 설정이 가능하다. 
- 참고로, Node(=VM)은 컨트롤 플레인과의 협업 및 실제 Pod의 실행 처리 등을 위하여 kubelet, kube-proxy 및 Container runtime 등을 포함한다.

(3) 에드온(Addons)

- 에드온은 CNI, DNS 및 Container Resource Monitoring 등으로 
- Cluster 수준의 기능을 제공하는 컴포넌트다.
- 다양한 에드온들이 존재하며, 선택적으로 구성하여 활용할 수 있다.

(4) 엔드포인트(Endpoint)

- 외부에서 Cluster에 접근할 수 있는 URL을 제공한다.

참고: CSP별 특징 및 제약 사항은 다음 참고
- https://docs.google.com/spreadsheets/d/1mPmfnfmyszYimVzplZMzsqO3WsBmOdes/edit#gid=1299745060
- 참고: 노드 그룹 OS로 선택 가능한 이미지 목록
  - Tencent: 다음 목록에서 OS Name을 ImageId로 설정
    - https://www.tencentcloud.com/document/product/457/46750

3. 드라이버 개발 노트

PMKS Driver API는 Async 호출 방식으로 제공
- 예시) CSP Create API 호출 후 Running 상태 기다림 없이 Driver API도 반환
Zonal vs Regional 관련 선택 옵션 제공하는 경우
- 현재는 Zonal로 설정, Zone 값은 Connection에서 획득 후 적용
Cluster 생성과 NodeGroup 추가 관련
- Type-I: Cluster 생성 후 NodeGroup 별도 추가/삭제
  - 대상 CSP: Tencent, Alibaba 등
- Type-II: 최초 Cluster 생성시 최소 1개 이상의 NodeGroup을 함께 생성
  - 이후 NodeGroup 추가/삭제 가능
  - 대상 CSP: Azure, NHN 등
Version 관련
- 1.21(AWS), 1.21.6-gke.1500(GCP), v1.23.3(NHN) 등 CSP별로 차이가 있음
- Driver는 "" 또는 "default"를 수신하면, CSP가 default 버전으로 생성하는 처리 지원하면 default 생성 처리,
  - 제공하지 않는 경우는 현 시점의 대상 CSP Web Console 기준 default 값으로 생성
- ~~버전 값을 입력 받으면~~ -~~현재: 1.23.3 형식으로 입력 받음, driver에서는 1.23.3 정보에서 유효한 정보를 파싱 후 활용,~~
  - ~~그 외 정보는 CSP의 default에 가까운 값으로 설정~~
- GCP: Region별 제공 버전이 다름
  - 2022/12/08: 일단, default("" or "default")만 제공
PMKS는 VPC 의존적이다. 즉, 특정 VPC에 소속되는 관리형 K8S를 생성 및 구성할 수 있다.
사용자는 PMKS 생성 요청 전에 필요한 VPC/Subnet 및 Security Group을 적절하게 생성 하여 인자로 함께 호출함을 가정한다.
- AWS의 경우 사전에 Role의 생성이 필요하며, 현재는 role 이름을 다음 이름으로 일치 시킨다.(추후 필요시 개선)
  - Cluster: cloud-barista-spider-eks-cluster-role
  - NodeGroup: cloud-barista-spider-eks-nodegroup-role
- 추가로 사전 생성이 필요한 자원이 있는 CSP는 상단 링크의 이슈에 현황을 공유 부탁드립니다.
IP Address Family의 경우 Driver 내부에서 IPv4로 설정한다. (IPv6 필요시 추후 고려)
공통 API에서 제공되지 않는 설정일 경우는 상단 링크의 이슈에 현황을 공유하고,
- Driver 내에서 기본 값(최신 버전 등 가급적 CSP의 default 값 활용)으로 설정 처리해 주시기 바랍니다. (추후 개선)
- 예시) AWS에서 kube-proxy version 값 등
NodeGroup의 Node(VM) 제공 정보 범위
- IID(SystemId만 포함) 목록만 반환
Cluster Access 정보 제공
- Endpoint URL 제공
- Kubeconfig 정보 제공
Addons 설정 관련: cni, dns 등 설정 API 존재시 이슈 공유 및 현재는 default 설정, 추후 재고려
Upgrade Cluster: Cluster Version을 업그레이드한다.
PMKS는 주로 공통 API를 이용한 Cluster 관리 중심의 제어 기능을 제공하며,
- 사용자는 Addon 설치/관리, Workload deploy 및 모니터링이나 Taint, Tag, Label 설정 등과 같은
- K8S 활용 자체는 K8S kubectl과 K8S 인터페이스 또는 Lens와 같은 Third party 지원 도구를 활용한다.
Tag, Key-Value 기록 규칙
- CSP가 제공하지 않는 정보 기록이 필요하여,
- Tagging이나 Description에 기록이 필요한 경우
- 가급적 다음 규칙을 따른다.
  - #CB-SPIDER:PMKS:SECURITYGROUP:sg-01
  - 참고: https://github.com/cloud-barista/cb-spider/blob/cea4014f20da0c793537c9e03469ffc8fd080190/cloud-control-manager/cloud-driver/drivers/tencent/resources/ClusterHandler.go#L400
그 외에 대상 CSP Driver 개발시 부족한 부분이 있으시면 이슈에 공유 부탁 드립니다.

4. PMKS Driver Common API

Source Tree

$tree cb-spider/cloud-control-manager/cloud-driver/interfaces/
cb-spider/cloud-control-manager/cloud-driver/interfaces/
|-- CloudDriver.go
|-- README.md
|-- connect
|   `-- CloudConnect.go
`-- resources
    |-- AnyCallHandler.go
    |-- ClusterHandler.go  <======================= PMKS Driver API
    |-- DiskHandler.go
    |-- IId.go
    |-- ImageHandler.go
    |-- KeyPairHandler.go
    |-- KeyValue.go
    |-- MyImageHandler.go
    |-- NLBHandler.go
    |-- SecurityHandler.go
    |-- VMHandler.go
    |-- VMSpecHandler.go
    `-- VPCHandler.go

Driver API Spec (latest)

package resources

import "time"

// -------- Const
type ClusterStatus string

const (
	ClusterCreating ClusterStatus = "Creating"
	ClusterActive   ClusterStatus = "Active"
	ClusterInactive ClusterStatus = "Inactive"
	ClusterUpdating ClusterStatus = "Updating"
	ClusterDeleting ClusterStatus = "Deleting"
)

type NodeGroupStatus string

const (
	NodeGroupCreating NodeGroupStatus = "Creating"
	NodeGroupActive   NodeGroupStatus = "Active"
	NodeGroupInactive NodeGroupStatus = "Inactive"
	NodeGroupUpdating NodeGroupStatus = "Updating"
	NodeGroupDeleting NodeGroupStatus = "Deleting"
)

// -------- Info Structure
type ClusterInfo struct {
	IId IID // {NameId, SystemId}

	Version string // Kubernetes Version, ex) 1.23.3
	Network       NetworkInfo

	// ---

	NodeGroupList []NodeGroupInfo
	AccessInfo    AccessInfo
	Addons        AddonsInfo

	Status        ClusterStatus

	CreatedTime  time.Time
	KeyValueList []KeyValue
}

type NetworkInfo struct {
	VpcIID            IID // {NameId, SystemId}
	SubnetIIDs        []IID
	SecurityGroupIIDs []IID

	// ---

	KeyValueList []KeyValue
}

type NodeGroupInfo struct {
	IId IID // {NameId, SystemId}

	// VM config.
	ImageIID     IID
	VMSpecName   string
	RootDiskType string // "SSD(gp2)", "Premium SSD", ...
	RootDiskSize string // "", "default", "50", "1000" (GB)
	KeyPairIID   IID

	// Scaling config.
	OnAutoScaling   bool // default: true
	DesiredNodeSize int
	MinNodeSize     int
	MaxNodeSize     int

	// ---

	Status       NodeGroupStatus
	Nodes        []IID

	KeyValueList []KeyValue
}

type AccessInfo struct {
	Endpoint 	string // ex) https://1.2.3.4:6443
	Kubeconfig	string
}

// CNI, DNS, .... @todo
type AddonsInfo struct {
	KeyValueList []KeyValue
}

// -------- Cluster API
type ClusterHandler interface {

	//------ Cluster Management
	CreateCluster(clusterReqInfo ClusterInfo) (ClusterInfo, error)
	ListCluster() ([]*ClusterInfo, error)
	GetCluster(clusterIID IID) (ClusterInfo, error)
	DeleteCluster(clusterIID IID) (bool, error)

	//------ NodeGroup Management
	AddNodeGroup(clusterIID IID, nodeGroupReqInfo NodeGroupInfo) (NodeGroupInfo, error)
	SetNodeGroupAutoScaling(clusterIID IID, nodeGroupIID IID, on bool) (bool, error)
	ChangeNodeGroupScaling(clusterIID IID, nodeGroupIID IID,
		DesiredNodeSize int, MinNodeSize int, MaxNodeSize int) (NodeGroupInfo, error)
	RemoveNodeGroup(clusterIID IID, nodeGroupIID IID) (bool, error)

	//------ Upgrade K8S
	UpgradeCluster(clusterIID IID, newVersion string) (ClusterInfo, error)
}

5. CB-Spider PMKS(Provider Managed Kubernetes) REST API 규격

v0.7.0+ API Spec 참고

History

- V0.4 => V0.5
  - ClusterInfo.AccessInfo 추가
- V0.3 => V0.4
  - 불필요 API 삭제 (#794)
  - 삭제 API: ListNodeGroup(), GetNodeGroup()
- V0.2 => V0.3
  - Attribute Naming 규칙 반영 (#786)
    - SubnetIID => SubnetIIDs
    - NodeList => Nodes
- V0.1 => V0.2
  - Cluster 생성시 default NodeGroup 동시 생성
  - 독립적이던 NodeGroup 생성 및 관리를 특정 Cluster 하에서 관리
  - NodeGroup Size 관리를 Autoscaling 방법으로만 제공
  - NodeGroupHandler를 ClusterHandler 안으로 통합
  - NodeGroup.Status 추가
  - NodeGroup AutoScaling On/Off 설정 API 추가