k8s自定义资源案例

k8s自定义资源: 使用Kubebuilder 与 code-generator生成代码

1. 安装kubebuilder

依赖组件:
go version v1.17+
docker version 20.10.10
kubectl version v1.25
kustomize version v4.5.7

kustomize使用git执行如下操作:
[root@kubebuilder example]# git clone [email protected]:kubernetes-sigs/kustomize.git
[root@kubebuilder example]# cd kustomize
[root@kubebuilder example]# git checkout kustomize/v4.5.2
[root@kubebuilder example]# go install .
[root@kubebuilder example]# mv kustomize /usr/local/bin/

安装组件
Kubebuilder使用controller-gen工具来生成程序代码和Kubernetes的YAML对象,比如CustomResourceDefinitions,同时使用了Kustomize工具通过kustomization文件定制kubernetes对象。因此我们需要安装kubebuilder, kind, controller-gen, kustomize及设置goproxy。

wget https://github.com/kubernetes-sigs/kubebuilder/releases/download/v3.3.0/kubebuilder_linux_amd64
wget https://github.com/kubernetes-sigs/kind/releases/download/v0.12.0/kind-linux-amd64
curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh"  | bash
mv kubebuilder_linux_amd64 /usr/local/bin/kubebuilder
mv kind-linux-amd64 /usr/local/bin/kind
export GOPROXY=https://proxy.golang.com.cn,direct

创建集群
使用kind创建一个kubernetes集群

[root@kubebuilder example]# kind create cluster --name local --image kindest/node:v1.23.5
[root@kubebuilder example]# kind get kubeconfig --name local >~/.kube/config

2. 初始化项目

  1. 创建项目
[root@kubebuilder example]# mkdir -p $GOPATH/src/my.domain/example
[root@kubebuilder example]# cd $GOPATH/src/my.domain/example
[root@kubebuilder example]# go mod init example
[root@kubebuilder example]# kubebuilder init --domain my.domain 
[root@kubebuilder example]# tree -CL 3
.
├── config
│   ├── default
│   │   ├── kustomization.yaml
│   │   ├── manager_auth_proxy_patch.yaml
│   │   └── manager_config_patch.yaml
│   ├── manager
│   │   ├── controller_manager_config.yaml
│   │   ├── kustomization.yaml
│   │   └── manager.yaml
│   ├── prometheus
│   │   ├── kustomization.yaml
│   │   └── monitor.yaml
│   └── rbac
│       ├── auth_proxy_client_clusterrole.yaml
│       ├── auth_proxy_role_binding.yaml
│       ├── auth_proxy_role.yaml
│       ├── auth_proxy_service.yaml
│       ├── kustomization.yaml
│       ├── leader_election_role_binding.yaml
│       ├── leader_election_role.yaml
│       ├── role_binding.yaml
│       └── service_account.yaml
├── Dockerfile
├── go.mod
├── go.sum
├── hack
│   └── boilerplate.go.txt
├── main.go
├── Makefile
└── PROJECT
  1. 创建api
[root@kubebuilder example]# kubebuilder create api --group example --version v1 --kind Guestbook
Create Resource [y/n]
y
Create Controller [y/n]
y
...

tree -CL 3
.
├── api
│   └── v1
│       ├── groupversion_info.go
│       ├── guestbook_types.go
│       └── zz_generated.deepcopy.go
├── bin
│   └── controller-gen
├── config
│   ├── crd
│   │   ├── kustomization.yaml
│   │   ├── kustomizeconfig.yaml
│   │   └── patches
│   ├── default
│   │   ├── kustomization.yaml
│   │   ├── manager_auth_proxy_patch.yaml
│   │   └── manager_config_patch.yaml
│   ├── manager
│   │   ├── controller_manager_config.yaml
│   │   ├── kustomization.yaml
│   │   └── manager.yaml
│   ├── prometheus
│   │   ├── kustomization.yaml
│   │   └── monitor.yaml
│   ├── rbac
│   │   ├── auth_proxy_client_clusterrole.yaml
│   │   ├── auth_proxy_role_binding.yaml
│   │   ├── auth_proxy_role.yaml
│   │   ├── auth_proxy_service.yaml
│   │   ├── guestbook_editor_role.yaml
│   │   ├── guestbook_viewer_role.yaml
│   │   ├── kustomization.yaml
│   │   ├── leader_election_role_binding.yaml
│   │   ├── leader_election_role.yaml
│   │   ├── role_binding.yaml
│   │   └── service_account.yaml
│   └── samples
│       └── example_v1_guestbook.yaml
├── controllers
│   ├── guestbook_controller.go
│   └── suite_test.go
├── Dockerfile
├── go.mod
├── go.sum
├── hack
│   └── boilerplate.go.txt
├── main.go
├── Makefile
└── PROJECT

