Attention

For production workloads, we recommend sing Lookup you can use existing DocDB clusters with your new services. This will avoid accidental deletions or rollback situations where both your DB and services have to rollback.

x-docdb

x-docdb:
  cluster:
    Properties: {}
    MacroParameters: {}
    Settings: {}
    Services: {}

Create / lookup DocumentDB clusters you want to connect your ECS Services to.

See also

See Change AWS RDS / DocumentDB secret environment variables for a step by step example to change the SecretsMapping.

Services

Refer to Services for in-depth details.

ReturnValues

The available return Values are as per the CFN return values for AWS DocDb Cluster To access the Ref value, use DBCluster .

Properties

DocDB Cluster is rather very simple in its configuration. There aren’t 200+ combinations of EngineName and Engine Version as for RDS, make life very easy.

However you can copy-paste all the properties you would find in the DocDB Cluster properties , some properties will be ignored in order to keep the automation going:

  • MasterUsername and MasterUserPassword

    These two will be auto generated and stored in secrets manager. The services linked to it will be granted GetSecretValue to it.

  • VpcSecurityGroupIds

    The security group will be generated for the DB specifically and allow services listed only.

  • AvailabilityZones

    Under trial, but not sure given that we give a Subnet Group why one would also define the AZs and it might conflict.

  • DBClusterIdentifier

    As usual, named resources make for a nightmare to rename etc. Instead, there will be a Name tag associated with your Cluster.

  • DBSubnetGroupName

    Equally gets created only. For now.

  • SnapshotIdentifier

    Untested - 2020-11-13 - will support it later.

MacroParameters

These parameters will allow you to define extra parameters to define your cluster successfully.

Instances: []
DBClusterParameterGroup: {} # AWS DocDB::DBClusterParameterGroup properties

Instances

List of DocDB instances. The aspiration is to follow the same syntax as the DocDB Instance .

Note

Not all Properties are respected, instead, they follow logically the attachment to the DocDB Cluster.

Instances:
  - DBInstanceClass: <db instance type>
    PreferredMaintenanceWindow: <window definition>
    AutoMinorVersionUpgrade: bool

Hint

If you do not define an instance, ECS ComposeX automatically creates a new one with a single node of type db.t3.medium

DBClusterParameterGroup

Allows you to create on-the-fly parameter groups to tune your DocDB cluster. Refer to DocDB DBClusterParameterGroup for more details.

parameter groups example
Description: "description"
Family: "docdb3.6"
Name: "sampleParameterGroup"
Parameters:
  audit_logs: "disabled"
  tls: "enabled"
  ttl_monitor: "enabled"

Access

For this resource, you can leave Access empty, the necessary Security Groups and IAM access to the DB Secret will be done for you.

Available options

Access:
  DBCluster: RO # Grants Read/Describe access only to the DB Cluster.

Settings

See Settings . Subnets supported for this resource.

Lookup

Lookup for this resource will accept 2 key elements

  • cluster # required, allows to define how to lookup the cluster

  • secret # optional, allows do point to the secret in AWS Secrets Manager that contains connection details to the Cluster.

Credentials

The credentials structure remains the same as for RDS SQL versions

DocumentDB secret structure after attachment
{
  "dbClusterIdentifier": "<str>",
  "password": "<str>",
  "engine": "<str>",
  "port": "<int>",
  "host": "<str>",
  "username": "<str>"
}

Examples

