このページの改善にご協力ください

このユーザーガイドに貢献するには、すべてのページの右側のペインにある「GitHub でこのページを編集する」リンクを選択してください。

kro の概念

kro を使用すると、プラットフォームチームは、複数のリソースを高レベルの抽象化に構成するカスタム Kubernetes API を作成できます。このトピックでは、実用的な例を取り上げ、EKS Capability for kro を使用する際に理解しておく必要がある重要な概念について説明します。

kro の開始方法

kro 機能を作成した後 (「kro 機能の作成」を参照)、クラスターで 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 が使用されます。

重要な概念

ResourceGraphDefinition

ResourceGraphDefinition (RGD) は、以下を指定することでカスタム Kubernetes API を定義します。

RGD を適用すると、kro はクラスターに新しいカスタムリソース定義 (CRD) を登録します。その後、アプリケーションチームはカスタム API のインスタンスを作成でき、kro は基盤となるすべてのリソースの作成と管理を処理します。

詳細については、kro ドキュメントの「ResourceGraphDefinition 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」を参照してください。

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」を参照してください。

リソースの依存関係

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」を参照してください。

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 の考慮事項」を参照してください。

次のステップ