注意:
如果修改了 api/v1/guestbook_types.go ,需要执行以下命令来更新代码和manifests:

make && make manifests

3. 使用code-generator

更新依赖版本
初始化项目后的go.mod:

[root@kubebuilder example]# cat go.mod
module example

go 1.16

require (
	github.com/onsi/ginkgo v1.16.4
	github.com/onsi/gomega v1.15.0
	k8s.io/apimachinery v0.22.1
	k8s.io/client-go v0.22.1
	sigs.k8s.io/controller-runtime v0.10.0
)

初始化项目后的go.mod:

[root@kubebuilder example]# K8S_VERSION=v0.18.6
[root@kubebuilder example]# go get k8s.io/client-go@$K8S_VERSION
go: downloading k8s.io/client-go v0.18.6
go: downloading k8s.io/component-base v0.18.6
go: downloading sigs.k8s.io/controller-runtime v0.3.0
go: downloading k8s.io/apiextensions-apiserver v0.15.13-beta.0
go get: downgraded k8s.io/apiextensions-apiserver v0.22.1 => v0.15.13-beta.0
go get: downgraded k8s.io/client-go v0.22.1 => v0.18.6
go get: downgraded k8s.io/component-base v0.22.1 => v0.18.6
go get: downgraded sigs.k8s.io/controller-runtime v0.10.0 => v0.3.0

[root@kubebuilder example]# go get k8s.io/apimachinery@$K8S_VERSION
go: downloading k8s.io/apimachinery v0.18.6
go: downloading k8s.io/api v0.18.6
go get: downgraded k8s.io/api v0.22.1 => v0.18.6
go get: downgraded k8s.io/apimachinery v0.22.1 => v0.18.6

安装code-generator
k8s的版本号与 go.mod 中的 k8s.io/client-go 的版本保持一致即可。
**注意:**需要将依赖复制到vendor中

go get github.com/googleapis/[email protected]
go get k8s.io/code-generator@$K8S_VERSION
或者go get k8s.io/[email protected]
go mod vendor

创建&修改所需文件
需要在api目录下创建code-generator所需的文件,并添加相关注释。

  • 新增 api/v1/doc.go
    **注意:**修改groupName,package与api的version保持一致。
[root@kubebuilder example]# cat api/v1/doc.go
// +k8s:deepcopy-gen=package
  
// Package v1 is the v1alpha1 version of the API.
// +groupName=example.my.domain
package v1
  • 新增 api/v1/register.go
    **注意:**package与api的version保持一致。
[root@kubebuilder example]# cat api/v1/register.go
package v1
  
import (
    "k8s.io/apimachinery/pkg/runtime/schema"
)
  
// SchemeGroupVersion is group version used to register these objects.
var SchemeGroupVersion = GroupVersion
  
// Resource takes an unqualified resource and returns a Group qualified GroupResource
func Resource(resource string) schema.GroupResource {
    return SchemeGroupVersion.WithResource(resource).GroupResource()
}
  • 修改 api/v1/{crd}_types.go 文件,添加注释 // +genclient
cat api/v1/guestbook_types.go
...
// +genclient
//+kubebuilder:object:root=true

