Python 开发 K8s Operator 完整实操教程

核心概念基于 Kopf 框架的 K8s Operator 开发教程，涵盖 CRD 定义、调谐逻辑、部署运维和完整项目落地。

1. 技术选型说明

主流 Python Operator 框架只有 kopf，优势：

纯 Python，可直接复用你的现有代码：kubernetes-client、DCGM Python SDK、LangGraph Agent、Prometheus/Loki SDK、Pandas；
注解式开发，无需复杂脚手架、不用学 Go；
内置 watch 监听、调谐重试、队列、日志、状态更新；
支持 Mutating/Validating Webhook、CRD 联动、GitOps 流程。对比其他方案：

pykube-ng：底层封装，无完整控制器循环，废弃；
手写原生 k8s watch：需要自己实现重试、队列、防重复，代码量大易出bug；
生产内部平台/快速Agent开发首选 Kopf。

2. 前置依赖与环境

2.1. 本地开发依赖


# Python >=3.9

pip install kopf kubernetes pydantic python-dotenv

包说明：

kopf：Operator 核心控制器框架；
kubernetes：官方K8s SDK，增删改查集群资源；
pydantic：CR spec 参数校验；

2.2. 集群前置资源（必须先部署）

开发前向集群创建：

CRD：自定义资源定义（扩展 SREAgent 资源）
RBAC：ServiceAccount / Role / RoleBinding，给控制器操作集群权限

3. 完整项目结构


sre-operator-python/

├── crd.yaml                # 自定义资源CRD

├── rbac.yaml               # 控制器权限

├── operator.yaml           # Operator控制器部署yaml

├── example-cr.yaml         # 用户使用的自定义资源实例

├── Dockerfile              # 打包镜像

├── requirements.txt        # 依赖

└── main.py                 # 控制器核心逻辑

4. 分步实现代码

4.1. 步骤1：requirements.txt


kopf==2.39.0

kubernetes==27.2.0

pydantic>=2.0

4.2. 步骤2：CRD 定义 crd.yaml

自定义资源 SREAgent，用于配置运维智能体：自动GPU监控、故障自愈、RAG知识库开关、巡检间隔


apiVersion: apiextensions.k8s.io/v1

kind: CustomResourceDefinition

metadata:

  name: sreagents.aiops.local

spec:

  group: aiops.local

  names:

    kind: SREAgent

    plural: sreagents

    singular: sreagent

    shortNames: ["sre"]

  scope: Namespaced

  versions:

    - name: v1

      served: true

      storage: true

      schema:

        openAPIV3Schema:

          type: object

          properties:

            spec:

              type: object

              properties:

                enableGpuMonitor:

                  type: boolean

                  default: true

                autoRepair:

                  type: boolean

                  default: false

                monitorInterval:

                  type: integer

                  minimum: 5

                  default: 15

                enableRAG:

                  type: boolean

                  default: true

                gpuTolerate:

                  type: boolean

                  default: true

下发CRD：


kubectl apply -f crd.yaml

# 验证

kubectl get crd | grep sreagents

4.3. 步骤3：RBAC权限 rbac.yaml

Operator 需要读写 Deployment、ConfigMap、自定义SREAgent资源


# ServiceAccount

apiVersion: v1

kind: ServiceAccount

metadata:

  name: sre-operator-sa

---

# 权限规则

apiVersion: rbac.authorization.k8s.io/v1

kind: Role

metadata:

  name: sre-operator-role

rules:

  # 自定义CR资源读写监听

  - apiGroups: ["aiops.local"]

    resources: ["sreagents"]

    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

  # 管理Agent的Deployment、Pod、ConfigMap

  - apiGroups: ["apps"]

    resources: ["deployments"]

    verbs: ["*"]

  - apiGroups: [""]

    resources: ["configmaps", "pods", "services"]

    verbs: ["*"]

  # 更新CR status状态

  - apiGroups: ["aiops.local"]

    resources: ["sreagents/status"]

    verbs: ["patch", "update"]

---

# 绑定权限

apiVersion: rbac.authorization.k8s.io/v1

kind: RoleBinding

metadata:

  name: sre-operator-rb

