メインコンテンツまでスキップ

コンポジションの作成

CompositeResourceDefinition（XRD）は、コンポジットリソース（XR）のタイプとスキーマを定義します。これはCrossplaneに対して、望ましいXRとそのフィールドについて通知します。XRDはCustomResourceDefinition（CRD）に似ていますが、より規範的な構造を持っています。XRDを作成する主なステップは、OpenAPI "構造的スキーマ"を指定することです。

まず、アプリケーションチームのメンバーが各自の名前空間でDynamoDBテーブルを作成できるようにする定義を提供しましょう。この例では、ユーザーは名前、キー属性、およびインデックス名フィールドのみを指定する必要があります。

XRDマニフェスト全体を表示
~/environment/eks-workshop/modules/automation/controlplanes/crossplane/compositions/composition/definition.yaml
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xdynamodbtables.awsblueprints.io
spec:
  group: awsblueprints.io
  names:
    kind: XDynamoDBTable
    plural: xdynamodbtables
  claimNames:
    kind: DynamoDBTable
    plural: dynamodbtables
  connectionSecretKeys:
    - tableName
  versions:
    - name: v1alpha1
      served: true
      referenceable: true
      schema:
        openAPIV3Schema:
          type: object
          description: Table is the Schema for the tables API
          properties:
            spec:
              type: object
              properties:
                resourceConfig:
                  properties:
                    deletionPolicy:
                      description: Defaults to Delete
                      enum:
                        - Delete
                        - Orphan
                      type: string
                    name:
                      type: string
                    providerConfigName:
                      type: string
                      default: aws-provider-config
                    region:
                      type: string
                      default: ""
                    tags:
                      additionalProperties:
                        type: string
                      description: Key-value map of resource tags.
                      type: object
                  required:
                    - region
                  type: object
                dynamoConfig:
                  properties:
                    attribute: #required for hashKey and/or rangeKey
                      items:
                        properties:
                          name: #name of the hashKey and/or rangeKey
                            type: string
                          type:
                            enum:
                              - B #binary
                              - N #number
                              - S #string
                            type: string
                        required:
                          - name
                          - type
                        type: object
                      type: array
                    hashKey:
                      type: string
                    rangeKey:
                      type: string
                    billingMode:
                      type: string
                      default: PAY_PER_REQUEST
                    readCapacity:
                      type: number
                    writeCapacity:
                      type: number
                    globalSecondaryIndex:
                      items:
                        properties:
                          hashKey:
                            type: string
                          name:
                            type: string
                          rangeKey:
                            type: string
                          readCapacity:
                            type: number
                          writeCapacity:
                            type: number
                          projectionType:
                            type: string
                            default: ALL
                          nonKeyAttributes: #required for gsi
                            items:
                              type: string
                            type: array
                        type: object
                        required:
                          - name
                      type: array
                    localSecondaryIndex:
                      items:
                        properties:
                          name:
                            type: string
                          rangeKey:
                            type: string
                          projectionType:
                            type: string
                          nonKeyAttributes: #required for lsi
                            items:
                              type: string
                            type: array
                        type: object
                        required:
                          - name
                          - rangeKey
                          - projectionType
                          - nonKeyAttributes
                      type: array
                  required:
                    - attribute
                  type: object
              required:
                - dynamoConfig
            status:
              type: object
              description: TableStatus defines the observed state of Table
              properties:
                tableArn:
                  description: Indicates this table's ARN
                  type: string
                tableName:
                  description: Indicates this table's Name
                  type: string
          required:
            - spec

XRDマニフェストからDynamoDB固有の設定を確認してみましょう。

DynamoDBテーブル名の指定が必要なセクションは以下の通りです：

                resourceConfig:
                  properties:
                    deletionPolicy:
                      description: Defaults to Delete
                      enum:
                        - Delete
                        - Orphan
                      type: string
                    name:
                      type: string

