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.
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
{
"dbClusterIdentifier": "<str>",
"password": "<str>",
"engine": "<str>",
"port": "<int>",
"host": "<str>",
"username": "<str>"
}
Examples ¶
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
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 |
||||
|
#/definitions/Lookup |
|||
|
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-docdb-dbcluster.html |
|||
type |
object |
|||
|
x-resources.common.spec.json#/definitions/Settings |
|||
|
x-rds-common.spec.json#/definitions/ServicesDef |
|||
|
#/definitions/MacroParameters |
|||
|
x-rds-common.spec.json#/definitions/SecretsMappingsDef |
|||
additionalProperties |
False |
|||
definitions |
||||
|
type |
object |
||
properties |
||||
|
x-resources.common.spec.json#/definitions/Lookup/properties/RoleArn |
|||
|
type |
object |
||
properties |
||||
|
x-resources.common.spec.json#/definitions/Lookup/properties/Arn |
|||
|
x-resources.common.spec.json#/definitions/Lookup/properties/Identifier |
|||
|
x-resources.common.spec.json#/definitions/Lookup/properties/Tags |
|||
|
type |
object |
||
properties |
||||
|
type |
array |
||
items |
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-docdb-dbinstance.html |
|||
type |
object |
|||
|
||||
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.