subjects:

  - kind: ServiceAccount

    name: sre-operator-sa

roleRef:

  kind: Role

  name: sre-operator-role

  apiGroup: rbac.authorization.k8s.io


kubectl apply -f rbac.yaml

4.4. 步骤4：核心控制器 main.py

包含核心控制器 main.py

包含三大核心回调：

创建/更新CR：调谐逻辑，自动生成SRE-Agent Deployment；
删除CR：自动清理Agent资源；
状态更新：将Agent运行状态写入CR.status，方便运维查看。


import kopf

from kubernetes import client, config

from kubernetes.client import V1Deployment, V1Container, V1PodSpec, V1LabelSelector, V1EnvVar

# 加载kubeconfig

try:

    # 本地开发环境

    config.load_kube_config()

except Exception:

    # 集群内容器自动加载sa权限

    config.load_incluster_config()

apps_api = client.AppsV1Api()

core_api = client.CoreV1Api()

# 资源标签，关联CR与管理的Deployment

def get_labels(cr_name: str):

    return {

        "app": "sre-ai-agent",

        "managed-by": "python-sre-operator",

        "cr-name": cr_name

    }

# 【核心调谐函数】CR创建/修改触发

@kopf.on.create("aiops.local", "v1", "sreagents")

@kopf.on.update("aiops.local", "v1", "sreagents")

def reconcile_sre_agent(spec, name, namespace, body, logger, **kwargs):

    cr_name = name

    labels = get_labels(cr_name)

    # 1. 读取用户CR配置

    enable_gpu = spec.get("enableGpuMonitor", True)

    auto_repair = spec.get("autoRepair", False)

    interval = spec.get("monitorInterval", 15)

    enable_rag = spec.get("enableRAG", True)

    use_gpu_tolerate = spec.get("gpuTolerate", True)

    # 2. 环境变量传递给Agent业务程序

    env_list = [

        V1EnvVar(name="MONITOR_INTERVAL", value=str(interval)),

        V1EnvVar(name="GPU_MONITOR", value=str(enable_gpu)),

        V1EnvVar(name="AUTO_REPAIR", value=str(auto_repair)),

        V1EnvVar(name="RAG_ENABLE", value=str(enable_rag))

    ]

    # 3. GPU节点污点容忍

    tolerations = []

    if use_gpu_tolerate:

        tolerations.append(client.V1Toleration(

            key="gpu", operator="Equal", value="true", effect="NoSchedule"

        ))

    # 4. 构造Agent容器

    container = V1Container(

        name="sre-agent",

        image="aiops/sre-agent:v1.0", # 你的自研运维Agent镜像

        env=env_list,

        resources=client.V1ResourceRequirements(

            requests={"cpu": "500m", "memory": "1Gi"},

            limits={"cpu": "1000m", "memory": "2Gi"}

        )

    )

    # 5. 组装Deployment对象

    deploy_name = f"sre-agent-{cr_name}"

    deploy_body = V1Deployment(

        metadata=client.V1ObjectMeta(name=deploy_name, labels=labels),

        spec=V1DeploymentSpec(

            replicas=1,

            selector=V1LabelSelector(match_labels=labels),

            template=client.V1PodTemplateSpec(

                metadata=client.V1ObjectMeta(labels=labels),

                spec=V1PodSpec(containers=[container], tolerations=tolerations)

            )

        )

    )

    # 6. 判断资源存在与否，创建/更新

    try:

        apps_api.read_namespaced_deployment(name=deploy_name, namespace=namespace)

        apps_api.patch_namespaced_deployment(deploy_name, namespace, deploy_body)

        logger.info(f"更新Agent Deployment: {deploy_name}")

        status_msg = f"更新成功，自动修复：{auto_repair}"

    except client.ApiException as e:

        if e.status == 404:

            apps_api.create_namespaced_deployment(namespace=namespace, body=deploy_body)

            logger.info(f"新建Agent Deployment: {deploy_name}")

            status_msg = f"创建成功，自动修复：{auto_repair}"

        else:

            raise

    # 7. 更新CR status字段，保存运行状态

    status = {

        "agentReady": True,

        "message": status_msg,

        "gpuMonitor": enable_gpu,

        "autoRepair": auto_repair

    }

    kopf.patch_status(body, namespace=namespace, status=status)