このセクションはDynamoDBテーブルのキー属性の仕様を提供します：

                dynamoConfig:
                  properties:
                    attribute: #required for hashKey and/or rangeKey
                      items:
                        properties:
                          name: #name of the hashKey and/or rangeKey
                            type: string
                          type:
                            enum:
                              - B #binary
                              - N #number
                              - S #string
                            type: string
                        required:
                          - name
                          - type
                        type: object
                      type: array
                    hashKey:
                      type: string
                    rangeKey:
                      type: string

これはグローバルセカンダリインデックスの仕様に関するセクションです：

                    globalSecondaryIndex:
                      items:
                        properties:
                          hashKey:
                            type: string
                          name:
                            type: string
                          rangeKey:
                            type: string
                          readCapacity:
                            type: number
                          writeCapacity:
                            type: number
                          projectionType:
                            type: string
                            default: ALL
                          nonKeyAttributes: #required for gsi
                            items:
                              type: string
                            type: array
                        type: object
                        required:
                          - name
                      type: array

これはローカルセカンダリインデックスの仕様に関するセクションです：

                    localSecondaryIndex:
                      items:
                        properties:
                          name:
                            type: string
                          rangeKey:
                            type: string
                          projectionType:
                            type: string
                          nonKeyAttributes: #required for lsi
                            items:
                              type: string
                            type: array
                        type: object
                        required:
                          - name
                          - rangeKey
                          - projectionType
                          - nonKeyAttributes
                      type: array

コンポジションは、コンポジットリソースが作成されたときにCrossplaneが取るべきアクションについて通知します。各コンポジションは、XRと1つ以上のマネージドリソースのセットの間にリンクを確立します。XRが作成、更新、または削除されると、関連するマネージドリソースも対応して作成、更新、または削除されます。

マネージドリソースTableをプロビジョニングするコンポジションを表示：
~/environment/eks-workshop/modules/automation/controlplanes/crossplane/compositions/composition/table.yaml
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: table.dynamodb.awsblueprints.io
  labels:
    awsblueprints.io/provider: aws
    awsblueprints.io/environment: dev
spec:
  writeConnectionSecretsToNamespace: crossplane-system
  compositeTypeRef:
    apiVersion: awsblueprints.io/v1alpha1
    kind: XDynamoDBTable
  patchSets:
    - name: common-fields
      patches:
        - type: FromCompositeFieldPath
          fromFieldPath: spec.resourceConfig.providerConfigName
          toFieldPath: spec.providerConfigRef.name
        - type: FromCompositeFieldPath
          fromFieldPath: spec.name
          toFieldPath: metadata.annotations[crossplane.io/external-name]
        - type: FromCompositeFieldPath
          fromFieldPath: metadata.name
          toFieldPath: metadata.annotations[crossplane.io/external-name]
          transforms:
            - type: string
              string:
                type: Regexp
                regexp:
                  match: ^(.*?)-crossplane
  resources:
    - name: table
      connectionDetails:
        - type: FromFieldPath
          name: tableName
          fromFieldPath: status.atProvider.id
      base:
        apiVersion: dynamodb.aws.upbound.io/v1beta1
        kind: Table
        spec:
          forProvider:
            writeConnectionSecretToRef:
              name: cartsdynamo
              namespace: crossplane-system
            region: ""
          providerConfigRef:
            name: aws-provider-config
      patches:
        - type: PatchSet
          patchSetName: common-fields
        - type: FromCompositeFieldPath
          fromFieldPath: spec.dynamoConfig.attribute
          toFieldPath: spec.forProvider.attribute
          policy:
            mergeOptions:
              appendSlice: true
              keepMapValues: true
        - type: FromCompositeFieldPath
          fromFieldPath: spec.resourceConfig.tags
          toFieldPath: spec.forProvider.tags
          policy:
            mergeOptions:
              keepMapValues: true
        - type: FromCompositeFieldPath
          fromFieldPath: spec.dynamoConfig.attribute[0].name
          toFieldPath: spec.forProvider.hashKey
        - type: FromCompositeFieldPath
          fromFieldPath: spec.dynamoConfig.billingMode
          toFieldPath: spec.forProvider.billingMode
        - type: FromCompositeFieldPath
          fromFieldPath: spec.dynamoConfig.rangeKey
          toFieldPath: spec.forProvider.rangeKey
        - type: FromCompositeFieldPath
          fromFieldPath: spec.dynamoConfig.readCapacity
          toFieldPath: spec.forProvider.readCapacity
        - type: FromCompositeFieldPath
          fromFieldPath: spec.dynamoConfig.writeCapacity
          toFieldPath: spec.forProvider.writeCapacity
        - type: FromCompositeFieldPath
          fromFieldPath: spec.dynamoConfig.globalSecondaryIndex[0].name
          toFieldPath: spec.forProvider.globalSecondaryIndex[0].name
        - type: FromCompositeFieldPath
          fromFieldPath: spec.dynamoConfig.attribute[1].name
          toFieldPath: spec.forProvider.globalSecondaryIndex[0].hashKey
        - type: FromCompositeFieldPath
          fromFieldPath: spec.dynamoConfig.globalSecondaryIndex[0].projectionType
          toFieldPath: spec.forProvider.globalSecondaryIndex[0].projectionType
          policy:
            mergeOptions:
              keepMapValues: true
        - type: FromCompositeFieldPath
          fromFieldPath: spec.dynamoConfig.localSecondaryIndex
          toFieldPath: spec.forProvider.localSecondaryIndex
          policy:
            mergeOptions:
              keepMapValues: true
        - type: ToCompositeFieldPath
          fromFieldPath: status.atProvider.id
          toFieldPath: status.tableName
        - type: ToCompositeFieldPath
          fromFieldPath: status.atProvider.arn
          toFieldPath: status.tableArn

