快速开始

本快速开始将涵盖：

前置条件

  • go 版本 v1.24.5+
  • docker 版本 17.03+
  • kubectl 版本 v1.11.3+
  • 可访问一个 Kubernetes v1.11.3+ 集群

安装

安装 kubebuilder：

# download kubebuilder and install locally.
curl -L -o kubebuilder "https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)"
chmod +x kubebuilder && sudo mv kubebuilder /usr/local/bin/

创建项目

创建一个目录，并在其中运行 init 命令来初始化新项目。示例如下：

mkdir -p ~/projects/guestbook
cd ~/projects/guestbook
kubebuilder init --domain my.domain --repo my.domain/guestbook

创建 API

运行以下命令创建一个新的 API（group/version 为 webapp/v1）以及其上的新 Kind（CRD）Guestbook：

kubebuilder create api --group webapp --version v1 --kind Guestbook

（可选）编辑 API 定义与调谐业务逻辑。更多信息见 设计一个 API 与控制器包含什么。

如果编辑了 API 定义，请生成诸如自定义资源（CR）或自定义资源定义（CRD）等清单：

make manifests
点击查看示例。(api/v1/guestbook_types.go) 

// GuestbookSpec defines the desired state of Guestbook
type GuestbookSpec struct {
	// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
	// Important: Run "make" to regenerate code after modifying this file

	// Quantity of instances
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=10
	Size int32 `json:"size"`

	// Name of the ConfigMap for GuestbookSpec's configuration
	// +kubebuilder:validation:MaxLength=15
	// +kubebuilder:validation:MinLength=1
	ConfigMapName string `json:"configMapName"`

	// +kubebuilder:validation:Enum=Phone;Address;Name
	Type string `json:"type,omitempty"`
}

// GuestbookStatus defines the observed state of Guestbook
type GuestbookStatus struct {
	// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
	// Important: Run "make" to regenerate code after modifying this file

	// PodName of the active Guestbook node.
	Active string `json:"active"`

	// PodNames of the standby Guestbook nodes.
	Standby []string `json:"standby"`
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:resource:scope=Cluster

// Guestbook is the Schema for the guestbooks API
type Guestbook struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   GuestbookSpec   `json:"spec,omitempty"`
	Status GuestbookStatus `json:"status,omitempty"`
}

试运行

你需要一个 Kubernetes 集群来作为运行目标。可以使用 KinD 获取一个用于测试的本地集群，或者针对远程集群运行。

在集群中安装 CRD：

make install

为获得快速反馈与代码级调试，运行控制器（它会在前台运行；如需保持运行，请切换到新的终端）：

make run

安装自定义资源的实例

如果你在 Create Resource [y/n] 处输入了 y，则在 samples 中已为该 CRD 创建了一个 CR（如果你更改过 API 定义，请先编辑样例）：

kubectl apply -k config/samples/

在集群中运行

当控制器准备好进行打包并在其他集群中测试时：

构建并将镜像推送到 IMG 指定的位置：

make docker-build docker-push IMG=<some-registry>/<project-name>:tag

使用 IMG 指定的镜像将控制器部署到集群：

make deploy IMG=<some-registry>/<project-name>:tag

卸载 CRD

从集群删除你的 CRD：

make uninstall

取消部署控制器

从集群中取消部署控制器：

make undeploy

使用插件

Kubebuilder 的设计基于插件，你可以使用可用插件为项目添加可选特性。

生成用于管理镜像的 API 与控制器

例如，你可以使用 deploy-image 插件 生成一个用于管理容器镜像的 API 与控制器：

kubebuilder create api --group webapp --version v1alpha1 --kind Busybox --image=busybox:1.36.1 --plugins="deploy-image/v1-alpha"

该命令会生成：

  • api/v1alpha1/busybox_types.go 中的 API 定义
  • internal/controllers/busybox_controller.go 中的控制器逻辑
  • internal/controllers/busybox_controller_test.go 中的测试脚手架（使用 EnvTest 进行集成式测试）

让你的项目与生态变化保持同步

Kubebuilder 提供了 AutoUpdate 插件，帮助你的项目与最新的生态变化保持一致。当有新版本发布时，该插件会打开一个包含 Pull Request 对比链接的 Issue。你可以审阅更新，并在需要时使用 GitHub AI models 来理解保持项目最新所需的变更。

kubebuilder edit --plugins="autoupdate/v1-alpha"

该命令会在 .github/workflows/autoupdate.yml 生成一个 GitHub workflow 文件。

下一步