# 【删除回调】CR被删除时，自动清理Agent Deployment

@kopf.on.delete("aiops.local", "v1", "sreagents")

def delete_agent_resources(name, namespace, logger, **kwargs):

    deploy_name = f"sre-agent-{name}"

    try:

        apps_api.delete_namespaced_deployment(deploy_name, namespace)

        logger.info(f"清理Agent资源: {deploy_name}")

    except client.ApiException as e:

        if e.status != 404:

            raise

# 程序入口

if __name__ == "__main__":

    # 启动控制器，持续监听CR事件

    kopf.run()

4.5. 步骤5：用户使用CR示例 example-cr.yaml

运维人员只需要编写极简CR，无需写复杂Deployment


apiVersion: aiops.local/v1

kind: SREAgent

metadata:

  name: gpu-cluster-agent

spec:

  enableGpuMonitor: true

  autoRepair: true

  monitorInterval: 10

  enableRAG: true

  gpuTolerate: true

4.6. 步骤6：控制器部署 operator.yaml

将Python Operator打包镜像，部署到集群中运行


apiVersion: apps/v1

kind: Deployment

metadata:

  name: sre-operator-python

spec:

  replicas: 1

  selector:

    matchLabels:

      app: sre-operator

  template:

    metadata:

      labels:

        app: sre-operator

    spec:

      serviceAccountName: sre-operator-sa

      containers:

      - name: operator

        image: python-sre-operator:v1

        command: ["python", "main.py"]

        resources:

          limits:

            cpu: 300m

            memory: 512Mi

          requests:

            cpu: 100m

            memory: 256Mi

4.7. 步骤7：Dockerfile 打包镜像


FROM python:3.10-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install -r requirements.txt

COPY main.py ./

CMD ["python", "main.py"]

5. 本地调试完整流程（不用打包镜像）

提前部署CRD、RBAC


kubectl apply -f crd.yaml -f rbac.yaml

本地启动控制器


python main.py

新开终端下发CR，观察控制器日志


kubectl apply -f example-cr.yaml

# 查看CR状态

kubectl get sreagents

kubectl describe sreagent gpu-cluster-agent

# 验证自动生成的Agent Deployment

kubectl get deploy

修改CR配置，观察控制器自动更新Pod环境变量


kubectl edit sreagent gpu-cluster-agent

删除CR，自动清理Agent


kubectl delete sreagent gpu-cluster-agent

6. 进阶生产增强功能（可直接扩展代码）

6.1. 增加 Validating Webhook（拦截非法CR配置）

防止用户填写非法参数，如monitorInterval < 5直接拒绝创建

在main.py追加校验函数：


@kopf.on.validate("aiops.local/v1", "sreagents")

def validate_cr(spec, **kwargs):

    interval = spec.get("monitorInterval", 15)

    if interval < 5:

        raise kopf.AdmissionError("monitorInterval 不能小于5")

6.2. Mutating Webhook 自动填充默认值


@kopf.on.mutate("aiops.local/v1", "sreagents")

def mutate_cr(spec, patch, **kwargs):

    if "monitorInterval" not in spec:

        patch.spec["monitorInterval"] = 15

6.3. 定时强制全量同步（防资源被手动篡改）

kopf提供定时器，每10分钟执行一次调谐，恢复被手动删除/修改的Agent Pod


@kopf.timer("aiops.local/v1", "sreagents", interval=600)

def full_sync(spec, name, namespace, **kwargs):

    reconcile_sre_agent(spec, name, namespace, body={}, logger=None)

6.4. 对接自有Agent业务代码

在reconcile_sre_agent中扩展：

自动创建ConfigMap存储RAG知识库地址、Prometheus/Loki地址；
动态注入DCGM采集权限、GPU监控脚本；
读取集群GPU节点标签，自动调整调度亲和；

7. 常见踩坑与排错

下发CR后控制器无日志、不触发调谐

RBAC缺少 watch 权限；
CRD apiGroup/kind 和代码监听不匹配；
kubeconfig 权限不足。

