**帮助改进此页面** 

要帮助改进本用户指南，请选择位于每个页面右侧窗格中的**在 GitHub 上编辑此页面**链接。

# kro 概念
<a name="kro-concepts"></a>

kro 支持平台团队创建自定义 Kubernetes API，将多个资源组合为更高级别的抽象资源。本主题会先引导您完成一个实操案例的演练，再详细阐释使用 EKS 托管型 kro 所需掌握的核心概念。

## kro 入门
<a name="_getting_started_with_kro"></a>

创建 kro 托管功能后（详见[创建 kro 功能](create-kro-capability.md)文档），即可开始在集群中通过 ResourceGraphDefinition 来创建自定义 API。

以下完整示例用于创建简单的 Web 应用程序抽象资源：

```
apiVersion: kro.run/v1alpha1
kind: ResourceGraphDefinition
metadata:
  name: webapplication
spec:
  schema:
    apiVersion: v1alpha1
    kind: WebApplication
    group: kro.run
    spec:
      name: string | required=true
      image: string | default="nginx:latest"
      replicas: integer | default=3
  resources:
  - id: deployment
    template:
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: ${schema.spec.name}
      spec:
        replicas: ${schema.spec.replicas}
        selector:
          matchLabels:
            app: ${schema.spec.name}
        template:
          metadata:
            labels:
              app: ${schema.spec.name}
          spec:
            containers:
            - name: app
              image: ${schema.spec.image}
              ports:
              - containerPort: 80
  - id: service
    template:
      apiVersion: v1
      kind: Service
      metadata:
        name: ${schema.spec.name}
      spec:
        selector:
          app: ${schema.spec.name}
        ports:
        - protocol: TCP
          port: 80
          targetPort: 80
```

应用该 ResourceGraphDefinition 后，应用团队即可通过您定义的简化版 API 来创建 Web 应用程序：

```
apiVersion: kro.run/v1alpha1
kind: WebApplication
metadata:
  name: my-app
spec:
  name: my-app
  replicas: 5
```

kro 会自动创建带有相应配置的 Deployment 和 Service 资源。由于配置中未指定 `image` 参数，系统会采用模式定义中预设的默认值 `nginx:latest`。

## 核心概念
<a name="_core_concepts"></a>

**重要**  
kro 会在创建阶段对 ResourceGraphDefinition 进行验证，而非在运行时阶段。当您创建一个 RGD 时，kro 会执行以下验证操作：校验 CEL 语法的正确性、基于实际的 Kubernetes 模式对表达式进行类型检查、验证字段是否存在、检测是否存在循环依赖。这意味着相关错误会在创建 RGD 时被立即发现，无需等到部署任何实例之后。

### ResourceGraphDefinition
<a name="_resourcegraphdefinition"></a>

ResourceGraphDefinition（RGD）通过配置以下内容来定义一种 Kubernetes 自定义 API：
+  **Schema**：采用 SimpleSchema 格式定义的 API 结构（字段名称、字段类型、默认值及验证规则）
+  **Resources**：待创建的底层 Kubernetes 资源或 Amazon 资源的模板
+  **Dependencies**：资源之间的关联方式（会通过字段引用自动识别）

当您应用一份 RGD 配置后，kro 会在集群中注册一个全新的自定义资源定义（CRD）。之后应用团队即可创建该自定义 API 的实例，由 kro 负责创建并管理所有对应的底层资源。

