如何在Kubernetes 裡新增自定義的 API 物件（一）

茁壯的小草發表於2022-02-14
API物件

環境：

golang 1.15 依賴包採用go module

例項：現在往 Kubernetes 新增一個名叫 Network 的 API 資源型別。它的作用是，一旦使用者建立一個 Network 物件，那麼 Kubernetes 就應該使用這個物件定義的網路引數，呼叫真實的網路外掛，為使用者建立一個真正的“網路”。這樣，將來使用者建立的 Pod，就可以宣告使用這個“網路”了。

結構如下：

MacBook-Pro kubernetes % tree k8s-controller-custom-resource -L 5

├── go.mod
├── hack
│   ├── boilerplate.go.txt
│   ├── tools.go
│   └── update-codegen.sh
├── pkg
│   └── apis
│       └── samplecrd
│           ├── register.go
│           └── v1
│               ├── doc.go
│               ├── register.go
│               └── types.go

1、初始化專案

#建立目錄
$ mkdir k8s-controller-custom-resource && cd k8s-controller-custom-resource
#初始化專案，生成go.mod檔案
$ go mod init k8s-controller-custom-resource
# 獲取依賴
$ go get k8s.io/apimachinery@v0.0.0-20190425132440-17f84483f500
$ go get k8s.io/client-go@v0.0.0-20190425172711-65184652c889
$ go get k8s.io/code-generator@v0.0.0-20190419212335-ff26e7842f9d

2、初始化crd資源型別

在初始化了專案後,需要建立好自己的crd struct,然後使用code-generator生成我們的程式碼.

mkdir -p pkg/apis/samplecrd/v1 && cd pkg/apis/samplecrd

其中，pkg/apis/samplecrd 就是 API 組的名字，v1 是版本。

然後，我在 pkg/apis/samplecrd 目錄下建立了一個 register.go 檔案，用來放置後面要用到的全域性變數。這個檔案的內容如下所示：


package samplecrd

const (
 GroupName = "samplecrd.k8s.io"
 Version   = "v1"
)

接著，我需要在 pkg/apis/samplecrd/v1 目錄下新增一個 doc.go 檔案（Golang 的文件原始檔）。這個檔案裡的內容如下所示：


// +k8s:deepcopy-gen=package

// +groupName=samplecrd.k8s.io
package v1

在這個檔案中，你會看到 +<tag_name>[=value]格式的註釋，這就是 Kubernetes 進行程式碼生成要用的 Annotation 風格的註釋。其中，+k8s:deepcopy-gen=package 意思是，請為整個 v1 包裡的所有型別定義自動生成 DeepCopy 方法；而+groupName=samplecrd.k8s.io，則定義了這個包對應的 API 組的名字。可以看到，這些定義在 doc.go 檔案的註釋，起到的是全域性的程式碼生成控制的作用，所以也被稱為 Global Tags。 

接下來，我需要新增 types.go 檔案。顧名思義，它的作用就是定義一個 Network 型別到底有哪些欄位（比如，spec 欄位裡的內容）。這個檔案的主要內容如下所示：

package v1

import (
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

// +genclient
// +genclient:noStatus
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object

// Network describes a Network resource
type Network struct {
	// TypeMeta is the metadata for the resource, like kind and apiversion
	metav1.TypeMeta `json:",inline"`
	// ObjectMeta contains the metadata for the particular object, including
	// things like...
	//  - name
	//  - namespace
	//  - self link
	//  - labels
	//  - ... etc ...
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// Spec is the custom resource spec
	Spec NetworkSpec `json:"spec"`
}

// NetworkSpec is the spec for a Network resource
type NetworkSpec struct {
	// Cidr and Gateway are example custom spec fields
	//
	// this is where you would put your custom resource data
	Cidr    string `json:"cidr"`
	Gateway string `json:"gateway"`
}

// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object

// NetworkList is a list of Network resources
type NetworkList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata"`

	Items []Network `json:"items"`
}