Reconcile 无限循环刷新Deployment
更新资源后触发变更事件，重复进入调谐；解决方案：增加版本判断，无变更直接return跳过。
无法更新CR statusRole 缺少 sreagents/status 的 patch/update 动词。
删除CR后Deployment残留
@kopf.on.delete 回调内部API异常，查看控制器error日志。
Webhook不生效
集群缺少webhook证书，生产环境需要自动签发cert-manager。

8. Python Operator 优缺点总结

8.1. 优点

完美兼容你的AIOps技术栈：Python Agent、DCGM、LangGraph、向量库、监控SDK；
上手极快，无需学习Go、kubebuilder复杂脚手架；
开发效率高，适合内部运维平台、自研SRE智能体管理；

8.2. 缺点

单副本运行，无原生leader选举，大规模多集群高并发场景性能弱于Go Kubebuilder；
内存占用高于Go二进制，超大集群不推荐；

8.3. 适用场景

你的项目：自研AIOps SRE-Agent管理Operator、GPU集群内部运维平台、小规模私有AI集群。

结合你的场景：自研 AIOps SRE-Agent Operator，用来统一管理集群运维智能体、自动部署Agent、管控自动修复开关、GPU监控能力、RAG知识库配置。

9. 前置核心概念回顾

CRD：自定义资源定义，扩展K8s API，新增资源类型 SREAgent
CR：CR的实例，用户写yaml声明期望状态（是否开启GPU自愈、监控间隔、是否自动排障）
Controller（调谐器）：Operator核心程序，持续监听CR增/改/删，执行Reconcile循环，对齐集群真实资源与期望配置
RBAC：控制器必须权限，读写Pod/Deployment/ConfigMap/CR等资源
Webhook（可选）：Mutating自动填充默认值、Validating校验非法配置
Reconcile 循环标准流程
Watch 捕获CR事件
获取CR期望spec配置
查询集群当前真实资源（Deployment/Service/ConfigMap）
对比期望vs真实，找出差异
创建/更新/删除资源消除差异
异常则重新入队重试；无差异休眠等待下一次变更

10. 两种自研技术栈选型对比（按需选择）

10.1. 方案1：Kubebuilder（Go语言，企业生产标准，推荐大规模AIOps平台）

优点：官方原生、高性能、支持Webhook、自动生成CRD/RBAC/CR模板、成熟稳定，GPU Operator/Prometheus Operator底层均基于此

缺点：需要Go基础，学习成本偏高

适用场景：长期维护、多集群大规模平台、正式交付产品

10.2. 方案2：Kopf（Python轻量框架，适合运维快速开发，你的SRE-Agent首选）

优点：Python开发，可直接复用你现有Python运维代码（DCGM SDK、K8s Python Client、LangGraph Agent、Prometheus SDK）、极简注解式开发、零复杂脚手架

缺点：性能弱于Go，不适合超高并发集群

适用场景：内部运维平台、快速落地AIOps Agent、快速验证调度自动化逻辑

方案一：Kopf Python 自研Operator（重点，贴合你的技术栈）

11. 环境准备


# 本地开发环境

python3.10+

pip install kopf kubernetes pydantic

依赖说明：

kopf：Operator控制器框架，封装Watch、Reconcile、重试队列
kubernetes：官方K8s Python SDK，增删集群资源
pydantic：CR配置参数校验

12. 完整项目目录结构


sre-agent-operator/

├── crd.yaml               # 自定义资源CRD定义

├── rbac.yaml              # 控制器权限SA/Role/RoleBinding

├── operator-deploy.yaml   # Operator控制器自身Deployment

├── example-cr.yaml        # 用户使用的SREAgent资源示例

└── main.py                # 核心控制器Reconcile逻辑

13. 分步完整代码实现

13.1. 1 CRD 定义 crd.yaml

注册自定义资源 sreagents.aiops.local，用来描述运维Agent配置


apiVersion: apiextensions.k8s.io/v1

kind: CustomResourceDefinition

metadata:

  name: sreagents.aiops.local

