Skills
skills/skills.netease.im/k8s-controller-generator

k8s-controller-generator

SKILL.md

Kubernetes Controller 生成器

基于kubebuilder框架生成生产就绪的Kubernetes Operator项目的技能，遵循网易等公司的真实企业开发工作流程。

何时使用此技能

在以下情况下使用此技能：

  • 您需要按照企业标准创建生产级Kubernetes operator
  • 您想在单个项目中生成多个CRD（例如：KafkaCluster、KafkaTopic、KafkaUser、KafkaConnect）
  • 您需要使用replace指令处理私有Go模块依赖
  • 您需要容器镜像和部署的自动化构建脚本
  • 您正在遵循生产环境的真实kubebuilder工作流程

快速开始 - 真实企业工作流程

当此技能触发时，基于真实的网易Kafka operator工作流程，请遵循以下步骤：

  1. 收集需求：向用户询问：

    • 域名（例如："netease.com"）
    • 仓库路径（例如："g.hz.netease.com/kafka/kafka-operator"）
    • CRD列表，包含group、version、kind（例如：KafkaCluster、KafkaTopic、KafkaUser、KafkaConnect）
    • 私有依赖（例如：带有replace指令的zookeeper-operator）
    • 镜像仓库和标签

  2. 生成项目：执行kubebuilder命令：

    kubebuilder init --domain netease.com --repo g.hz.netease.com/kafka/kafka-operator
kubebuilder create api --group kafka --version v1alpha1 --kind KafkaCluster
kubebuilder create api --group kafka --version v1alpha1 --kind KafkaTopic
kubebuilder create api --group kafka --version v1alpha1 --kind KafkaUser
kubebuilder create api --group kafka --version v1alpha1 --kind KafkaConnect

  3. 设置依赖：使用私有模块替换配置go.mod

  4. 创建构建脚本：生成带有CGO_ENABLED=0和docker push的build.sh

  5. 审查输出：呈现完整的企业就绪operator项目

项目结构

生成的项目遵循Kubernetes operator最佳实践：

myapp-controller/
├── api/
│   ├── v1alpha1/
│   │   ├── groupversion_info.go
│   │   ├── myapp_types.go
│   │   └── zz_generated.deepcopy.go
│   └── v1alpha1/
│       └── register.go
├── config/
│   ├── crd/
│   │   └── bases/
│   ├── rbac/
│   ├── manager/
│   └── samples/
├── controllers/
│   ├── myapp_controller.go
│   └── suite_test.go
├── hack/
│   └── boilerplate.go.txt
├── main.go
├── Makefile
├── PROJECT
├── Dockerfile
├── .dockerignore
├── go.mod
├── go.sum
└── README.md

核心特性

1. 自定义资源定义（CRD）

  • 生成带有验证模式的CRD YAML
  • 带有kubebuilder标记的Go类型
  • 深度复制生成

2. 控制器实现

  • 具有适当错误处理的协调循环
  • 事件记录
  • Finalizer支持
  • 状态子资源更新

3. 测试框架

  • 使用Ginkgo和Gomega的单元测试
  • 集成测试环境
  • 测试覆盖率报告

4. 构建和部署

  • 带有常见目标的Makefile（build、test、deploy、generate）
  • 容器化的Dockerfile
  • 用于部署的Kustomize清单
  • RBAC权限

5. 生产特性

  • Prometheus指标端点
  • 健康和就绪探针
  • 领导者选举
  • 优雅关闭

使用示例

示例1：基本控制器

用户："为MyApp资源生成控制器"
助手：[使用技能生成项目]

示例2：高级Operator

用户："创建带有自定义资源RedisCluster的Redis operator"
助手：[使用技能，将RedisCluster作为资源类型]

示例3：多版本API

用户："生成带有v1alpha1和v1beta1 API版本的控制器"
助手：[使用技能生成多个版本]

脚本

generate-operator.py

生成operator项目的主脚本。

用法：

python scripts/generate-operator.py \
  --domain example.com \
  --repo github.com/your-org/operator \
  --crd kafka v1alpha1 KafkaCluster \
  --crd kafka v1alpha1 KafkaTopic \
  --crd kafka v1alpha1 KafkaUser \
  --crd kafka v1alpha1 KafkaConnect \
  --dependency netease.com/zookeeper-operator v0.0.0-20210816021234-8a7500083e92 \
    "netease.com/zookeeper-operator v0.0.0-20210816021234-8a7500083e92 => g.hz.netease.com/base-cloud/zookeeper-operator v0.0.0-20210816021234-8a7500083e92" \
  --output-dir ./kafka-operator

