> For the complete documentation index, see [llms.txt](https://atomoh.gitbook.io/kubernetes/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atomoh.gitbook.io/kubernetes/cn/ping-tai-gong-cheng/03-kro.md).

# Kubernetes Resource Operator (KRO)

> **支持版本**: Kubernetes 1.31, 1.32, 1.33 **最后更新**: February 21, 2026

## 概述

Kubernetes Resource Operator (KRO) 是一个用于以声明式方式定义和管理 Kubernetes 资源之间关系的框架。KRO 超越了传统 Helm Charts 的限制，通过 ResourceGraphDefinition (RGD) 对资源图建模，并能够将复杂应用作为单个 Custom Resource（自定义资源）进行部署。

## KRO 核心概念

### 什么是 Kubernetes Resource Operator？

Kubernetes Resource Operator (KRO) 是一个用于以声明式方式定义和管理 Kubernetes 资源之间关系的框架。KRO 基于以下核心概念：

1. **声明式资源关系**：通过显式定义资源之间的关系来表达复杂的应用结构。
2. **基于状态的调谐**：持续调谐期望状态与实际状态之间的差异。
3. **资源图**：以图的形式对资源之间的依赖关系和关联进行建模。
4. **自动化生命周期管理**：自动处理资源的创建、更新和删除。

### ResourceGraphDefinition (RGD)

ResourceGraphDefinition (RGD) 是 KRO 的核心组件，用于定义 Custom Resource 与其依赖的 Kubernetes 原生资源之间的关系。RGD 提供以下能力：

1. **父子关系定义**：定义父资源与子资源之间的层级结构。
2. **基于模板的资源创建**：根据父资源属性动态创建子资源。
3. **状态传播**：将子资源状态传播到父资源，以理解整体应用状态。
4. **依赖管理**：定义子资源之间的依赖关系，确保正确的创建和更新顺序。

### KRO 与传统方法对比

与传统 Kubernetes 资源管理方法相比，KRO 具有以下差异化特性：

| 特性             | KRO | Helm | Operator SDK | Kustomize |
| -------------- | --- | ---- | ------------ | --------- |
| **资源关系建模**     | 显式图 | 隐式   | 基于代码         | 无         |
| **状态传播**       | 自动  | 手动   | 基于代码         | 无         |
| **依赖管理**       | 声明式 | 隐式   | 基于代码         | 无         |
| **可扩展性**       | 高   | 中    | 高            | 低         |
| **学习曲线**       | 中   | 低    | 高            | 低         |
| **GitOps 友好性** | 高   | 中    | 中            | 高         |

### KRO 架构

KRO 由以下组件组成：

1. **KRO Controller**：监视 ResourceGraphDefinitions 并管理资源图。
2. **Resource Graph Engine**：处理资源之间的关系和依赖。
3. **State Manager**：跟踪并传播资源状态。
4. **Reconciliation Loop**：调谐期望状态与实际状态之间的差异。

```
+-------------------+     +-------------------+     +-------------------+
|  Custom Resource  |     | ResourceGraph     |     | Kubernetes        |
|  (CR)             |<--->| Definition        |<--->| Native Resources  |
+-------------------+     +-------------------+     +-------------------+
         ^                        ^                         ^
         |                        |                         |
         v                        v                         v
+-----------------------------------------------------------------------+
|                          KRO Controller                                |
|                                                                       |
|  +----------------+  +----------------+  +----------------+           |
|  | Resource Graph |  | State Manager  |  | Reconciliation |           |
|  |     Engine     |  |                |  |     Loop       |           |
|  +----------------+  +----------------+  +----------------+           |
+-----------------------------------------------------------------------+
```

## KRO 的起源与演进

### Kubernetes 资源管理中的挑战

随着 Kubernetes 应用复杂度不断增长，资源管理方法也随之演进：

1. **直接使用 kubectl 管理**：手动应用单个 YAML 文件 —— 难以管理资源间关系和顺序
2. **Helm**：通过基于模板的打包简化部署，但受限于 Go 模板复杂性和 Release 状态管理
3. **Operator SDK**：可以进行完整的自定义 Controller 开发，但需要 Go 编程知识，并且开发/维护成本高
4. **KRO**：声明式 ResourceGraphDefinition 无需编码即可定义资源图 —— 将 Operator 的能力与 Helm 的简洁性结合起来

### KRO 解决的问题

| 现有限制          | KRO 的解决方案                   |
| ------------- | --------------------------- |
| Helm 模板复杂性    | 纯 YAML + 资源引用语法             |
| Operator 开发成本 | RGD 声明自动生成 CRD + Controller |
| 无资源间状态传播      | statusMappings 用于自动的子→父状态传播 |
| 手动依赖排序        | 在资源图中自动解析依赖关系               |

## 实验环境设置

要跟随本文档中的示例进行操作，你需要以下工具和环境：

### 必需工具

* kubectl v1.31 或更高版本
* Helm v3.10 或更高版本
* kro CLI v0.5.0 或更高版本
* 一个可用的 Kubernetes 集群（EKS、minikube、kind 等）

### 安装 KRO

```bash
# Install KRO controller
kubectl apply -f https://github.com/kro-project/kro/releases/download/v0.5.0/kro-controller.yaml

# Install KRO CLI
curl -L https://github.com/kro-project/kro/releases/download/v0.5.0/kro-cli-$(uname -s)-$(uname -m) -o kro
chmod +x kro
sudo mv kro /usr/local/bin/

# Verify installation
kubectl get pods -n kro-system
```

## Helm 和 KRO 对比

### Helm

Helm 是一种广泛使用的工具，用于打包和部署 Kubernetes 应用。Helm 具有以下特点：

* **基于模板**：使用 Go 模板语言生成 Kubernetes manifests
* **Chart 概念**：用于打包应用的单元
* **Release 管理**：已部署应用的版本管理
* **中心仓库**：用于共享和复用 Charts 的 Repository

### Kubernetes Resource Operator (KRO)

KRO 是一种使用 Kubernetes Custom Resources 管理应用的方法：

* **声明式 API**：Kubernetes 原生资源定义
* **基于状态**：声明期望状态，由 Controller 调谐实际状态
* **GitOps 友好**：易于与版本控制系统集成
* **可扩展性**：通过 Custom Resource Definitions (CRDs) 进行扩展

### 对比表

| 特性        | Helm              | KRO                     |
| --------- | ----------------- | ----------------------- |
| **打包方式**  | Chart（tgz 归档）     | Custom Resource         |
| **模板引擎**  | Go templates      | 无（纯 YAML）               |
| **版本管理**  | Release 历史        | 基于 Git                  |
| **回滚机制**  | helm rollback     | 基于 GitOps 的回滚           |
| **依赖管理**  | requirements.yaml | ResourceGraphDefinition |
| **定制化**   | values.yaml       | CR spec                 |
| **安装方式**  | helm install      | kubectl apply           |
| **升级方式**  | helm upgrade      | kubectl apply           |
| **删除方式**  | helm uninstall    | kubectl delete          |
| **Hooks** | 安装/升级/删除 hooks    | 基于 Kubernetes 事件        |

## 从 Helm 迁移到 KRO 的原因

1. **Kubernetes 原生方法**：KRO 遵循 Kubernetes 的声明式 API 模型，提供更一致的体验
2. **改进的版本管理**：能够单独跟踪每个资源的变更
3. **细粒度控制**：在单个资源级别提供更详细的控制
4. **简化的依赖管理**：通过显式依赖声明更容易管理复杂关系
5. **增强的安全性**：能够遵循最小权限原则，仅授予必要权限
6. **改进的状态管理**：自动传播和聚合资源状态
7. **GitOps 工作流集成**：通过声明式方法轻松与 GitOps 工具集成

## 实践示例：将 Nginx Helm Chart 迁移到 KRO

### 现有 Helm Chart (values.yaml)

```yaml
# Nginx Helm chart values.yaml
replicaCount: 2

image:
  repository: nginx
  tag: 1.21.0
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80

ingress:
  enabled: true
  hosts:
    - host: example.com
      paths:
        - path: /
          pathType: Prefix

resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 50m
    memory: 64Mi
```

### KRO Custom Resource Definition

```yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: nginxapps.kro.example.com
spec:
  group: kro.example.com
  names:
    kind: NginxApp
    listKind: NginxAppList
    plural: nginxapps
    singular: nginxapp
  scope: Namespaced
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                replicas:
                  type: integer
                  default: 1
                image:
                  type: object
                  properties:
                    repository:
                      type: string
                    tag:
                      type: string
                    pullPolicy:
                      type: string
                      enum: [Always, IfNotPresent, Never]
                service:
                  type: object
                  properties:
                    type:
                      type: string
                      enum: [ClusterIP, NodePort, LoadBalancer]
                    port:
                      type: integer
                ingress:
                  type: object
                  properties:
                    enabled:
                      type: boolean
                    hosts:
                      type: array
                      items:
                        type: object
                        properties:
                          host:
                            type: string
                          paths:
                            type: array
                            items:
                              type: object
                              properties:
                                path:
                                  type: string
                                pathType:
                                  type: string
                resources:
                  type: object
                  properties:
                    limits:
                      type: object
                      x-kubernetes-preserve-unknown-fields: true
                    requests:
                      type: object
                      x-kubernetes-preserve-unknown-fields: true
```

### 创建 ResourceGraphDefinition

```yaml
apiVersion: kro.run/v1alpha1
kind: ResourceGraphDefinition
metadata:
  name: nginxapp-graph
spec:
  resourceKind:
    group: kro.example.com
    kind: NginxApp
    version: v1
  childResources:
    - apiVersion: apps/v1
      kind: Deployment
      nameTemplate: "{{.parent.metadata.name}}"
      template: |
        spec:
          replicas: {{.parent.spec.replicas}}
          selector:
            matchLabels:
              app: {{.parent.metadata.name}}
          template:
            metadata:
              labels:
                app: {{.parent.metadata.name}}
            spec:
              containers:
              - name: nginx
                image: {{.parent.spec.image.repository}}:{{.parent.spec.image.tag}}
                imagePullPolicy: {{.parent.spec.image.pullPolicy}}
                ports:
                - containerPort: {{.parent.spec.service.port}}
                resources:
                  {{- if .parent.spec.resources }}
                  limits:
                    {{- if .parent.spec.resources.limits.cpu }}
                    cpu: {{.parent.spec.resources.limits.cpu}}
                    {{- end }}
                    {{- if .parent.spec.resources.limits.memory }}
                    memory: {{.parent.spec.resources.limits.memory}}
                    {{- end }}
                  requests:
                    {{- if .parent.spec.resources.requests.cpu }}
                    cpu: {{.parent.spec.resources.requests.cpu}}
                    {{- end }}
                    {{- if .parent.spec.resources.requests.memory }}
                    memory: {{.parent.spec.resources.requests.memory}}
                    {{- end }}
                  {{- end }}

    - apiVersion: v1
      kind: Service
      nameTemplate: "{{.parent.metadata.name}}"
      template: |
        spec:
          selector:
            app: {{.parent.metadata.name}}
          ports:
          - port: {{.parent.spec.service.port}}
            targetPort: {{.parent.spec.service.port}}
          type: {{.parent.spec.service.type}}

    - apiVersion: networking.k8s.io/v1
      kind: Ingress
      nameTemplate: "{{.parent.metadata.name}}"
      condition: "{{.parent.spec.ingress.enabled}}"
      template: |
        spec:
          rules:
          {{- range .parent.spec.ingress.hosts }}
          - host: {{.host}}
            http:
              paths:
              {{- range .paths }}
              - path: {{.path}}
                pathType: {{.pathType}}
                backend:
                  service:
                    name: {{$.parent.metadata.name}}
                    port:
                      number: {{$.parent.spec.service.port}}
              {{- end }}
          {{- end }}

  statusMappings:
    - childResource:
        kind: Deployment
        name: "{{.parent.metadata.name}}"
      conditions:
        - type: Available
          mapping:
            type: Ready
      fieldMappings:
        - child: "status.availableReplicas"
          parent: "status.availableReplicas"
        - child: "status.readyReplicas"
          parent: "status.readyReplicas"

    - childResource:
        kind: Service
        name: "{{.parent.metadata.name}}"
      fieldMappings:
        - child: "spec.clusterIP"
          parent: "status.serviceIP"
```

### KRO Custom Resource 实例

```yaml
apiVersion: kro.example.com/v1
kind: NginxApp
metadata:
  name: my-nginx
spec:
  replicas: 2
  image:
    repository: nginx
    tag: 1.21.0
    pullPolicy: IfNotPresent
  service:
    type: ClusterIP
    port: 80
  ingress:
    enabled: true
    hosts:
      - host: example.com
        paths:
          - path: /
            pathType: Prefix
  resources:
    limits:
      cpu: 100m
      memory: 128Mi
    requests:
      cpu: 50m
      memory: 64Mi
```

### 部署和验证

```bash
# Apply CRD and RGD
kubectl apply -f nginxapp-crd.yaml
kubectl apply -f nginxapp-rgd.yaml

# Apply custom resource instance
kubectl apply -f my-nginx.yaml

# Verify created resources
kubectl get deployments,services,ingress -l app=my-nginx

# Check custom resource status
kubectl get nginxapp my-nginx -o yaml
```

## KRO 使用场景

### 1. 微服务应用管理

KRO 非常适合管理由多个组件组成的微服务应用。每个微服务可以由以下资源组成：

* Deployment 或 StatefulSet
* Service
* ConfigMap
* Secret
* HorizontalPodAutoscaler
* PodDisruptionBudget

使用 KRO，你可以显式定义这些资源之间的关系，并通过单个 Custom Resource 管理整个微服务。

### 2. 数据库集群管理

数据库集群（例如 PostgreSQL、MySQL）需要多个组件和复杂配置。KRO 可以管理以下资源：

* Master 和 replica StatefulSets
* Service endpoints
* Persistent volume claims
* 备份和恢复 Jobs
* 监控配置

### 3. 多集群应用部署

KRO 也可用于管理跨多个 Kubernetes 集群的应用。这支持以下场景：

* 区域部署
* 在开发、预发布和生产环境之间保持一致的部署
* 混合云环境中的应用管理

## KRO 最佳实践

### 1. 资源图设计

* **单一职责原则**：每个 Custom Resource 都应具有明确的单一职责。
* **适当的抽象级别**：选择既不过于详细也不过于抽象的适当抽象级别。
* **清晰边界**：清楚定义资源之间的边界和职责。
* **可复用性**：识别常见模式并将其提取为可复用组件。

### 2. 状态管理

* **有意义的状态**：向用户提供有意义的状态信息。
* **状态聚合**：适当聚合来自多个子资源的状态。
* **条件定义**：定义清晰的 Condition 类型和状态。
* **诊断信息**：包含有助于故障排查的诊断信息。

### 3. 版本管理

* **API 版本管理**：妥善管理 Custom Resource API 版本。
* **Conversion Webhooks**：实现用于版本转换的 Webhook。
* **向后兼容性**：在可能的情况下保持向后兼容性。
* **渐进迁移**：逐步引入重大变更。

### 4. 安全性

* **最小权限**：仅向 Controller 授予最低必要权限。
* **RBAC 策略**：定义适当的 RBAC 策略以控制访问。
* **Secret 管理**：将敏感信息作为 Secrets 管理。
* **Validation Webhooks**：实现用于输入验证的 Webhook。

## 结论

从 Helm 迁移到 KRO 是转向 Kubernetes 原生方法的重要一步。这使应用管理更加声明式、可扩展，并且更适合 GitOps。尤其对于复杂应用，KRO 提供了更细粒度的控制和改进的版本管理。

ResourceGraphDefinition (RGD) 是 KRO 的核心概念，提供了显式定义资源之间关系并传播状态的机制。这使复杂应用结构更易于建模和管理。

迁移过程需要额外的初始工作，但在长期维护和运维方面会带来显著收益。通过渐进式迁移方法，你可以在利用 KRO 优势的同时最大限度降低风险。

虽然 KRO 仍是一项不断演进的技术，但它代表了一种重要方法，展示了 Kubernetes 生态系统未来的发展方向。声明式 API、资源关系建模和状态传播等概念正在成为云原生应用管理的核心原则。

## 测验

要测试你在本章中学到的内容，请尝试 [KRO 测验](/kubernetes/cn/ce-yan-ji-he/quizzes/03-kro-quiz.md)。