spec:

  group: aiops.local

  names:

    kind: SREAgent

    plural: sreagents

    singular: sreagent

    shortNames: ["sre"]

  scope: Namespaced

  versions:

    - name: v1

      served: true

      storage: true

      schema:

        openAPIV3Schema:

          type: object

          properties:

            spec:

              type: object

              properties:

                # 自定义配置项，对应你的AIOps Agent能力

                enableGpuMonitor:

                  type: boolean

                  default: true

                autoRepairFault:

                  type: boolean

                  default: false

                monitorInterval:

                  type: integer

                  minimum: 5

                  default: 15

                gpuTolerate:

                  type: boolean

                  default: true

                ragEnable:

                  type: boolean

                  default: true

下发CRD到集群：


kubectl apply -f crd.yaml

# 验证

kubectl get crd | grep sreagents

13.2. 2 RBAC权限 rbac.yaml

控制器需要读写Deployment、ConfigMap、自定义SREAgent资源，必须配置权限


# ServiceAccount

apiVersion: v1

kind: ServiceAccount

metadata:

  name: sre-operator-sa

---

# Role 权限规则

apiVersion: rbac.authorization.k8s.io/v1

kind: Role

metadata:

  name: sre-operator-role

rules:

  # 监听自定义CR资源

  - apiGroups: ["aiops.local"]

    resources: ["sreagents"]

    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

  # 管理Agent的Deployment、ConfigMap、Service

  - apiGroups: ["apps"]

    resources: ["deployments"]

    verbs: ["*"]

  - apiGroups: [""]

    resources: ["configmaps", "services", "pods"]

    verbs: ["*"]

---

# 绑定权限

apiVersion: rbac.authorization.k8s.io/v1

kind: RoleBinding

metadata:

  name: sre-operator-rb

subjects:

  - kind: ServiceAccount

    name: sre-operator-sa

roleRef:

  kind: Role

  name: sre-operator-role

  apiGroup: rbac.authorization.k8s.io

下发权限：


kubectl apply -f rbac.yaml -n default

13.3. 3 核心控制器代码 main.py（Reconcile 调谐逻辑）

实现：监听SREAgent CR，自动创建/更新/销毁运维Agent Deployment


import kopf

from kubernetes import client, config

from kubernetes.client import V1Deployment, V1Container, V1PodSpec, V1LabelSelector

# 加载集群kubeconfig（本地开发加载~/.kube/config；容器内自动加载serviceaccount）

try:

    config.load_kube_config()

except:

    config.load_incluster_config()

apps_v1 = client.AppsV1Api()

core_v1 = client.CoreV1Api()

# 定义Reconcile函数：CR 创建/更新 触发

@kopf.on.create("aiops.local", "v1", "sreagents")

@kopf.on.update("aiops.local", "v1", "sreagents")

