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.