これをいくつかのパートに分けて確認すると理解しやすくなります。

このセクションは、XRのspec.nameフィールドをマネージドリソースのexternal-nameアノテーションにマッピングします。Crossplaneはこれを使用してAWSでの実際のDynamoDBテーブル名を設定します。

        - type: FromCompositeFieldPath
          fromFieldPath: spec.name
          toFieldPath: metadata.annotations[crossplane.io/external-name]

これはXRからすべての属性定義をマネージドDynamoDBリソースに転送し、Crossplaneが適切なデータ型でテーブルスキーマを作成できるようにします。

        - type: FromCompositeFieldPath
          fromFieldPath: spec.dynamoConfig.attribute
          toFieldPath: spec.forProvider.attribute
          policy:
            mergeOptions:
              appendSlice: true
              keepMapValues: true

これはXRからの最初の属性をDynamoDBテーブルのプライマリキー構造のパーティションキー（ハッシュキー）としてマッピングします。

        - type: FromCompositeFieldPath
          fromFieldPath: spec.dynamoConfig.attribute[0].name
          toFieldPath: spec.forProvider.hashKey

これはXR仕様からGSI名をマネージドリソースに転送し、CrossplaneがDynamoDBテーブルに名前付きのグローバルセカンダリインデックスを作成できるようにします。

        - type: FromCompositeFieldPath
          fromFieldPath: spec.dynamoConfig.globalSecondaryIndex[0].name
          toFieldPath: spec.forProvider.globalSecondaryIndex[0].name

これはXRからLSI設定をマネージドリソースにマッピングし、Crossplaneが指定された名前と属性でローカルセカンダリインデックスをプロビジョニングできるようにします。

        - type: FromCompositeFieldPath
          fromFieldPath: spec.dynamoConfig.localSecondaryIndex
          toFieldPath: spec.forProvider.localSecondaryIndex

この設定をEKSクラスターに適用してみましょう：

~$kubectl apply -k ~/environment/eks-workshop/modules/automation/controlplanes/crossplane/compositions/composition
compositeresourcedefinition.apiextensions.crossplane.io/xdynamodbtables.awsblueprints.io created
composition.apiextensions.crossplane.io/table.dynamodb.awsblueprints.io created


これらのリソースを配置することで、DynamoDBテーブルを作成するためのCrossplaneコンポジションの設定が完了しました。この抽象化により、アプリケーション開発者は、基盤となるAWS固有の詳細を理解することなく、標準化されたDynamoDBテーブルをプロビジョニングできるようになりました。