def reconcile_agent(body, name, namespace, spec, **kwargs):

    """核心调谐循环：对齐期望配置与集群真实Deployment"""

    cr_name = name

    cr_spec = spec

    # 1. 读取CR期望配置

    enable_gpu = cr_spec.get("enableGpuMonitor", True)

    auto_repair = cr_spec.get("autoRepairFault", False)

    interval = cr_spec.get("monitorInterval", 15)

    use_gpu_tolerate = cr_spec.get("gpuTolerate", True)

    enable_rag = cr_spec.get("ragEnable", True)

    # 标签，关联CR与Agent Deployment

    labels = {

        "app": "sre-ai-agent",

        "managed-by": "sre-operator",

        "cr-name": cr_name

    }

    # 2. 构造容器环境变量（传递CR配置给Agent程序）

    env = [

        client.V1EnvVar(name="MONITOR_INTERVAL", value=str(interval)),

        client.V1EnvVar(name="GPU_MONITOR_ENABLE", value=str(enable_gpu)),

        client.V1EnvVar(name="AUTO_REPAIR", value=str(auto_repair)),

        client.V1EnvVar(name="RAG_ENABLE", value=str(enable_rag))

    ]

    # GPU节点容忍配置

    tolerations = []

    if use_gpu_tolerate:

        tolerations.append(client.V1Toleration(

            key="gpu", operator="Equal", value="true", effect="NoSchedule"

        ))

    # 容器定义（你的AIOps SRE Agent镜像）

    container = V1Container(

        name="sre-agent",

        image="aiops/sre-agent:v1.0",

        env=env,

        resources=client.V1ResourceRequirements(

            requests={"cpu": "500m", "memory": "1Gi"},

            limits={"cpu": "1", "memory": "2Gi"}

        )

    )

    # Deployment完整对象

    deploy = V1Deployment(

        metadata=client.V1ObjectMeta(name=f"sre-agent-{cr_name}", labels=labels),

        spec=V1DeploymentSpec(

            replicas=1,

            selector=V1LabelSelector(match_labels=labels),

            template=client.V1PodTemplateSpec(

                metadata=client.V1ObjectMeta(labels=labels),

                spec=V1PodSpec(containers=[container], tolerations=tolerations)

            )

        )

    )

    # 3. 查询集群当前是否存在对应Deployment

    try:

        apps_v1.read_namespaced_deployment(name=f"sre-agent-{cr_name}", namespace=namespace)

        # 存在则更新

        apps_v1.patch_namespaced_deployment(

            name=f"sre-agent-{cr_name}",

            namespace=namespace,

            body=deploy

        )

        kopf.info(f"更新Agent Deployment {cr_name}")

    except client.exceptions.ApiException as e:

        if e.status == 404:

            # 不存在则新建

            apps_v1.create_namespaced_deployment(namespace=namespace, body=deploy)

            kopf.info(f"新建Agent Deployment {cr_name}")

        else:

            raise

# CR 删除时触发，自动清理Agent Deployment

@kopf.on.delete("aiops.local", "v1", "sreagents")

def clean_agent(body, name, namespace, **kwargs):

    deploy_name = f"sre-agent-{name}"

    try:

        apps_v1.delete_namespaced_deployment(name=deploy_name, namespace=namespace)

        kopf.info(f"删除Agent {deploy_name}")

    except client.exceptions.ApiException as e:

        if e.status != 404:

            raise

if __name__ == "__main__":

    kopf.run()

13.4. 4 Operator自身部署 yaml operator-deploy.yaml

将控制器打包镜像，部署到K8s集群


apiVersion: apps/v1

kind: Deployment

metadata:

  name: sre-operator

spec:

  replicas: 1

  selector:

    matchLabels:

      app: sre-operator

  template:

    metadata:

      labels:

        app: sre-operator

    spec:

      serviceAccountName: sre-operator-sa

      containers:

      - name: operator

        image: python-sre-operator:latest

        command: ["python", "main.py"]

        resources:

          limits:

            cpu: 300m

            memory: 512Mi

13.5. 5 用户使用CR示例 example-cr.yaml

用户只需要编写该yaml，apply后Operator自动创建完整运维Agent


apiVersion: aiops.local/v1

kind: SREAgent

metadata:

  name: gpu-cluster-agent

spec:

  enableGpuMonitor: true

  autoRepairFault: true

  monitorInterval: 10

  gpuTolerate: true

  ragEnable: true

14. 完整测试、部署流程

14.1. 本地调试（无需打包镜像）


# 1. 先安装CRD、RBAC

kubectl apply -f crd.yaml -f rbac.yaml

# 2. 本地启动控制器

python main.py

# 3. 新建CR，观察控制器日志自动创建Agent Deployment

kubectl apply -f example-cr.yaml

# 4. 修改CR spec，观察控制器自动更新Pod环境变量

kubectl edit sreagent gpu-cluster-agent

# 5. 删除CR，自动清理Deployment

kubectl delete sreagent gpu-cluster-agent

14.2. 集群部署运行

打包main.py、依赖构建镜像 aiops/sre-operator:latest
下发部署yaml


kubectl apply -f operator-deploy.yaml

# 查看控制器日志

kubectl logs -f deployment/sre-operator

15. 扩展增强（生产可用）

增加Validating Webhook：拦截非法CR配置（monitorInterval小于5直接拒绝创建）
Mutating Webhook：自动填充缺失默认字段
状态更新：在CR status字段写入Agent运行状态、故障数量、巡检记录
重试机制：Reconcile失败自动延迟重试
告警输出：控制器捕获异常推送钉钉/企业微信告警