参数：

  • --domain: API域名（必需）
  • --repo: Go模块仓库路径（必需）
  • --crd: CRD定义，格式：group version kind（可多次使用）
  • --dependency: 私有依赖，格式：module version "replace指令"
  • --output-dir: 输出目录（默认："./generated"）

validate-project.py

验证生成项目的完整性。

用法：

python scripts/validate-project.py ./generated-project

模板

技能包含以下模板：

  • templates/go.mod.tmpl: Go模块模板
  • templates/main.go.tmpl: 主入口点
  • templates/controller.go.tmpl: 控制器实现
  • templates/types.go.tmpl: CRD类型
  • templates/Makefile.tmpl: 构建系统
  • templates/Dockerfile.tmpl: 容器化
  • templates/deployment.yaml.tmpl: 部署清单
  • templates/build.sh.tmpl: 生产构建脚本

最佳实践

  1. 遵循Kubebuilder约定：生成的代码遵循kubebuilder模式
  2. 幂等协调：控制器设计为幂等
  3. 错误处理：适当的错误处理和重试逻辑
  4. 测试：全面的测试覆盖
  5. 安全性：遵循最小权限原则的RBAC
  6. 可观测性：内置指标和日志记录

常见模式

添加自定义逻辑

生成后，用户通常：

  1. 在*_types.go中添加自定义字段到CRD
  2. 在协调函数中实现业务逻辑
  3. 如果需要，添加验证webhook
  4. 扩展RBAC权限

部署

  1. 构建镜像：make docker-build
  2. 推送到仓库：make docker-push
  3. 部署到集群：make deploy
  4. 应用示例CR：kubectl apply -f config/samples/

故障排除

常见问题

  1. Go版本：确保安装Go 1.19+
  2. Kubebuilder：安装kubebuilder进行代码生成
  3. Docker：构建容器镜像所需
  4. Kubernetes集群：测试和部署所需

调试

  • 使用make run在本地针对集群运行
  • 检查控制器日志：kubectl logs -f deployment/myapp-controller-controller-manager
  • 查看事件：kubectl get events --watch

参考

后续步骤

生成控制器后：

  1. 审查生成的代码结构
  2. 自定义CRD模式
  3. 实现业务逻辑
  4. 编写测试
  5. 构建和部署
  6. 监控和迭代

记住：此技能生成一个起点。您需要添加特定的业务逻辑才能使控制器适用于您的用例。

企业工作流程示例

网易Kafka Operator工作流程

# 生成完整的Kafka operator
python scripts/generate-operator.py \
  --domain netease.com \
  --repo g.hz.netease.com/kafka/kafka-operator \
  --crd kafka v1alpha1 KafkaCluster \
  --crd kafka v1alpha1 KafkaTopic \
  --crd kafka v1alpha1 KafkaUser \
  --crd kafka v1alpha1 KafkaConnect \
  --dependency netease.com/zookeeper-operator v0.0.0-20210816021234-8a7500083e92 \
    "netease.com/zookeeper-operator v0.0.0-20210816021234-8a7500083e92 => g.hz.netease.com/base-cloud/zookeeper-operator v0.0.0-20210816021234-8a7500083e92" \
  --output-dir ./kafka-operator

生产构建脚本

生成的build.sh包含：

  • CGO_ENABLED=0静态编译
  • 多阶段Docker构建
  • 非root用户运行
  • 镜像签名和推送
  • 安全扫描集成

技能触发条件

当用户请求以下内容时触发此技能：

  • "生成Kubernetes operator"
  • "创建Kubernetes控制器"
  • "使用kubebuilder生成CRD"
  • "生成生产级operator"
  • "创建企业级Kubernetes控制器"
  • "生成带有多个CRD的operator"
  • "创建网易风格的Kafka operator"

技能输出

技能生成完整的operator项目，包括：

  1. 代码文件：所有Go源代码文件
  2. 配置文件：CRD、RBAC、部署配置
  3. 构建脚本：Makefile、Dockerfile、build.sh
  4. 文档：README.md、使用指南
  5. 验证脚本：项目完整性检查

注意事项

  1. 环境要求：需要安装kubebuilder、Go、Docker
  2. 网络访问：需要访问Go模块仓库
  3. 权限：需要Kubernetes集群访问权限
  4. 存储：生成的项目需要足够的磁盘空间
  5. 时间：生成完整项目可能需要几分钟时间

更新日志

v2.0.0

  • 基于真实的网易生产工作流程
  • 支持多CRD一次性生成
  • 私有依赖管理（replace指令）
  • 生产构建脚本
  • 完整的验证系统

v1.0.0

  • 基本kubebuilder项目生成
  • 单个CRD支持
  • 标准模板
  • 基本测试框架
Installs
1
Source
skills.netease.…2d6908ce
First Seen
Apr 2, 2026