x-rds

Syntax

x-rds:
  psql-dbA:
    Properties: {}
    MacroParameters: {}
    Settings: {}
    Services: []
    Lookup: {}

Properties

RDS clusters or instances need a lot of properties. In order to keep compatibility you can still provide all the properties that the RDS Cluster or RDS Instance would need with the same definition as in AWS CloudFormation.

However, some settings will be replaced automatically (at least for the foreseeable future), such as the master username and password. The reason for it is to allow to keep integration to your ECS Services as seamless as possible.

Using properties

When using Properties, you can use either the RDS Aurora Cluster properties or RDS Instances properties. ECS ComposeX will attempt to automatically identify whether this is a DB Cluster or DB Instance properties set. If successful, it will ingest all your properties, and explained earlier, interpolate a few with new ones created for you.

MacroParameters

MacroParameters for RDS allow you to set only very little settings / properties and let ECS ComposeX do the rest for you.

MacroParameters syntax
Engine: str
EngineVersion: str
UseServerless: bool
UseMultiAz: bool
ParametersGroup: {}         # Properties for parameters group as per AWS CFN definition
Instances: []               # Only valid when creating a DBCluster, allows to define multiple DB Instances
RdsFeatures: {}             # Custom settings to define AWS RDS AssociatedRoles
PermissionsBoundary: str    # Allow you to define an IAM boundary policy that will be used for the RDS IAM role(s)
MacroParameters definitions example
Engine: aurora-postgresql # Same as AWS CFN Engine property
EngineVersion: 11.7 # Same as AWS CFN EngineVersion property
UseServerless: False
UseMultiAz: True
ParametersGroups:
  Description: Some description
  Family: aurora-postgresql-11.7
  Parameters: {}
Instances: []
RdsFeatures:
  - Name: s3Import
    Resources:
      - x-s3::bucket-01
      - arn:aws:s3:::bucket/path/allowed/*
      - bucket-name

PermissionsBoundary

Allows to define whether an IAM Policy boundary is required for the IAM roles that will be created around the RDS Cluster/Instance.

Hint

This value can be either a policy name or policy ARN. When a policy Name, the ARN is built based on your Account ID.

RdsFeatures

Syntax definition
RdsFeatures:
  - Name: <DB Engine feature name>
  - Resources: [<str>]

The RDS Features is a wrapper to automatically define which RDS Features, supported by the Engine family, you might want to enable. For these features, which require an IAM role, it will create a new IAM role specifically linked to RDS and grant permissions based on the what the feature requires.

If you had set AssociatedRoles already in the permissions, then each FeatureName you have already defined that you might re-define in RdsFeatures will be skipped. If you wish to use RdsFeatures then remove that feature from the AssociateRoles definition.

Attention

This was primarily developed to allow feature request #375 so at the moment it only supports s3Import and s3Export.

Example with different bucket names syntax
x-rds:
  dbB:
    Properties: {}
    MacroParameters:
      PermissionsBoundary: policy-name
      RdsFeatures:
        - Name: s3Import
          Resources:
            - x-s3::bucket-01
            - arn:aws:s3:::sacrificial-lamb/folder/*
            - bucket-name
        - Name: s3Export
          Resources:
            - x-s3::bucket-01
            - arn:aws:s3:::sacrificial-lamb/folder/*
            - bucket-name

Hint

You can reference a S3 bucket defined in x-s3 . This supports S3 buckets created and referenced via Lookup

Services

At this point in time, there is no plan to deploy as part of ECS ComposeX a lambda function that would connect to the DB and create a DB/schema specifically for the microservice, as would this lambda function do.

The syntax for listing the services remains the same as the other x- resources but the access type won’t be respected.

Access types

Warning

The access key value won’t be respected at this stage. This is required to keep compatibility with other modules.

Settings

Supported Settings
EnvNames: [<str>] # List of Environment Variable names to use for exposure to container

Lookup

The lookup allows you to find your cluster or db instance and also the Secret associated with them to allow ECS Services to get access to these.

It will also find the DB security group and add an ingress rule.

x-rds:
  dba:
    Lookup:
      cluster:
        Name: cluster-identifier
        Tags:
          - sometag: value
      instance:
        Name: DB Instance Id
        Tags:
          - sometag: value
      secret:
        Tags:
          - sometag: value
        Name: secret/in/secretsmanager

When using AWS RDS Aurora, you should be specifying the cluster, otherwise the instance for “traditional” RDS instances.

Defaults

Credentials

Aurora and traditional RDS Databases support both Username/Password generic authentication. Due to the wide adoption of that authentication mechanism, all RDS Dbs will come with a username/password, auto generated and stored in AWS Secrets Manager.

Hint

We do plan to allow a tick button to enable Aurora authentication with IAM, however have not received a Feature Request for it.

AWS Secrets Manager integrates very nicely to AWS RDS. This has no intention to implement the rotation system at this point in time, however, it will generate the password for the database and expose it securely to the microservices which can via environment variables fetch

  • DB Endpoint

  • DB username

  • DB Password

  • DB Port

Examples

New DB Creation
x-rds:
  dbname:
    Properties:
      Engine: aurora-mysql
      EngineVersion: 5.7.12
    Services:
      - name: app01
        access: RW
Existing Cluster DB Lookup
x-rds:
  existing-cluster-dbA:
    Lookup:
      cluster:
        Tags:
          - key: value
      secret:
        Tags:
          - key: value

Hint

The DB Family group will be found automatically and the setting will allow creation of a new RDS Parameter group for the Cluster / DB Instance.