方案二：Kubebuilder Go 自研Operator（企业标准生产方案）

16. 环境准备

安装 Go 1.21+
安装 kubebuilder、kustomize


# 安装kubebuilder

curl -L https://github.com/kubernetes-sigs/kubebuilder/releases/download/v3.14.0/kubebuilder_3.14.0_linux_amd64.tar.gz | tar xz

mv kubebuilder_3.14.0_linux_amd64 /usr/local/kubebuilder

export PATH=$PATH:/usr/local/kubebuilder/bin

17. 项目初始化完整命令


# 1. 初始化项目

kubebuilder init --domain aiops.local --repo github.com/xxx/sre-operator

# 2. 创建API资源 SREAgent

kubebuilder create api --group aiops --version v1 --kind SREAgent

# 选择 Create Resource(y), Create Controller(y)

执行后自动生成：CRD模板、Controller骨架、RBAC规则、kustomize部署清单

18. 核心开发步骤

修改 api/v1/sreagent_types.go 定义Spec结构体（你的Agent配置参数）
实现 controllers/sreagent_controller.go 内Reconcile核心调谐逻辑
可选：开启Webhook，生成mutate/validate代码


kubebuilder create webhook --group aiops --version v1 --kind SREAgent --defaulting --programmatic-validation

本地运行测试


make install run

打包镜像、部署到集群


make docker-build docker-push IMG=aiops/sre-operator-go:v1

make deploy IMG=aiops/sre-operator-go:v1

19. Go版优缺点总结

优势：编译二进制、极低内存CPU占用、官方标准、Webhook原生支持、支持大规模集群高并发调谐、可集成原生K8s缓存
劣势：无法直接复用你现有Python Agent/DCGM/LangGraph代码，需要跨进程调用

三、自研Operator通用生产优化点（必做）

状态写入CR.status
每次调谐完成，将Agent运行状态、巡检故障数、GPU异常数量写入CR status，用户kubectl get sreagent直观查看运行健康度
指数退避重试
Reconcile出现API错误、资源不足、依赖服务不可用时，采用指数延迟重试，避免死循环疯狂请求API Server
并发调谐控制
限制同时处理CR数量，防止控制器并发过高压垮集群apiserver
资源配额限制
Operator控制器Deployment设置CPU/内存limits，防止内存泄露占用节点资源
日志结构化输出
区分Info/Warn/Error日志，方便对接Loki日志系统排查调谐失败问题
防重复调谐
使用资源版本号判断是否真正发生变更，无变更直接跳过Reconcile逻辑
高可用：控制器多副本 + Leader选举，同一时间仅一个副本执行调谐（Kopf默认单副本，Kubebuilder原生支持leader election）

四、自研Operator 高频排坑

CR下发后控制器无响应

RBAC权限缺失，无法watch自定义CR资源；补充Role规则
CRD定义错误，apiGroup/kind不匹配控制器监听配置
控制器进程异常崩溃，查看pod日志

Reconcile无限循环反复触发
更新Deployment后触发资源变更事件，再次进入调谐；需要通过标签/版本判断是否无需更新，跳过逻辑
权限不足无法创建Deployment
Role缺少apps deployments的create/update/patch动词
删除CR后Agent资源残留未清理
@kopf.on.delete 回调函数异常、权限不足，无法执行删除API
Webhook校验不生效，非法配置可以提交
Webhook证书未正确挂载、webhook配置namespace/selector不匹配

五、你的AIOps场景自研Operator落地价值

统一管控所有SRE智能运维Agent，一条CR配置自动完成部署、GPU容忍、RAG开关、自动故障修复能力切换
屏蔽底层Deployment/ConfigMap复杂yaml，运维人员只需要写极简CR资源，降低使用门槛
持续自愈：Agent Pod被手动删除、配置篡改，控制器自动恢复期望状态
批量管控多GPU集群Agent，全局统一开关自动修复、GPU监控能力
完整GitOps友好：CR yaml存入Git仓库，集群状态代码化、可回滚、版本管控

关联文档

K8s Operator 完整详解

K8s Operator 开发全流程

Python 基础