最後，我需要再編寫一個 pkg/apis/samplecrd/v1/register.go 檔案。

package v1

import (
	"k8s-controller-custom-resource/pkg/apis/samplecrd"

	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"

	"k8s.io/apimachinery/pkg/runtime"
	"k8s.io/apimachinery/pkg/runtime/schema"
)

// GroupVersion is the identifier for the API which includes
// the name of the group and the version of the API
var SchemeGroupVersion = schema.GroupVersion{
	Group:   samplecrd.GroupName,
	Version: samplecrd.Version,
}

// addKnownTypes adds our types to the API scheme by registering
// Network and NetworkList
func addKnownTypes(scheme *runtime.Scheme) error {
	scheme.AddKnownTypes(
		SchemeGroupVersion,
		&Network{},
		&NetworkList{},
	)

	// register the type in the scheme
	metav1.AddToGroupVersion(scheme, SchemeGroupVersion)
	return nil
}

這樣，Network 物件的定義工作就全部完成了。可以看到，它其實定義了兩部分內容：

第一部分是，自定義資源型別的 API 描述，包括：組（Group）、版本（Version）、資源型別（Resource）等。

第二部分是，自定義資源型別的物件描述，包括：Spec、Status 等。 

3、使用 Kubernetes 提供的程式碼生成工具，為上面定義的 Network 資源型別自動生成 clientset、informer 和 lister。

生成程式碼主要為下一章的controller使用。其中，clientset 就是操作 Network 物件所需要使用的客戶端，而 informer 和 lister 這兩個包的主要功能，我會在下一篇文章中重點講解。這個程式碼生成工具名叫k8s.io/code-generator，使用方法如下所示：

  • 在專案跟路徑建立目錄
mkdir hack && cd hack
  • 建立tools.go來依賴code-generator,因為在沒有程式碼使用code-generator時,go module 預設不會為我們依賴此包
// +build tools