// GuestbookList contains a list of Guestbook
type GuestbookList struct {
...

准备脚本
在项目 hack 目录下准备以下文件:

  • 新建 hack/tools.go 文件
[root@kubebuilder example]# cat hack/tools.go
// +build tools
  
package tools
  
import _ "k8s.io/code-generator"
  • 新建 hack/update-codegen.sh,注意根据项目修改相应变量:
    MODULE 和 go.mod 保持一致
    API_PKG=api,和 api 目录保持一致
    OUTPUT_PKG=generated/example,与生成Resource时指定的group保持一致
    GROUP=example, 和生成Resource时指定的group 保持一致
    VERSION=v1, 和生成Resource时指定的version保持一致
[root@kubebuilder example]# cat ./hack/update-codegen.sh
#!/usr/bin/env bash
#表示有报错即退出 跟set -e含义一样
set -o errexit
#执行脚本的时候,如果遇到不存在的变量,Bash 默认忽略它 ,跟 set -u含义一样
set -o nounset
# 只要一个子命令失败,整个管道命令就失败,脚本就会终止执行 
set -o pipefail
  
#kubebuilder项目的MODULE
MODULE=my.domain/example
  
#api包
APIS_PKG=api
  
#代码生出输出,生成Resource时指定的group一样
OUTPUT_PKG=generated/example
  
# group-version such as cronjob:v1
GROUP=example
VERSION=v1
GROUP_VERSION=$GROUP:$VERSION
  
SCRIPT_ROOT=$(dirname "${BASH_SOURCE[0]}")/..
CODEGEN_PKG=${CODEGEN_PKG:-$(cd "${SCRIPT_ROOT}"; ls -d -1 ./vendor/k8s.io/code-generator 2>/dev/null || echo ../code-generator)}
  
# kubebuilder2.3.2版本生成的api目录结构code-generator无法直接使用
rm -rf "${APIS_PKG}/${GROUP}" && mkdir -p "${APIS_PKG}/${GROUP}" && cp -r "${APIS_PKG}/${VERSION}/" "${APIS_PKG}/${GROUP}"
  
# 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.
#client,informer,lister(注意: code-generator 生成的deepcopy不适配 kubebuilder 所生成的api)
bash "${CODEGEN_PKG}"/generate-groups.sh "client,informer,lister" \
  ${MODULE}/${OUTPUT_PKG} ${MODULE}/${APIS_PKG} \
  ${GROUP_VERSION} \
  --go-header-file "${SCRIPT_ROOT}"/hack/boilerplate.go.txt
#  --output-base "${SCRIPT_ROOT}"
#  --output-base "${SCRIPT_ROOT}/../../.."

注意
kubebuilder2.3.2版本生成的api目录结构code-generator无法直接使用,需要在sh脚本中进行处理。
修改脚本执行参数可以选择生成的代码,如:“client,informer,lister”。**注意无需再次生成deepcopy:**code-generator 生成的deepcopy不适配 kubebuilder 所生成的api。
修改 Makefile ,添加生成命令

[root@kubebuilder example]# chmod +x hack/update-codegen.sh 
[root@kubebuilder example]# vim Makefile
 71 update-codegen: ## generetor clientset informer inderx code
 72         ./hack/update-codegen.sh

生成代码
项目根目录下执行make update-codegen即可,将生成如下代码结构:

[root@kubebuilder example]# tree  generated/
generated/
└── example
    ├── clientset
    │   └── versioned
    │       ├── clientset.go
    │       ├── doc.go
    │       ├── fake
    │       │   ├── clientset_generated.go
    │       │   ├── doc.go
    │       │   └── register.go
    │       ├── scheme
    │       │   ├── doc.go
    │       │   └── register.go
    │       └── typed
    │           └── example
    │               └── v1
    │                   ├── doc.go
    │                   ├── example_client.go
    │                   ├── fake
    │                   │   ├── doc.go
    │                   │   ├── fake_example_client.go
    │                   │   └── fake_guestbook.go
    │                   ├── generated_expansion.go
    │                   └── guestbook.go
    ├── informers
    │   └── externalversions
    │       ├── example
    │       │   ├── interface.go
    │       │   └── v1
    │       │       ├── guestbook.go
    │       │       └── interface.go
    │       ├── factory.go
    │       ├── generic.go
    │       └── internalinterfaces
    │           └── factory_interfaces.go
    └── listers
        └── example
            └── v1
                ├── expansion_generated.go
                └── guestbook.go

之后便可以通过clientset等包对自定义资源对象进行操作。

注意事项
kubebuilder2.3.2版本生成的api目录结构为 api/v1,而code-generator需要的api目录结构为 api/example/v1,相比较增加了group这一层。

hack/update-codegen.sh 脚本会自动根据kubebuilder的api生成code-generator所需目录结构。
code-generator 生成的deepcopy不适配 kubebuilder 所生成的api。
code-generator 生成代码后再次使用make操作时可能由于生成的代码影响命令正常执行,例如: make manifests 在生成CRD模版时,需先删除api以及generated目录中为code-generator生成的代码,才可正常生成CRD模版。
使用时kubebuilder正常使用 api/v1 中的types,而code-generator生成的clientset等则需要使用 api/example/v1 中的types。

参考文献

使用code-generator生成crd的clientset、informer、listers
快速入门

你可能感兴趣的:(笔记,kubernetes,容器,云原生)