Sample to crate two DBs with different instances configuration
x-docdb:
  docdbA:
    Properties: {}
    Services:
      app03:
  docdbB:
    MacroParameters:
      Instances:
        - DBInstanceClass: db.r5.large
        - AutoMinorVersionUpgrade: true
          DBInstanceClass: db.r5.xlarge
    Properties: {}
    Services:
      app03:
        ReturnValues:
          DBClusterName: DOCDB_DB_B
  docdbC:
    MacroParameters:
      DBClusterParameterGroup:
        Description: Some description
        Family: docdb4.0
        Name: sampleParameterGroup
        Parameters:
          audit_logs: disabled
          tls: disabled
          ttl_monitor: enabled
      Instances:
        - DBInstanceClass: db.r5.large
        - AutoMinorVersionUpgrade: true
          DBInstanceClass: db.t3.medium
    Properties:
      BackupRetentionPeriod: 7
      DBSubnetGroupName: String
      DeletionProtection: false
      EngineVersion: 4.0.0
      StorageEncrypted: true
      Tags:
        - Key: Name
          Value: docdb_C
    Services:
      app03:
        Access:
          DBCluster: RO
        SecretsMappings:
          Mappings:
            - SecretKey: host
              VarName: DB_HOST
Create a DocDB and import an existing one.
x-docdb:
  docdbA:
    Properties: {}
    Services:
      app03:
        access: RW
  docdbB:
    Lookup:
      cluster:
        Name: docdbb-purmjgtgvyqr
        Tags:
          - CreatedByComposeX: 'true'
          - Name: docdb.docdbB
      secret:
        Tags:
          - aws:cloudformation:logical-id: docdbBSecret
    Services:
      app03:
        Access: RW

JSON Schema

Model

x-docdb

x-docdb.spec.json

x-docdb specification

type

object

properties

  • Lookup

#/definitions/Lookup

  • Properties

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-docdb-dbcluster.html

type

object

  • Settings

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

  • Services

x-rds-common.spec.json#/definitions/ServicesDef

  • MacroParameters

#/definitions/MacroParameters

  • SecretsMappings

x-rds-common.spec.json#/definitions/SecretsMappingsDef

additionalProperties

False

definitions

  • Lookup

type

object

properties

  • RoleArn

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

  • cluster

type

object

properties

  • Arn

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

  • Identifier

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

  • Tags

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

  • MacroParameters

type

object

properties

  • Instances

type

array

items

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-docdb-dbinstance.html

type

object

  • DBClusterParameterGroup

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-docdb-dbclusterparametergroup.html

type

object

Definition

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "id": "x-docdb.spec.json",
  "$id": "x-docdb.spec.json",
  "title": "x-docdb",
  "description": "x-docdb specification",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "Lookup": {
      "$ref": "#/definitions/Lookup"
    },
    "Properties": {
      "type": "object",
      "description": "https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-docdb-dbcluster.html"
    },
    "Settings": {
      "$ref": "x-resources.common.spec.json#/definitions/Settings"
    },
    "Services": {
      "$ref": "x-rds-common.spec.json#/definitions/ServicesDef"
    },
    "MacroParameters": {
      "$ref": "#/definitions/MacroParameters"
    },
    "SecretsMappings": {
      "$ref": "x-rds-common.spec.json#/definitions/SecretsMappingsDef"
    }
  },
  "oneOf": [
    {
      "required": [
        "Properties"
      ]
    },
    {
      "required": [
        "Lookup"
      ]
    }
  ],
  "definitions": {
    "Lookup": {
      "type": "object",
      "properties": {
        "RoleArn": {
          "$ref": "x-resources.common.spec.json#/definitions/Lookup/properties/RoleArn"
        },
        "cluster": {
          "type": "object",
          "properties": {
            "Arn": {
              "$ref": "x-resources.common.spec.json#/definitions/Lookup/properties/Arn"
            },
            "Identifier": {
              "$ref": "x-resources.common.spec.json#/definitions/Lookup/properties/Identifier"
            },
            "Tags": {
              "$ref": "x-resources.common.spec.json#/definitions/Lookup/properties/Tags"
            }
          }
        }
      }
    },
    "MacroParameters": {
      "type": "object",
      "properties": {
        "Instances": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-docdb-dbinstance.html"
          }
        },
        "DBClusterParameterGroup": {
          "type": "object",
          "description": "https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-docdb-dbclusterparametergroup.html"
        }
      }
    }
  }
}

Test files

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