有关更多信息，请参阅 kro 文档中的 [ResourceGraphDefinition Overview](https://kro.run/docs/concepts/rgd/overview/)。

### SimpleSchema 格式
<a name="_simpleschema_format"></a>

SimpleSchema 提供了一种简化的 API 模式定义方式，无需使用者掌握 OpenAPI 相关知识：

```
schema:
  apiVersion: v1alpha1
  kind: Database
  spec:
    name: string | required=true description="Database name"
    size: string | default="small" enum=small,medium,large
    replicas: integer | default=1 minimum=1 maximum=5
```

SimpleSchema 支持 `string`、`integer`、`boolean` 和 `number` 等类型，并可配置 `required`、`default`、`minimum`/`maximum`、`enum` 和 `pattern` 等约束规则。

有关更多信息，请参阅 kro 文档中的 [SimpleSchema](https://kro.run/docs/concepts/rgd/schema/)。

### CEL 表达式
<a name="_cel_expressions"></a>

kro 采用公共表达式语言（CEL）来实现值的动态引用和条件逻辑的添加。CEL 表达式需要包裹在 `${` 与 `}` 之内，主要有两种使用方式：

 **独立表达式**：字段的完整值由单个表达式构成：

```
spec:
  replicas: ${schema.spec.replicaCount}  # Expression returns integer
  labels: ${schema.spec.labelMap}        # Expression returns object
```

表达式的计算结果会直接替换整个字段的值，且结果类型必须与字段预期的类型相匹配。

 **字符串模板**：在字符串中嵌入一个或多个表达式：

```
metadata:
  name: "${schema.spec.prefix}-${schema.spec.name}"  # Multiple expressions
  annotation: "Created by ${schema.spec.owner}"      # Single expression in string
```

字符串模板中的所有表达式必须返回字符串类型。若要转换其他类型，可使用 `string()` 函数，例如：`"replicas-${string(schema.spec.count)}"`。

 **字段引用**：通过 `schema.spec` 访问实例的规格参数：

```
template:
  metadata:
    name: ${schema.spec.name}-deployment
    namespace: ${schema.metadata.namespace}  # Can also reference metadata
  spec:
    replicas: ${schema.spec.replicas}
```

 **可选字段访问**：对于可能不存在的字段，可使用 `?` 符号，例如：

```
# For ConfigMaps or Secrets with unknown structure
value: ${configmap.data.?DATABASE_URL}

# For optional status fields
ready: ${deployment.status.?readyReplicas > 0}
```

若目标字段不存在，表达式会返回 `null` 而非直接执行失败。

 **条件式资源**：仅在满足指定条件时才创建资源：

```
resources:
- id: ingress
  includeWhen:
    - ${schema.spec.enableIngress == true}
  template:
    # ... ingress configuration
```

`includeWhen` 字段会接收一份布尔表达式列表。只有所有表达式结果均为 true，对应的资源才会被创建。目前 `includeWhen` 仅支持引用 `schema.spec` 中的字段。

 **数据转换**：通过三元运算符与函数实现值的转换处理：

```
template:
  spec:
    resources:
      requests:
        memory: ${schema.spec.size == "small" ? "512Mi" : "2Gi"}

    # String concatenation
    image: ${schema.spec.registry + "/" + schema.spec.imageName}

    # Type conversion
    port: ${string(schema.spec.portNumber)}
```

 **跨资源引用**：引用其他资源的值：

```
resources:
- id: bucket
  template:
    apiVersion: s3.services.k8s.aws/v1alpha1
    kind: Bucket
    spec:
      name: ${schema.spec.name}-data

- id: configmap
  template:
    apiVersion: v1
    kind: ConfigMap
    data:
      BUCKET_NAME: ${bucket.spec.name}
      BUCKET_ARN: ${bucket.status.ackResourceMetadata.arn}
```

当您在 CEL 表达式中引用另一资源时，kro 会自动创建资源间的依赖关系，并确保被引用的资源优先完成创建。

有关更多信息，请参阅 kro 文档中的 [CEL Expressions](https://kro.run/docs/concepts/rgd/cel-expressions/)。

### 资源依赖关系
<a name="_resource_dependencies"></a>

kro 会通过 CEL 表达式自动推导资源间的依赖关系，无需您手动指定资源的创建顺序，只需描述资源之间的关联逻辑即可。当某一资源通过 CEL 表达式引用另一资源时，kro 会自动创建两者的依赖关系，并确定正确的资源创建顺序。

```
resources:
- id: bucket
  template:
    apiVersion: s3.services.k8s.aws/v1alpha1
    kind: Bucket
    spec:
      name: ${schema.spec.name}-data

- id: notification
  template:
    apiVersion: s3.services.k8s.aws/v1alpha1
    kind: BucketNotification
    spec:
      bucket: ${bucket.spec.name}  # Creates dependency: notification depends on bucket
```

表达式 `${bucket.spec.name}` 会触发依赖关系的生成。kro 会为所有资源及其依赖关系构建一个有向无环图（DAG），再据此计算出资源的拓扑创建顺序。

 **创建顺序**：资源会按照拓扑顺序进行创建（被依赖的资源优先创建）。

 **并行创建**：无依赖关系的资源会被同时创建。

 **删除顺序**：资源会按照拓扑顺序的逆序进行删除（依赖方优先被删除）。

 **循环依赖**：不被允许。kro 会在 ResourceGraphDefinition 验证阶段，直接拒绝存在循环依赖的配置。

您可以查看系统计算出的资源创建顺序：

```
kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.status.topologicalOrder}'
```

有关更多信息，请参阅 kro 文档中的 [Graph inference](https://kro.run/docs/concepts/rgd/dependencies-ordering/)。

## 与 ACK 的组合编排
<a name="_composing_with_ack"></a>

kro 可与 EKS 托管型 ACK 无缝协同，实现 Amazon 资源与 Kubernetes 资源的组合编排：

```
resources:
# Create {aws} S3 bucket with ACK
- id: bucket
  template:
    apiVersion: s3.services.k8s.aws/v1alpha1
    kind: Bucket
    spec:
      name: ${schema.spec.name}-files

# Inject bucket details into Kubernetes ConfigMap
- id: config
  template:
    apiVersion: v1
    kind: ConfigMap
    data:
      BUCKET_NAME: ${bucket.spec.name}
      BUCKET_ARN: ${bucket.status.ackResourceMetadata.arn}

# Use ConfigMap in application deployment
- id: deployment
  template:
    apiVersion: apps/v1
    kind: Deployment
    spec:
      template:
        spec:
          containers:
          - name: app
            envFrom:
            - configMapRef:
                name: ${config.metadata.name}
```

这种模式支持您创建 Amazon 资源、提取其详细信息（如 ARN、URL、端点）并注入应用配置，且所有操作均作为单一单元进行管理。

有关更多组合编排模式及进阶示例，请参阅 [EKS 托管型 kro 注意事项](kro-considerations.md)。

## 后续步骤
<a name="_next_steps"></a>
+  [EKS 托管型 kro 注意事项](kro-considerations.md)：了解 EKS 专属模式、RBAC 以及与 ACK、Argo CD 的集成方法
+  [kro 文档](https://kro.run/docs/overview)：包含进阶 CEL 表达式、验证模式及问题排查方案的完整 kro 文档