/*
Copyright 2019 The Kubernetes Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

// This package imports things required by build scripts, to force `go mod` to see them as dependencies
package tools

import _ "k8s.io/code-generator"
  • 編寫構建指令碼：update-codegen.sh
#!/usr/bin/env bash

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

set -o errexit
set -o nounset
set -o pipefail

# generate the code with:
# --output-base    because this script should also be able to run inside the vendor dir of
#                  k8s.io/kubernetes. The output-base is needed for the generators to output into the vendor dir
#                  instead of the $GOPATH directly. For normal projects this can be dropped.
../vendor/k8s.io/code-generator/generate-groups.sh \
  "deepcopy,client,informer,lister" \
  k8s-controller-custom-resource/pkg/client \
  k8s-controller-custom-resource/pkg/apis \
  samplecrd:v1 \
  --go-header-file $(pwd)/boilerplate.go.txt \
  --output-base $(pwd)/../../
  • 在構建api時,我們還提供了檔案頭,所以我們在此也建立檔案頭:boilerplate.go.txt
/*
Copyright The Kubernetes Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
  • 生成程式碼
# 生成vendor資料夾
$ go mod vendor
# 進入專案根目錄,為vendor中的code-generator賦予許可權
$ chmod -R 777 vendor
# 呼叫指令碼生成程式碼
MacBook-Pro hack % ./update-codegen.sh
Generating deepcopy funcs
Generating clientset for samplecrd:v1 at k8s-controller-custom-resource/pkg/client/clientset
Generating listers for samplecrd:v1 at k8s-controller-custom-resource/pkg/client/listers
Generating informers for samplecrd:v1 at k8s-controller-custom-resource/pkg/client/informers

程式碼生成工作完成之後，我們再檢視一下這個專案的目錄結構：

├── go.mod
├── go.sum
├── hack
│   ├── boilerplate.go.txt
│   ├── tools.go
│   └── update-codegen.sh
├── pkg
│   ├── apis
│   │   └── samplecrd
│   │       ├── register.go
│   │       └── v1
│   │           ├── doc.go
│   │           ├── register.go
│   │           ├── types.go
│   │           └── zz_generated.deepcopy.go
│   └── client
│       ├── clientset
│       ├── informers
│       └── listers

 其中，pkg/apis/samplecrd/v1 下面的 zz_generated.deepcopy.go 檔案，就是自動生成的 DeepCopy 程式碼檔案。而整個 client 目錄，以及下面的三個包（clientset、informers、 listers），都是 Kubernetes 為 Network 型別生成的客戶端庫，這些庫會在後面編寫自定義控制器的時候用到。

4、在 Kubernetes 叢集裡建立一個 Network 型別的 API 物件

  • 建立CRD yaml檔案：network.yaml

apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
  name: networks.samplecrd.k8s.io
spec:
  group: samplecrd.k8s.io
  version: v1
  names:
    kind: Network
    plural: networks
  scope: Namespaced

然後在k8s中建立crd，這個操作，就告訴了 Kubernetes，我現在要新增一個自定義的 API 物件。而這個物件的 API 資訊，正是 network.yaml 裡定義的內容。我們可以通過 kubectl get 命令，檢視這個 CRD：

MacBook-Pro k8s-controller-custom-resource % k8sdev apply -f crd/network.yaml
customresourcedefinition.apiextensions.k8s.io/networks.samplecrd.k8s.io created

MacBook-Pro k8s-controller-custom-resource % k8sdev get crd
NAME                                  CREATED AT
networks.samplecrd.k8s.io             2022-02-14T08:50:46Z
  • 建立Network 物件的 YAML 檔案，名叫 example-network.yaml

apiVersion: samplecrd.k8s.io/v1
kind: Network
metadata:
  name: example-network
spec:
  cidr: "192.168.0.0/16"
  gateway: "192.168.0.1"

在k8s中建立 Network 物件

MacBook-Pro k8s-controller-custom-resource % k8sdev apply -f example/example-network.yaml
network.samplecrd.k8s.io/example-network created

通過這個操作，就在 Kubernetes 叢集裡建立了一個 Network 物件。它的 API 資源路徑是samplecrd.k8s.io/v1/networks。

這時候，你就可以通過 kubectl get 命令，檢視到新建立的 Network 物件：

MacBook-Pro k8s-controller-custom-resource % k8sdev get network
NAME              AGE
example-network   69s

你還可以通過 kubectl describe 命令，看到這個 Network 物件的細節：

MacBook-Pro k8s-controller-custom-resource % k8sdev describe network  example-network
Name:         example-network
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  samplecrd.k8s.io/v1
Kind:         Network
Metadata:
  Creation Timestamp:  2022-02-14T08:57:58Z
  Generation:          1
  Resource Version:    34001215910
  Self Link:           /apis/samplecrd.k8s.io/v1/namespaces/default/networks/example-network
  UID:                 d2a3b4d8-4000-473d-976e-cf6acb050942
Spec:
  Cidr:     192.168.0.0/16
  Gateway:  192.168.0.1
Events:     <none>

 

5、總結

在今天這篇文章中，為 Kubernetes 新增一個名叫 Network 的 API 資源型別。從而達到了通過標準的 kubectl create 和 get 操作，來管理自定義 API 物件的目的。不過，建立出這樣一個自定義 API 物件，我們只是完成了 Kubernetes 宣告式 API 的一半工作。

接下來的另一半工作是：為這個 API 物件編寫一個自定義控制器（Custom Controller）。這樣， Kubernetes 才能根據 Network API 物件的“增、刪、改”操作，在真實環境中做出相應的響應。比如，“建立、刪除、修改”真正的 Neutron 網路。而這，正是 Network 這個 API 物件所關注的“業務邏輯”。這個業務邏輯的實現過程，以及它所使用的 Kubernetes API 程式設計庫的工作原理，就是在下一篇文章中主要內容。

 

 

參考：

code-generator使用

k8s-controller-custom-resource

 

相關文章