**このページの改善にご協力ください** このユーザーガイドに貢献するには、すべてのページの右側のペインにある「**GitHub でこのページを編集する**」リンクを選択してください。 # kro の概念 kro を使用すると、プラットフォームチームは、複数のリソースを高レベルの抽象化に構成するカスタム Kubernetes API を作成できます。このトピックでは、実用的な例を取り上げ、EKS Capability for kro を使用する際に理解しておく必要がある重要な概念について説明します。 ## kro の開始方法 kro 機能を作成した後 (「[kro 機能の作成](create-kro-capability.md)」を参照)、クラスターで ResourceGraphDefinitions を使用して、カスタム API の作成を開始できます。 シンプルなウェブアプリケーションの抽象化を作成する完全な例を次に示します。 ``` 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 を使用してウェブアプリケーションを作成できます。 ``` apiVersion: kro.run/v1alpha1 kind: WebApplication metadata: name: my-app spec: name: my-app replicas: 5 ``` kro は、適切な設定でデプロイとサービスを自動的に作成します。`image` が指定されていないため、スキーマのデフォルト値である `nginx:latest` が使用されます。 ## 重要な概念 **重要** kro は、ランタイムではなく作成時に ResourceGraphDefinitions を検証します。RGD を作成すると、kro は CEL 構文を検証し、式を実際の Kubernetes スキーマと照合して型チェックし、フィールドの存在を検証し、循環依存関係を検出します。つまり、RGD を作成すると、インスタンスがデプロイされる前にエラーがすぐに検出されます。 ### ResourceGraphDefinition ResourceGraphDefinition (RGD) は、以下を指定することでカスタム Kubernetes API を定義します。 + **スキーマ** - SimpleSchema 形式 (フィールド名、型、デフォルト、検証) を使用した API 構造 + **リソース** - 作成する基盤となる Kubernetes または AWS リソースのテンプレート + **依存関係** - リソースの相互関係 (フィールド参照から自動的に検出) RGD を適用すると、kro はクラスターに新しいカスタムリソース定義 (CRD) を登録します。その後、アプリケーションチームはカスタム API のインスタンスを作成でき、kro は基盤となるすべてのリソースの作成と管理を処理します。 詳細については、kro ドキュメントの「[ResourceGraphDefinition Overview](https://kro.run/docs/concepts/rgd/overview/)」を参照してください。 ### SimpleSchema 形式 SimpleSchema は、OpenAPI の知識を必要とせずに API スキーマを定義する簡単な方法を提供します。 ``` 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 は、`required`、`default`、`minimum`/`maximum`、`enum`、`pattern` などの制約がある、`string`、`integer`、`boolean`、`number` 型をサポートしています。 詳細については、kro ドキュメントの「[SimpleSchema](https://kro.run/docs/concepts/rgd/schema/)」を参照してください。 ### CEL 式 kro は、値を動的に参照し、条件付きロジックを追加するために、Common Expression Language (CEL) を使用します。CEL 式は `${` と `}` で囲まれ、次の 2 つの方法で使用できます。 **スタンドアロン式** - フィールド値全体が 1 つの式です。 ``` spec: replicas: ${schema.spec.replicaCount} # Expression returns integer labels: ${schema.spec.labelMap} # Expression returns object ``` 式の結果はフィールド値全体を置き換え、フィールドで想定されている型と一致する必要があります。 **文字列テンプレート** - 文字列に埋め込まれた 1 つ以上の式: ``` 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 は検証時に循環依存関係を含む ResourceGraphDefinitions を拒否します。 計算された作成順序を表示できます。 ``` kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.status.topologicalOrder}' ``` 詳細については、kro ドキュメントの「[Graph inference](https://kro.run/docs/concepts/rgd/dependencies-ordering/)」を参照してください。 ## ACK を使用した構成 kro は、EKS Capability for 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、エンドポイント) を抽出してアプリケーション設定に挿入できます。これらはすべて、1 つのユニットとして管理されます。 その他の構成パターンと詳細な例については、「[EKS を利用する場合の kro の考慮事項](kro-considerations.md)」を参照してください。 ## 次のステップ + [EKS を利用する場合の kro の考慮事項](kro-considerations.md) - EKS 固有のパターン、RBAC、および ACK と Argo CD との統合について説明します。 + [kro ドキュメント](https://kro.run/docs/overview) - 高度な CEL 式、検証パターン、トラブルシューティングを含む、kro の包括的なドキュメントです。