x-dynamodb

Syntax reference
x-dynamodb:
  table-A:
    Properties: {}
    MacroParameters: {}
    Services: {}
    Scaling: {}

Create / use existing DynamoDB tables and link them logically to the services (and other AWS resources, where applicable).

Services

Example with 2 services
x-dynamodb:
  table01:
    Properties: {}
    Services:
      app01:
        Access: RW
      app02:
        Access: RO
        ReturnValues: {}

ReturnValues

Refer to AWS CFN DynamoDB Return Values for these settings.

Warning

If you try to retrieve StreamArn but did not set the properties for it, it will fail.

To get the table name, use TableName to get the value returned by Ref function.

Access

ECS Compose-X defined access names:

  • RW : Allow read/write/delete on the table items

  • RO: Allow read only actions on the table items

Properties

Refer to AWS CFN Dynamodb Documentation . We support all of the definition and test with the documentation examples.

Tables with GSI and autoscaling
version: '3.8'
x-dynamodb:
  tableA:
    Scaling:
      Table: &scaling_definition
        ReadCapacityUnits:
          MaxCapacity: 100
          MinCapacity: 10
          TargetValue: 70.0
          ScaleOutCooldown: 60
        WriteCapacityUnits:
          MaxCapacity: 70
          MinCapacity: 10
          TargetValue: 70.0
          ScaleInCooldown: 120
      Indexes:
        myGSI:
          <<: *scaling_definition
      CopyToIndexes: true

    Properties:
      AttributeDefinitions:
        - AttributeName: Album
          AttributeType: S
        - AttributeName: Artist
          AttributeType: S
        - AttributeName: Sales
          AttributeType: N
        - AttributeName: NumberOfSongs
          AttributeType: N
      GlobalSecondaryIndexes:
        - IndexName: myGSI
          KeySchema:
            - AttributeName: Sales
              KeyType: HASH
            - AttributeName: Artist
              KeyType: RANGE
          Projection:
            NonKeyAttributes:
              - Album
              - NumberOfSongs
            ProjectionType: INCLUDE
          ProvisionedThroughput:
            ReadCapacityUnits: '5'
            WriteCapacityUnits: '5'
        - IndexName: myGSI2
          KeySchema:
            - AttributeName: NumberOfSongs
              KeyType: HASH
            - AttributeName: Sales
              KeyType: RANGE
          Projection:
            NonKeyAttributes:
              - Album
              - Artist
            ProjectionType: INCLUDE
          ProvisionedThroughput:
            ReadCapacityUnits: '5'
            WriteCapacityUnits: '5'
      KeySchema:
        - AttributeName: Album
          KeyType: HASH
        - AttributeName: Artist
          KeyType: RANGE
      LocalSecondaryIndexes:
        - IndexName: myLSI
          KeySchema:
            - AttributeName: Album
              KeyType: HASH
            - AttributeName: Sales
              KeyType: RANGE
          Projection:
            NonKeyAttributes:
              - Artist
              - NumberOfSongs
            ProjectionType: INCLUDE
      ProvisionedThroughput:
        ReadCapacityUnits: '5'
        WriteCapacityUnits: '5'
    Services:
      app02:
        Access: RW
        ReturnValues:
          Arn: TABLE_A_ARN
      app03:
        access: RW
      bignicefamily:
        ReturnValues:
          Arn: TABLE_A_arn

  tableB:
    Scaling:
      Table:
        <<: *scaling_definition
      CopyToIndexes: true
    Properties:
      AttributeDefinitions:
        - AttributeName: ArtistId
          AttributeType: S
        - AttributeName: Concert
          AttributeType: S
        - AttributeName: TicketSales
          AttributeType: S
      GlobalSecondaryIndexes:
        - IndexName: GSI
          KeySchema:
            - AttributeName: TicketSales
              KeyType: HASH
          Projection:
            ProjectionType: KEYS_ONLY
          ProvisionedThroughput:
            ReadCapacityUnits: 5
            WriteCapacityUnits: 5
      KeySchema:
        - AttributeName: ArtistId
          KeyType: HASH
        - AttributeName: Concert
          KeyType: RANGE
      ProvisionedThroughput:
        ReadCapacityUnits: 5
        WriteCapacityUnits: 5
    Services:
      app03:
        Access: RW
      bignicefamily:
        Access: RO

Attention

You may set the TableName property yourselves, or let AWS CloudFormation set one for you. If you set it yourselves, as per the documentation, that table will be replaced with a new table using the new name. Set it at your own risks

Lookup

For more details, see the Lookup .

Lookup DynamoDB Table example
x-dynamodb:
  table-A:
    Lookup:
      Tags:
        - table-name: table123
        - owner: myself
        - costallocation: 123
    Services:
      serviceA:
        Access: DynamoDBCrudPolicy

Scaling

Note

This is only available to new DynamoDB tables.


x-dynamodb:
TableA:

Properties: {} Scaling:

Table: AutoscalingUnit Indexes:

<index_name>: AutoscalingUnit

CopyToIndexes: bool

