**帮助改进此页面** 要帮助改进本用户指南，请选择位于每个页面右侧窗格中的**在 GitHub 上编辑此页面**链接。 # 使用 kro（Kube Resource Orchestrator）组合编排资源 **kro（Kube Resource Orchestrator）**是一个 Kubernetes 原生开源项目，支持通过简洁直观的配置来定义自定义 Kubernetes API。借助 kro，您可以轻松配置全新的自定义 API，这些 API 可用于创建一组 Kubernetes 对象，并定义对象之间的逻辑操作。 基于 EKS 功能，kro 由 AWS 提供全托管服务，无需您在集群中安装、维护和扩缩 kro 控制器。 ## kro 工作原理 kro 引入了一种名为 `ResourceGraphDefinition`（RGD）的自定义资源定义（CRD），支持以简洁高效的方式创建自定义 Kubernetes API。在您创建 `ResourceGraphDefinition` 后，kro 会借助 Kubernetes 原生扩展能力，在集群中创建并管理这些新的 API。基于这份单一的资源规范，kro 会自动根据您的配置创建并注册一个全新的 CRD，同时自适应地管理您所定义的这些新自定义资源。 RGD 可包含多种资源，kro 会自动判断资源间的依赖关系与创建顺序，无需人工干预。您能够通过简单的语法，将配置信息从一个资源注入另一个资源，极大简化了资源组合编排流程，不再需要在集群中部署用于资源衔接的“粘合型”控制器。借助 kro，您所定义的自定义资源既可以包含 Kubernetes 原生资源，也能够兼容集群中已安装的任意自定义资源定义（CRD）。 kro 仅支持一种核心资源类型： + **ResourceGraphDefinition (RGD)**：定义一种 Kubernetes 自定义资源，该资源可封装一个或多个底层的 Kubernetes 原生资源或自定义资源 除该核心资源外，kro 还会负责创建并管理由其生成的自定义资源的生命周期，同时管理这些自定义资源所包含的全部组成资源。 kro 可与 AWS Controllers for Kubernetes（ACK）无缝集成，支持您将工作负载资源与 AWS 资源进行组合，从而创建更高级别的抽象资源。此能力可帮助您构建专属的云基础设施组件，简化资源管理流程，并能基于企业标准配置默认值与不可变配置项，形成可复用的模式。 ## kro 优势 kro 支持平台团队创建自定义 Kubernetes API，将多个资源组合为更高级别的抽象资源。这一能力可以简化资源管理工作，开发者只需通过简洁、标准化且带版本控制的自定义资源，就能完成复杂应用的部署。您可以为常用的资源组合定义可复用模式，在企业内部实现一致化的资源创建流程。 kro 在 [Kubernetes 环境中采用公共表达式语言（CEL）](https://kubernetes.io/docs/reference/using-api/cel/)实现资源间的值传递与条件逻辑配置，让资源组合编排具备更强的灵活性。您既可以组合 Kubernetes 原生资源，也能将 ACK 管理的 AWS 资源纳入其中，构建出一体化的自定义 API，从而实现应用与基础设施的完整定义。 kro 支持通过 Kubernetes 清单完成声明式配置，可无缝对接 GitOps 工作流程与基础设施即代码实践，与您现有的开发流程深度融合。作为 EKS 托管功能的一部分，kro 由 AWS 提供全托管服务，无需您在集群中安装、配置和维护 kro 控制器。 **示例：创建 ResourceGraphDefinition** 以下示例展示了一个简单的 `ResourceGraphDefinition` 配置，用于创建一个包含 Deployment 和 Service 的 Web 应用： ``` apiVersion: kro.run/v1alpha1 kind: ResourceGraphDefinition metadata: name: web-application spec: schema: apiVersion: v1alpha1 kind: WebApplication spec: name: string replicas: integer | default=3 resources: - id: deployment template: apiVersion: apps/v1 kind: Deployment metadata: name: ${schema.spec.name} spec: replicas: ${schema.spec.replicas} - id: service template: apiVersion: v1 kind: Service metadata: name: ${schema.spec.name} ``` 当用户创建 `WebApplication` 自定义资源实例时，kro 会自动生成对应的 Deployment 与 Service 资源，并将其生命周期与自定义资源进行统一管理。 ## 与其他 EKS 托管功能集成 kro 与其他 EKS 托管功能集成。 + **AWS Controllers for Kubernetes（ACK）**：借助 kro 将 ACK 资源组合为更高级别的抽象资源，简化 AWS 资源的管理流程。 + **Argo CD**：通过 Argo CD 管理 kro 自定义资源在多集群的部署，为平台基础设施组件与应用栈启用 GitOps 工作流程。 ## kro 入门 若要开始使用 EKS 托管型 kro，可按照以下步骤操作： 1. 通过 AWS 控制台、AWS CLI 或您偏好的基础设施即代码工具，在 EKS 集群上[创建 kro 功能资源](create-kro-capability.md)。 1. 创建 ResourceGraphDefinition（RGD），定义自己的自定义 API 与资源组合编排规则。 1. 应用自定义资源实例，完成底层 Kubernetes 资源与 AWS 资源的配置和管理。 # 创建 kro 功能 本主题旨在介绍如何在 Amazon EKS 集群上创建 kro 功能。 ## 先决条件 创建 kro 功能之前，确保满足以下条件： + 运行受支持 Kubernetes 版本的现有 Amazon EKS 集群（标准支持与扩展支持范围内的所有版本均适用） + 可在 EKS 集群上创建功能资源的充足 IAM 权限 + （适用于 CLI/eksctl）已安装并配置相应 CLI 工具 **注意** 与 ACK 和 Argo CD 不同，kro 除信任策略外，无需额外的 IAM 权限。kro 完全在集群中运行，不会发起 AWS API 调用。不过，您仍需提供一个配置了相应信任策略的 IAM 功能角色。有关配置 Kubernetes RBAC 权限的信息，请参阅[配置 kro 权限](kro-permissions.md)。 ## 选择工具 您可以使用AWS 管理控制台、AWS CLI 或 eksctl 创建 kro 功能： + [使用控制台创建 kro 功能](kro-create-console.md)：使用控制台获得引导式体验 + [使用 AWS CLI 创建 kro 功能](kro-create-cli.md)：使用 AWS CLI 进行脚本编写和自动化 + [使用 eksctl 创建 kro 功能](kro-create-eksctl.md)：使用 eksctl 获得 Kubernetes 原生体验 ## 在创建 kro 功能时会执行的操作 在创建 kro 功能时： 1. EKS 会创建 kro 功能服务，并配置该服务来监控和管理集群内的资源 1. 自定义资源定义（CRD）将被安装到集群中 1. 系统会使用 `AmazonEKSKROPolicy` 自动为您的 IAM 功能角色创建一个访问条目，该条目授予管理 ResourceGraphDefinitions 及其实例的权限（请参阅 [EKS 功能的安全注意事项](capabilities-security.md)） 1. 该功能会代入您提供的 IAM 功能角色（此角色仅用于信任关系配置） 1. kro 开始监听 `ResourceGraphDefinition` 资源及其对应的实例 1. 功能状态从 `CREATING` 更改为 `ACTIVE` 功能进入运行状态后，即可创建 ResourceGraphDefinition，以此定义自定义 API，并创建这些 API 对应的实例。 **注意** 自动创建的访问条目包括授予 kro 管理 ResourceGraphDefinitions 及其实例的权限的 `AmazonEKSKROPolicy`。要允许 kro 创建 ResourceGraphDefinitions 中定义的底层 Kubernetes 资源（例如部署、服务或 ACK 资源），则必须配置额外的访问条目权限。要了解有关访问条目以及如何配置其他权限的更多信息，请参阅 [配置 kro 权限](kro-permissions.md) 和 [EKS 功能的安全注意事项](capabilities-security.md)。 ## 后续步骤 创建 kro 功能后： + [kro 概念](kro-concepts.md)：了解 kro 的基本概念及资源组合编排 + [kro 概念](kro-concepts.md)：了解 SimpleSchema、CEL 表达式及资源组合编排模式 # 使用控制台创建 kro 功能 本主题旨在介绍如何使用 AWS 管理控制台 创建 kro（Kube Resource Orchestrator）功能。 ## 创建 kro 功能 1. 从以下位置打开 Amazon EKS 控制台：https://console.aws.amazon.com/eks/home\$1/clusters。 1. 选择集群名称，打开集群详细信息页面。 1. 选择**功能**选项卡。 1. 在左侧导航栏中，选择 **kro（Kube Resource Orchestrator）**。 1. 选择**创建 kro 功能**。 1. 对于 **IAM 功能角色**： + 如果已有 IAM 功能角色，请从下拉列表中选择该角色 + 如需创建角色，请选择**创建 kro 角色** 此操作会在新选项卡中打开 IAM 控制台，其中包含预填充的信任策略。该角色无需配置额外的 IAM 权限，因为 kro 的所有操作均在集群内部完成。 创建角色后，返回 EKS 控制台，系统将自动选择该角色。 **注意** 与 ACK 和 Argo CD 不同，kro 除信任策略外，无需额外的 IAM 权限。kro 完全在集群中运行，不会发起 AWS API 调用。 1. 选择**创建**。 功能创建过程随即开始。 ## 验证功能是否处于活动状态 1. 在**功能**选项卡上，查看 kro 功能状态。 1. 等待状态从 `CREATING` 更改为 `ACTIVE`。 1. 变为活动状态后，该功能即可使用。 有关功能状态和问题排查的信息，请参阅[使用功能资源](working-with-capabilities.md)。 ## 授予 Kubernetes 资源管理权限 当您创建 kro 功能时，系统会使用 `AmazonEKSKROPolicy` 自动创建 EKS 访问条目，该条目允许 kro 管理 ResourceGraphDefinitions 及其实例。但是，默认情况下，不授予任何权限来创建 ResourceGraphDefinitions 中定义的底层 Kubernetes 资源（如部署、服务、ConfigMaps 等）。 这种有意的设计遵循了最低权限原则，即不同的 ResourceGraphDefinitions 需要不同的权限。您必须根据您的 ResourceGraphDefinitions 将管理的资源明确配置 kro 所需的权限。 对于快速入门、测试或开发环境，请使用 `AmazonEKSClusterAdminPolicy`： 1. 在 EKS 控制台中，导航到 EKS 集群的**访问**选项卡。 1. 在**访问条目**下，找到对应 kro 功能角色的条目（将包含之前创建的角色 ARN）。 1. 选择访问条目，打开对应的详细信息页面。 1. 在**访问策略**部分，选择**关联访问策略**。 1. 从策略列表中选择 `AmazonEKSClusterAdminPolicy`。 1. 在**访问范围**中，选择**集群**。 1. 选择**关联 **。 **重要** `AmazonEKSClusterAdminPolicy` 会授予宽泛的权限，以创建和管理所有的 Kubernetes 资源，包括能够在所有命名空间中创建任何类型的资源的权限。这便于开发和 POC，但不应在生产环境中使用。在生产环境使用时，请创建自定义 RBAC 策略，仅授予 ResourceGraphDefinition 需管理的特定资源对应的权限。有关配置最低权限的指引，请参阅[配置 kro 权限](kro-permissions.md)和 [EKS 功能的安全注意事项](capabilities-security.md)。 ## 验证自定义资源是否可用 待该功能处于激活状态后，验证 kro 自定义资源是否已在集群中正常可用。 **使用控制台** 1. 在 Amazon EKS 控制台中导航至集群 1. 选择**资源**选项卡 1. 选择**扩展** 1. 选择 **CustomResourceDefinitions** 您应能看到 `ResourceGraphDefinition` 这一资源类型已被列出。 **使用 kubectl** ``` kubectl api-resources | grep kro.run ``` 您应能看到 `ResourceGraphDefinition` 这一资源类型已被列出。 ## 后续步骤 + [kro 概念](kro-concepts.md)：了解 kro 的基本概念及资源组合编排 + [kro 概念](kro-concepts.md)：了解 SimpleSchema、CEL 表达式和组合编排模式 + [使用功能资源](working-with-capabilities.md)：管理 kro 功能资源 # 使用 AWS CLI 创建 kro 功能 本主题旨在介绍如何使用 AWS CLI 创建 kro（Kube Resource Orchestrator）功能。 ## 先决条件 + **AWS CLI**：版本 `2.12.3` 或更高版本。要检查版本，请运行 `aws --version`。有关更多信息，请参阅《AWS 命令行界面用户指南》中的[安装](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)。 + **`kubectl`**：用于与 Kubernetes 集群结合使用的命令行工具。有关更多信息，请参阅 [设置 `kubectl` 和 `eksctl`](install-kubectl.md)。 ## 步骤 1：创建 IAM 功能角色 创建信任策略文件： ``` cat > kro-trust-policy.json << 'EOF' { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "capabilities.eks.amazonaws.com" }, "Action": [ "sts:AssumeRole", "sts:TagSession" ] } ] } EOF ``` 创建 IAM 角色： ``` aws iam create-role \ --role-name KROCapabilityRole \ --assume-role-policy-document file://kro-trust-policy.json ``` **注意** 与 ACK 和 Argo CD 不同，kro 无需额外的 IAM 权限。kro 完全在集群中运行，不会发起 AWS API 调用。只有在与 EKS 功能服务建立信任关系时，才需要该角色。 ## 步骤 2：创建 kro 功能 在集群上创建 kro 功能资源。将 *region-code* 替换为集群所在的 AWS 区域（例如 `us-west-2`），并将 *my-cluster* 替换为集群的实际名称。 ``` aws eks create-capability \ --region region-code \ --cluster-name my-cluster \ --capability-name my-kro \ --type KRO \ --role-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/KROCapabilityRole \ --delete-propagation-policy RETAIN ``` 命令会立即返回，但是由于 EKS 正在创建所需的功能基础设施和组件，该功能需要一些时间才能变为活动状态。在创建集群时，EKS 将在集群中安装与此功能相关的 Kubernetes 自定义资源定义。 **注意** 如果收到集群不存在或您没有权限的错误消息，请验证： 集群名称是否正确 AWS CLI 是否针对正确的区域进行配置 您是否拥有所需的 IAM 权限 ## 步骤 3：验证功能是否处于活动状态 等待功能变为活动状态。将 *region-code* 替换为您的集群所在的 AWS 区域，并将 *my-cluster* 替换为您的集群的名称。 ``` aws eks describe-capability \ --region region-code \ --cluster-name my-cluster \ --capability-name my-kro \ --query 'capability.status' \ --output text ``` 当状态显示为 `ACTIVE` 时，表示功能已准备就绪。 您也可以查看完整功能详细信息： ``` aws eks describe-capability \ --region region-code \ --cluster-name my-cluster \ --capability-name my-kro ``` ## 步骤 4：授予 Kubernetes 资源管理权限 当您创建 kro 功能时，系统会使用 `AmazonEKSKROPolicy` 自动创建 EKS 访问条目，该条目允许 kro 管理 ResourceGraphDefinitions 及其实例。但是，默认情况下，不授予任何权限来创建 ResourceGraphDefinitions 中定义的底层 Kubernetes 资源（如部署、服务、ConfigMaps 等）。 这种有意的设计遵循了最低权限原则，即不同的 ResourceGraphDefinitions 需要不同的权限。例如：\$1 一个仅创建 ConfigMaps 和密钥的 ResourceGraphDefinition 所需的权限与创建部署和服务所需的权限不同 \$1 创建 ACK 资源的 ResourceGraphDefinition 需要针对这些特定自定义资源的权限 \$1 一些 ResourceGraphDefinitions 可能只是读取现有的资源，而不会创建新的资源 您必须根据您的 ResourceGraphDefinitions 将管理的资源明确配置 kro 所需的权限。 ### 快速设置 对于快速入门、测试或开发环境，请使用 `AmazonEKSClusterAdminPolicy`： 获取功能角色的 ARN： ``` CAPABILITY_ROLE_ARN=$(aws eks describe-capability \ --region region-code \ --cluster-name my-cluster \ --capability-name my-kro \ --query 'capability.roleArn' \ --output text) ``` 关联集群管理员策略： ``` aws eks associate-access-policy \ --region region-code \ --cluster-name my-cluster \ --principal-arn $CAPABILITY_ROLE_ARN \ --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \ --access-scope type=cluster ``` **重要** `AmazonEKSClusterAdminPolicy` 会授予宽泛的权限，以创建和管理所有的 Kubernetes 资源，包括能够在所有命名空间中创建任何类型的资源的权限。这便于开发和 POC，但不应在生产环境中使用。在生产环境使用时，请创建自定义 RBAC 策略，仅授予 ResourceGraphDefinition 需管理的特定资源对应的权限。有关配置最低权限的指引，请参阅[配置 kro 权限](kro-permissions.md)和 [EKS 功能的安全注意事项](capabilities-security.md)。 ## 步骤 5：验证自定义资源是否可用 待该功能处于激活状态后，验证 kro 自定义资源是否已在集群中正常可用： ``` kubectl api-resources | grep kro.run ``` 您应能看到 `ResourceGraphDefinition` 这一资源类型已被列出。 ## 后续步骤 + [kro 概念](kro-concepts.md)：了解 kro 的基本概念及资源组合编排 + [kro 概念](kro-concepts.md)：了解 SimpleSchema、CEL 表达式和组合编排模式 + [使用功能资源](working-with-capabilities.md)：管理 kro 功能资源 # 使用 eksctl 创建 kro 功能 本主题旨在介绍如何使用 eksctl 创建 kro（Kube Resource Orchestrator）功能。 **注意** 以下步骤需要 eksctl 版本 `0.220.0` 或更高版本。要检查版本，请运行 `eksctl version`。 ## 步骤 1：创建 IAM 功能角色 创建信任策略文件： ``` cat > kro-trust-policy.json << 'EOF' { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "capabilities.eks.amazonaws.com" }, "Action": [ "sts:AssumeRole", "sts:TagSession" ] } ] } EOF ``` 创建 IAM 角色： ``` aws iam create-role \ --role-name KROCapabilityRole \ --assume-role-policy-document file://kro-trust-policy.json ``` **注意** 与 ACK 和 Argo CD 不同，kro 除信任策略外，无需额外的 IAM 权限。kro 完全在集群中运行，不会发起 AWS API 调用。 ## 步骤 2：创建 kro 功能 使用 eksctl 创建 kro 功能。将 *region-code* 替换为您的集群所在的 AWS 区域，并将 *my-cluster* 替换为您的集群的名称。 ``` eksctl create capability \ --region region-code \ --cluster my-cluster \ --name my-kro \ --type KRO \ --role-arn arn:aws:iam::[.replaceable]111122223333:role/KROCapabilityRole ``` 命令会立即返回，但该功能需要一些时间才能变为活动状态。 ## 步骤 3：验证功能是否处于活动状态 检查功能状态。将 *region-code* 替换为您的集群所在的 AWS 区域，并将 *my-cluster* 替换为您的集群的名称。 ``` eksctl get capability \ --region region-code \ --cluster my-cluster \ --name my-kro ``` 当状态显示为 `ACTIVE` 时，表示功能已准备就绪。 ## 步骤 4：授予 Kubernetes 资源管理权限 默认情况下，kro 仅能创建和管理 ResourceGraphDefinition 及其对应的实例。若要允许 kro 创建和管理 ResourceGraphDefinition 中定义的底层 Kubernetes 资源，需将 `AmazonEKSClusterAdminPolicy` 访问策略关联到该功能的访问条目。 获取功能角色的 ARN： ``` CAPABILITY_ROLE_ARN=$(aws eks describe-capability \ --region region-code \ --cluster my-cluster \ --name my-kro \ --query 'capability.roleArn' \ --output text) ``` 关联集群管理员策略： ``` aws eks associate-access-policy \ --region region-code \ --cluster my-cluster \ --principal-arn $CAPABILITY_ROLE_ARN \ --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \ --access-scope type=cluster ``` **重要** `AmazonEKSClusterAdminPolicy` 会授予宽泛的权限，支持创建和管理所有 Kubernetes 资源，该策略的设计目的是简化功能的入门流程。在生产环境使用时，请创建权限范围更严格的 RBAC 策略，仅授予 ResourceGraphDefinition 需管理的特定资源对应的权限。有关配置最低权限的指引，请参阅[配置 kro 权限](kro-permissions.md)和 [EKS 功能的安全注意事项](capabilities-security.md)。 ## 步骤 5：验证自定义资源是否可用 待该功能处于激活状态后，验证 kro 自定义资源是否已在集群中正常可用： ``` kubectl api-resources | grep kro.run ``` 您应能看到 `ResourceGraphDefinition` 这一资源类型已被列出。 ## 后续步骤 + [kro 概念](kro-concepts.md)：了解 kro 的基本概念及资源组合编排 + [kro 概念](kro-concepts.md)：了解 SimpleSchema、CEL 表达式和组合编排模式 + [使用功能资源](working-with-capabilities.md)：管理 kro 功能资源 # kro 概念 kro 支持平台团队创建自定义 Kubernetes API，将多个资源组合为更高级别的抽象资源。本主题会先引导您完成一个实操案例的演练，再详细阐释使用 EKS 托管型 kro 所需掌握的核心概念。 ## kro 入门 创建 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`。 ## 核心概念 **重要** kro 会在创建阶段对 ResourceGraphDefinition 进行验证，而非在运行时阶段。当您创建一个 RGD 时，kro 会执行以下验证操作：校验 CEL 语法的正确性、基于实际的 Kubernetes 模式对表达式进行类型检查、验证字段是否存在、检测是否存在循环依赖。这意味着相关错误会在创建 RGD 时被立即发现，无需等到部署任何实例之后。 ### ResourceGraphDefinition ResourceGraphDefinition（RGD）通过配置以下内容来定义一种 Kubernetes 自定义 API： + **Schema**：采用 SimpleSchema 格式定义的 API 结构（字段名称、字段类型、默认值及验证规则） + **Resources**：待创建的底层 Kubernetes 资源或 AWS 资源的模板 + **Dependencies**：资源之间的关联方式（会通过字段引用自动识别） 当您应用一份 RGD 配置后，kro 会在集群中注册一个全新的自定义资源定义（CRD）。之后应用团队即可创建该自定义 API 的实例，由 kro 负责创建并管理所有对应的底层资源。 有关更多信息，请参阅 kro 文档中的 [ResourceGraphDefinition Overview](https://kro.run/docs/concepts/rgd/overview/)。 ### SimpleSchema 格式 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 表达式 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/)。 ### 资源依赖关系 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 的组合编排 kro 可与 EKS 托管型 ACK 无缝协同，实现 AWS 资源与 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} ``` 这种模式支持您创建 AWS 资源、提取其详细信息（如 ARN、URL、端点）并注入应用配置，且所有操作均作为单一单元进行管理。 有关更多组合编排模式及进阶示例，请参阅 [EKS 托管型 kro 注意事项](kro-considerations.md)。 ## 后续步骤 + [EKS 托管型 kro 注意事项](kro-considerations.md)：了解 EKS 专属模式、RBAC 以及与 ACK、Argo CD 的集成方法 + [kro 文档](https://kro.run/docs/overview)：包含进阶 CEL 表达式、验证模式及问题排查方案的完整 kro 文档 # 配置 kro 权限 与 ACK 和 Argo CD 不同，kro 无需额外的 IAM 权限。kro 完全在 Kubernetes 集群中运行，不会发起 AWS API 调用。可通过标准的 Kubernetes RBAC 机制管控对 kro 资源的访问权限。 ## kro 权限的工作原理 kro 涉及两种作用域不同的 Kubernetes 资源： **ResourceGraphDefinition**：属于集群级资源，用于定义自定义 API。这类资源通常由平台团队负责管理，平台团队会基于组织内的标准规范完成资源的设计与维护工作。 **实例**：属于命名空间级资源，基于 ResourceGraphDefinition 创建而来。拥有对应 RBAC 权限的应用团队，即可创建这类实例。 默认情况下，kro 功能会通过 `AmazonEKSKROPolicy` 访问条目策略，获得管理 ResourceGraphDefinition 及其实例的权限。但如果需要让 kro 创建和管理 ResourceGraphDefinition 中定义的底层 Kubernetes 资源（例如 Deployment、Service 或 ACK 资源），则需要为其配置额外权限。您可通过访问条目策略或 Kubernetes RBAC 两种方式授予这些权限。有关授予这些权限的详细信息，请参阅 [kro 自定义资源权限](capabilities-security.md#kro-resource-permissions)。 ## 平台团队权限 平台团队需要具备创建和管理 ResourceGraphDefinition 的权限。 **平台团队的 ClusterRole 示例**： ``` apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: kro-platform-admin rules: - apiGroups: ["kro.run"] resources: ["resourcegraphdefinitions"] verbs: ["*"] ``` **绑定到平台团队成员**： ``` apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: platform-team-kro-admin subjects: - kind: Group name: platform-team apiGroup: rbac.authorization.k8s.io roleRef: kind: ClusterRole name: kro-platform-admin apiGroup: rbac.authorization.k8s.io ``` ## 应用团队权限 应用团队需要具备在其所属命名空间内创建自定义资源实例的权限。 **应用团队的角色示例**： ``` apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: kro-app-developer namespace: my-app rules: - apiGroups: ["kro.run"] resources: ["webapps", "databases"] verbs: ["create", "get", "list", "update", "delete", "patch"] ``` **绑定到应用团队成员**： ``` apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: app-team-kro-developer namespace: my-app subjects: - kind: Group name: app-team apiGroup: rbac.authorization.k8s.io roleRef: kind: Role name: kro-app-developer apiGroup: rbac.authorization.k8s.io ``` **注意** Role 配置中的 API 组（本例中为 `kro.run`）必须与 ResourceGraphDefinition 模式文件里定义的 `apiVersion` 保持一致。 ## 只读访问权限 授予只读访问权限，允许相关人员查看 ResourceGraphDefinition 及实例，且不赋予修改权限。 **只读 ClusterRole**： ``` apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: kro-viewer rules: - apiGroups: ["kro.run"] resources: ["resourcegraphdefinitions"] verbs: ["get", "list", "watch"] ``` **实例的只读 Role**： ``` apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: kro-instance-viewer namespace: my-app rules: - apiGroups: ["kro.run"] resources: ["webapps", "databases"] verbs: ["get", "list", "watch"] ``` ## 多命名空间访问权限 借助 ClusterRole 搭配 RoleBinding，为应用团队授予多命名空间的访问权限。 **多命名空间访问的 ClusterRole**： ``` apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: kro-multi-namespace-developer rules: - apiGroups: ["kro.run"] resources: ["webapps"] verbs: ["create", "get", "list", "update", "delete"] ``` **绑定到指定命名空间**： ``` apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: app-team-dev-access namespace: development subjects: - kind: Group name: app-team apiGroup: rbac.authorization.k8s.io roleRef: kind: ClusterRole name: kro-multi-namespace-developer apiGroup: rbac.authorization.k8s.io --- apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: app-team-staging-access namespace: staging subjects: - kind: Group name: app-team apiGroup: rbac.authorization.k8s.io roleRef: kind: ClusterRole name: kro-multi-namespace-developer apiGroup: rbac.authorization.k8s.io ``` ## 最佳实践 **最低权限原则**：仅为每个团队授予完成其职责所需的最小权限。 **优先使用用户组而非独立用户**：将角色绑定到用户组而非单个用户，便于权限的统一管理。 **分离平台团队与应用团队的职责边界**：平台团队负责管理 ResourceGraphDefinition，应用团队负责管理实例。 **命名空间隔离机制**：利用命名空间实现不同团队或环境的隔离，并通过 RBAC 管控各命名空间的访问权限。 **审计场景的只读访问权限**：为安全与合规团队配置只读访问权限，满足审计工作的需求。 ## 后续步骤 + [kro 概念](kro-concepts.md)：了解 kro 的基本概念及资源组合编排 + [kro 概念](kro-concepts.md)：了解 SimpleSchema、CEL 表达式和组合编排模式 + [EKS 功能的安全注意事项](capabilities-security.md)：查看针对功能的安全最佳实践 # EKS 托管型 kro 注意事项 本主题旨在介绍使用 EKS 托管型 kro 的重要注意事项，包括资源组合编排的适用场景、RBAC 配置模式以及与其他 EKS 托管功能的集成方法。 ## kro 的适用场景 kro 旨在创建可复用的基础设施模式与自定义 API，以简化复杂的资源管理工作。 **需要使用 kro 的场景**： + 为应用团队构建带有简化 API 的自助式平台 + 在团队间统一基础设施模式（如数据库 \$1 备份 \$1 监控的组合） + 管理资源间的依赖关系，并实现资源间的值传递 + 构建自定义抽象资源，隐藏底层的实现复杂度 + 将多个 ACK 资源组合为更高级别的基础设施组件 + 为复杂的基础设施栈启用 GitOps 工作流程 **无需使用 kro 的场景**： + 管理简单的独立资源（直接使用 ACK 或 Kubernetes 原生资源） + 需要动态运行时逻辑（kro 为声明式框架，不支持命令式操作） + 资源之间不存在依赖关系或共享配置 kro 的优势在于构建标准化部署流程，即提供预设规则、可复用模式，帮助各团队轻松、合规地部署复杂的基础设施。 ## RBAC 模式 kro 可实现职责分离，将创建 ResourceGraphDefinition 的平台团队与创建实例的应用团队的工作边界清晰划分。 ### 平台团队职责 平台团队负责创建并维护用于定义自定义 API 的 ResourceGraphDefinition（RGD）。 **所需权限**： + 创建、更新、删除 ResourceGraphDefinition + 管理各类底层资源（Deployment、Service、ACK 资源） + 拥有 RGD 待使用的所有命名空间的访问权限 **平台团队的 ClusterRole 示例**： ``` apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: platform-kro-admin rules: - apiGroups: ["kro.run"] resources: ["resourcegraphdefinitions"] verbs: ["*"] - apiGroups: ["*"] resources: ["*"] verbs: ["get", "list", "watch"] ``` 有关 RBAC 配置的详细信息，请参阅[配置 kro 权限](kro-permissions.md)。 ### 应用团队职责 应用团队负责创建由 RGD 定义的自定义资源实例，无需理解底层实现的复杂逻辑。 **所需权限**： + 创建、更新、删除自定义资源实例 + 拥有其所在命名空间的读取权限 + 不授予底层资源或 RGD 的访问权限 **优点**： + 团队可直接使用简洁的高层级 API + 平台团队把控底层实现细节 + 降低配置错误的风险加快 + 新团队成员的上手速度 ## 与其他 EKS 功能集成 ### ACK 资源组合编排 kro 与 ACK 结合使用时，在创建基础设施模式方面的能力尤为突出。 **常见模式**： + **带存储功能的应用程序**：S3 存储桶 \$1 SQS 队列 \$1 通知配置 + **数据库资源栈**：RDS 实例 \$1 参数组 \$1 安全组 \$1 Secrets Manager 密钥 + **联网资源**：VPC \$1 子网 \$1 路由表 \$1 安全组 \$1 NAT 网关 + **带存储功能的计算资源**：EC2 实例 \$1 EBS 卷 \$1 IAM 实例配置文件 kro 会自动处理资源的依赖顺序、实现资源间的值传递（如 ARN、连接字符串），并将所有资源作为单一单元进行全生命周期管理。 有关 ACK 资源组合编排的示例，请参阅 [ACK 概念](ack-concepts.md)。 ### 将 Argo CD 与 GitOps 搭配使用 借助适用于 Argo CD 的 EKS 功能，可从 Git 存储库中部署 RGD 及实例。 **存储库组织方式**： + **平台存储库**：存放由平台团队管理的 ResourceGraphDefinition + **应用存储库**：存放由应用团队管理的自定义资源容器实例 + **共享存储库**：小型组织可将 RGD 与实例存放于同一存储库 **注意事项**： + 需先部署 RGD，再部署实例（可借助 Argo CD 的同步波功能实现） + 为平台团队与应用团队分别配置独立的 Argo CD 项目 + 由平台团队管控 RGD 存储库的访问权限 + 为应用团队分配 RGD 定义文件的只读访问权限 有关 Argo CD 的更多信息，请参阅[使用 Argo CD](working-with-argocd.md)。 ## ResourceGraphDefinition 的组织方式 可按照用途、复杂度和归属方对 RGD 进行分类管理。 **按用途分类**： + **基础设施**：数据库资源栈、联网资源、存储资源 + **应用程序**：Web 应用、API 服务、批处理任务 + **平台**：共享服务、监控组件、日志组件 **按复杂度分类**： + **简单**：包含 2-3 个资源，依赖关系极少 + **中等**：包含 5-10 个资源，存在部分依赖关系 + **复杂**：包含 10 个以上资源，依赖关系复杂 **命名规范**： + 采用描述性名称，例如：`webapp-with-database`、`s3-notification-queue` + 若存在破坏性变更，可在名称中加入版本号，例如：`webapp-v2` + 为同类型 RGD 添加统一前缀，例如：`platform- `、`app-` **命名空间策略**： + RGD 为集群级资源（非命名空间级资源） + 实例为命名空间级资源 + 可在 RGD 中配置命名空间选择器，管控实例允许被创建的命名空间范围 ## 版本控制与更新 需提前规划 RGD 的迭代优化与实例的迁移方案。 **RGD 更新**： + **非破坏性变更**：直接原地更新 RGD 即可（操作包括新增可选字段、添加带 includeWhen 条件的新资源） + **破坏性变更**：需创建名称不同的新 RGD（例如 webapp-v2） + **弃用策略**：通过注解标记旧版 RGD，并同步告知用户迁移时间规划 **实例迁移**： + 基于更新版 RGD 创建新的实例 + 验证新实例运行状态正常 + 删除旧版实例 + kro 会自动处理底层资源的更新操作 **最佳实践** + RGD 变更需先在非生产环境完成测试 + 有重大变更时，在 RGD 名称中采用语义版本控制命名规则 + 记录破坏性变更内容及对应的迁移方案 + 为应用团队提供可直接参考的迁移示例 ## 验证与测试 将 RGD 部署到生产环境前，需对其进行验证。 **验证策略**： + **模式验证**：kro 会自动对 RGD 模式进行验证 + **实例试运行**：在开发命名空间中创建测试用实例 + **集成测试**：验证组合后的各类资源是否能协同正常工作 + **策略强制执行**：通过准入控制器落实组织内部的标准规范 **需测试的常见问题**： + 资源依赖关系与创建顺序 + 资源间的值传递逻辑（CEL 表达式） + 条件式资源的包含规则（includeWhen） + 底层资源的状态反馈机制 + 实例创建操作对应的 RBAC 权限配置 ## 上游文档 有关使用 kro 的详细信息，请参阅以下内容： + [kro 入门](https://kro.run/docs/guides/getting-started)：创建 ResourceGraphDefinition + [CEL 表达式](https://kro.run/docs/concepts/cel)：编写 CEL 表达式 + [kro 指南](https://kro.run/docs/guides/)：高级组合编排模式 + [问题排查](https://kro.run/docs/troubleshooting)：问题排查与调试 ## 后续步骤 + [配置 kro 权限](kro-permissions.md)：为平台团队与应用团队配置 RBAC + [kro 概念](kro-concepts.md)：了解 kro 的基本概念及资源生命周期 + [排查 kro 功能问题](kro-troubleshooting.md)：诊断并解决 kro 相关问题 + [ACK 概念](ack-concepts.md)：了解用于资源组合编排的 ACK 资源 + [使用 Argo CD](working-with-argocd.md)：通过 GitOps 部署 RGD 及实例 # 排查 kro 功能问题 本主题旨在介绍 EKS 托管型 kro 问题排查指引，内容涵盖功能运行状况检查、RBAC 权限、CEL 表达式错误以及资源组合编排问题。 **注意** EKS 功能完全托管，可在您的集群之外运行。您无法访问控制器日志或 `kro-system` 命名空间。问题排查侧重于功能运行状况、RBAC 配置和资源状态。 ## 功能状态显示为 ACTIVE，但 ResourceGraphDefinition 无法正常工作 若 kro 功能状态显示为 `ACTIVE`，但 ResourceGraphDefinition 无法创建底层资源，请检查功能运行状况、RBAC 权限以及资源状态。 **检查功能运行状况**： 您可以在 EKS 控制台或使用 AWS CLI 查看功能运行状况和状态问题。 **控制台**： 1. 从以下位置打开 Amazon EKS 控制台：https://console.aws.amazon.com/eks/home\$1/clusters。 1. 选择集群名称。 1. 选择**可观测性**选项卡。 1. 选择**监控集群**。 1. 选择**功能**选项卡，查看所有功能的运行状况和状态。 **AWS CLI**： ``` # View capability status and health aws eks describe-capability \ --region region-code \ --cluster-name my-cluster \ --capability-name my-kro # Look for issues in the health section ``` **常见原因：** + **RBAC 权限缺失**：kro 缺少创建底层 Kubernetes 资源的权限 + **CEL 表达式无效**：ResourceGraphDefinition 中存在语法错误 + **资源依赖异常**：被依赖的资源未处于就绪状态 + **模式验证失败**：实例不符合 RGD 模式要求 **验证 RBAC 权限**： ``` # Check if capability has cluster admin policy kubectl get accessentry -A | grep kro ``` 若该功能不具备所需权限，可将 `AmazonEKSClusterAdminPolicy` 关联到 kro 功能的访问条目；对于生产环境，也可创建权限范围更严格的 RBAC 策略。有关详细信息，请参阅 [配置 kro 权限](kro-permissions.md)。 **检查 ResourceGraphDefinition 状态**： ``` # List all RGDs kubectl get resourcegraphdefinition # Describe specific RGD kubectl describe resourcegraphdefinition my-rgd # Check for validation errors kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.status.conditions}' ``` ResourceGraphDefinition 包含三项关键状态条件： + `ResourceGraphAccepted`：RGD 是否通过验证（CEL 语法、类型校验、字段存在性验证） + `KindReady`：自定义 API 对应的 CRD 是否已生成并完成注册 + `ControllerReady`：kro 是否正在主动监听自定义 API 的实例 若 `ResourceGraphAccepted` 状态为 `False`，请查看状态条件信息，排查是否存在未知字段、类型不匹配或循环依赖等验证类错误。 ## 已创建实例但未生成底层资源 若自定义资源实例已存在，但对应的底层 Kubernetes 资源（如 Deployment、Service、ConfigMap）未被创建，请验证 kro 是否具备相应权限，同时排查资源组合编排错误。 **检查实例状态**： ``` # Describe the instance (replace with your custom resource kind and name) kubectl describe custom-kind my-instance # View instance events kubectl get events --field-selector involvedObject.name=my-instance # Check instance status conditions kubectl get custom-kind my-instance -o jsonpath='{.status.conditions}' # Check instance state kubectl get custom-kind my-instance -o jsonpath='{.status.state}' ``` 实例包含一个 `state` 字段，用于展示其宏观状态： + `ACTIVE`：实例已成功运行 + `IN_PROGRESS`：实例正被处理或协调 + `FAILED`：实例协调失败 + `DELETING`：实例正被删除 + `ERROR`：处理过程中发生错误 实例同时包含四项状态条件： + `InstanceManaged`：终结器与标签已正确配置 + `GraphResolved`：运行时依赖图已创建，且相关资源已完成解析 + `ResourcesReady`：所有资源均已创建并处于就绪状态 + `Ready`：实例的整体运行状况（仅当所有子条件均为 `True` 时，该状态才会变为 `True`） 可重点关注 `Ready` 条件来判断实例的运行状况。若 `Ready` 状态为 `False`，请检查各子条件，明确是哪个阶段执行失败。 **验证 RBAC 权限**： kro 功能需要具备创建 ResourceGraphDefinition 中所定义的底层 Kubernetes 资源的权限。 ``` # Check if the capability has the AmazonEKSClusterAdminPolicy kubectl get accessentry -A | grep kro ``` 若存在权限缺失，可将 `AmazonEKSClusterAdminPolicy` 关联到 kro 功能的访问条目；对于生产环境，则建议创建权限范围更严格的 RBAC 策略。有关详细信息，请参阅 [配置 kro 权限](kro-permissions.md)。 ## CEL 表达式错误 CEL 表达式错误会在 ResourceGraphDefinition 创建阶段被捕获，而非在实例创建阶段。当您创建 RGD 时，kro 会对所有 CEL 语法进行验证、基于 Kubernetes 模式对表达式进行类型检查，同时验证字段是否存在。 **常见 CEL 验证错误**： + **未定义字段引用**：引用了模式或资源中不存在的字段 + **类型不匹配**：表达式返回的类型不符合预期（例如：预期为整数类型，实际返回字符串类型） + **语法无效**：CEL 表达式中存在缺失括号、引号或运算符的情况 + **未知资源类型**：引用了集群中未存在的 CRD **检查 RGD 验证状态**： ``` # Check if RGD was accepted kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.status.conditions[?(@.type=="ResourceGraphAccepted")]}' # View detailed validation errors kubectl describe resourcegraphdefinition my-rgd ``` 若 `ResourceGraphAccepted` 状态为 `False`，对应的条件信息中会包含具体的验证错误信息。 **有效的 CEL 表达式示例**： ``` # Reference schema field ${schema.spec.appName} # Conditional expression ${schema.spec.replicas > 1} # String template (expressions must return strings) name: "${schema.spec.appName}-service" # Standalone expression (can be any type) replicas: ${schema.spec.replicaCount} # Resource reference ${deployment.status.availableReplicas} # Optional field access (returns null if field doesn't exist) ${configmap.data.?DATABASE_URL} ``` ## 资源依赖关系无法解析 kro 会从 CEL 表达式中自动推导资源依赖关系，并按正确顺序创建资源。若资源未按预期生成，请检查依赖顺序以及资源的就绪状态。 **查看计算出的创建顺序**： ``` # See the order kro will create resources kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.status.topologicalOrder}' ``` 该操作会展示基于资源间 CEL 表达式引用关系计算得出的资源创建顺序。 **检查资源就绪状态**： ``` # View instance status to see which resources are ready kubectl get custom-kind my-instance -o jsonpath='{.status}' # Check specific resource status kubectl get deployment my-deployment -o jsonpath='{.status.conditions}' ``` **验证 readyWhen 条件（若已配置）**： `readyWhen` 字段为可选项。若未指定该字段，资源在创建完成后会被立即判定为就绪状态。若已定义 `readyWhen` 条件，请验证该条件是否能正确校验资源的就绪状态： ``` resources: - id: deployment readyWhen: - ${deployment.status.availableReplicas == deployment.spec.replicas} ``` **检查资源事件**： ``` # View events for the underlying resources kubectl get events -n namespace --sort-by='.lastTimestamp' ``` ## 模式验证失败 若实例因模式验证错误而无法创建，请确认该实例是否符合 RGD 模式要求。 **检查验证错误**： ``` # Attempt to create instance and view error kubectl apply -f instance.yaml # View existing instance validation status kubectl describe custom-kind my-instance | grep -A 5 "Validation" ``` **常见验证问题**： + **必填字段缺失**：实例未提供模式要求的全部必填字段 + **类型不匹配**：在需要整数类型的位置传入了字符串类型 + **枚举值无效**：使用了不在允许取值列表内的数值 + **格式不匹配**：字符串未匹配正则表达式格式 **查看 RGD 模式**： ``` # View the schema definition kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.spec.schema}' ``` 确保实例提供所有必填字段且类型正确。 ## 后续步骤 + [EKS 托管型 kro 注意事项](kro-considerations.md)：kro 注意事项和最佳实践 + [配置 kro 权限](kro-permissions.md)：为平台团队与应用团队配置 RBAC + [kro 概念](kro-concepts.md)：了解 kro 的基本概念及资源生命周期 + [EKS 功能问题排查](capabilities-troubleshooting.md)：一般功能问题排查指导 # EKS 托管型 kro 与自主管理型 kro 的对比 EKS 托管型 kro 具备与自主管理型 kro 完全相同的功能，同时还拥有显著的运维优势。有关 EKS 功能与自主管理型解决方案的总体比较，请参阅 [EKS 功能和注意事项](capabilities-considerations.md)。 EKS 托管型 kro 基于上游 kro 控制器构建，且与上游 kro 完全兼容。ResourceGraphDefinition、CEL 表达式以及资源组合编排的工作方式均保持一致。如需查看 kro 的完整文档与示例，请参阅 [kro 文档](https://kro.run/docs/overview)。 ## 迁移路径 您可以从自主管理型 kro 无缝迁移到托管型 kro，实现零停机时间。 **重要** 迁移前，请确保自主管理型 kro 控制器与 EKS 托管型 kro 运行的是同一版本。通过 EKS 控制台或 `aws eks describe-capability` 查看托管型 kro 的版本，随后将自主管理型 kro 安装版本升级到与之匹配。此举可避免迁移过程中出现兼容性问题。 1. 更新自主管理型 kro 控制器，将其主节点选举租约配置在 `kube-system` 命名空间中： ``` helm upgrade --install kro \ oci://ghcr.io/awslabs/kro/kro-chart \ --namespace kro \ --set leaderElection.namespace=kube-system ``` 这会将控制器的租约移至 `kube-system`，从而允许托管功能与其协调。 1. 在集群中创建 kro 托管功能（详见[创建 kro 功能](create-kro-capability.md)文档） 1. 托管功能会自动识别现有的 ResourceGraphDefinition 及其实例，并接管资源调和工作 1. 逐步缩减或移除自主管理型 kro 的部署资源： ``` helm uninstall kro --namespace kro ``` 此方法允许两个控制器在迁移期间安全共存。托管功能会自动接管此前由自主管理型 kro 管理的 ResourceGraphDefinition 及其实例，保障资源调和流程持续进行且无冲突。 ## 后续步骤 + [创建 kro 功能](create-kro-capability.md)：创建 kro 托管功能资源 + [kro 概念](kro-concepts.md)：了解 kro 的基本概念及资源组合编排