AutoscalingUnit

Allows to define the scaling properties for either ReadCapacityUnits or WriteCapacityUnits

AutoscalingUnit
ReadCapacityUnits: ScalingDefinition
WriteCapacityUnits: ScalingDefinition

ScalingDefinition

ScalingDefinition
MaxCapacity: number
MinCapacity: numer
TargetValue: number
ScaleInCooldown: number
ScaleOutCooldown: number

CopyToIndexes

If you want to define autoscaling on the indexes with the same properties as for the Table, setting CopyToIndexes to true will automatically go through the GSIs of the table and set the same scaling policy as the one defined for the table.

Indexes


x-dynamodb:
TableA:

Properties: {} Scaling:

Table: AutoscalingUnit Indexes:

myGSI: AutoscalingUnit

Allows you define the same parameters as for the table, but on the indexes. If you set both CopyToIndexes and an index in this section, the Index level settings take precedence.

Tip

If you define scaling on an index that is not in the Properties, it will automatically flag it and fail.

JSON Schema

Model

x-dynamodb

x-dynamodb.spec.json

x-dynamodb specification

type

object

properties

  • Lookup

x-resources.common.spec.json#/definitions/Lookup

  • Properties

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-dynamodb-table.html

type

object

  • Settings

x-resources.common.spec.json#/definitions/Settings

  • Services

x-resources.common.spec.json#/definitions/Services

  • MacroParameters

type

object

  • Scaling

Defines autoscaling settings for the table and indexes.

type

object

properties

  • Table

#/definitions/AutoscalingUnit

  • CopyToIndexes

Whether or not apply the same scaling configuration to all indexes than Table. Does not override settings set in Indexes

type

boolean

default

False

  • Indexes

The indexes to apply autoscaling too.

type

object

patternProperties

  • [a-zA-Z0-9-_.]{3,255}

#/definitions/AutoscalingUnit

additionalProperties

False

additionalProperties

False

definitions

  • CapacityUnits

type

object

properties

  • MinCapacity

type

number

minimum

5.0

  • MaxCapacity

type

number

minimum

5.0

  • TargetValue

type

number

maximum

100.0

minimum

1.0

  • ScaleInCooldown

type

number

minimum

1

default

60

  • ScaleOutCooldown

type

number

minimum

1

default

60

  • AutoscalingUnit

type

object

properties

  • WriteCapacityUnits

#/definitions/CapacityUnits

  • ReadCapacityUnits

#/definitions/CapacityUnits

additionalProperties

False

Definition

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "id": "x-dynamodb.spec.json",
  "$id": "x-dynamodb.spec.json",
  "title": "x-dynamodb",
  "description": "x-dynamodb specification",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "Lookup": {
      "$ref": "x-resources.common.spec.json#/definitions/Lookup"
    },
    "Properties": {
      "type": "object",
      "description": "https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-dynamodb-table.html"
    },
    "Settings": {
      "$ref": "x-resources.common.spec.json#/definitions/Settings"
    },
    "Services": {
      "$ref": "x-resources.common.spec.json#/definitions/Services"
    },
    "MacroParameters": {
      "type": "object"
    },
    "Scaling": {
      "type": "object",
      "description": "Defines autoscaling settings for the table and indexes.",
      "additionalProperties": false,
      "required": [
        "Table"
      ],
      "properties": {
        "Table": {
          "$ref": "#/definitions/AutoscalingUnit"
        },
        "CopyToIndexes": {
          "type": "boolean",
          "default": false,
          "description": "Whether or not apply the same scaling configuration to all indexes than Table. Does not override settings set in Indexes"
        },
        "Indexes": {
          "type": "object",
          "description": "The indexes to apply autoscaling too.",
          "patternProperties": {
            "[a-zA-Z0-9-_.]{3,255}": {
              "$ref": "#/definitions/AutoscalingUnit"
            }
          }
        }
      }
    }
  },
  "oneOf": [
    {
      "required": [
        "Lookup"
      ]
    },
    {
      "required": [
        "Properties"
      ]
    }
  ],
  "definitions": {
    "CapacityUnits": {
      "type": "object",
      "required": [
        "MinCapacity",
        "MaxCapacity",
        "TargetValue"
      ],
      "properties": {
        "MinCapacity": {
          "type": "number",
          "minimum": 5.0
        },
        "MaxCapacity": {
          "type": "number",
          "minimum": 5.0
        },
        "TargetValue": {
          "type": "number",
          "minimum": 1.0,
          "maximum": 100.0
        },
        "ScaleInCooldown": {
          "type": "number",
          "minimum": 1,
          "default": 60
        },
        "ScaleOutCooldown": {
          "type": "number",
          "minimum": 1,
          "default": 60
        }
      }
    },
    "AutoscalingUnit": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "WriteCapacityUnits": {
          "$ref": "#/definitions/CapacityUnits"
        },
        "ReadCapacityUnits": {
          "$ref": "#/definitions/CapacityUnits"
        }
      }
    }
  }
}

Test files

You can find the test files here to use as reference for your use-case.