amazon.aws.rds_cluster module – rds_cluster module
Note
This module is part of the amazon.aws collection (version 7.4.0).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install amazon.aws.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: amazon.aws.rds_cluster.
New in amazon.aws 5.0.0
Synopsis
Create, modify, and delete RDS clusters.
This module was originally added to
community.awsin release 3.2.0.
Requirements
The below requirements are needed on the host that executes this module.
python >= 3.6
boto3 >= 1.26.0
botocore >= 1.29.0
Parameters
Parameter |
Comments |
|---|---|
AWS access key ID. See the AWS documentation for more information about access tokens https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys. The The aws_access_key and profile options are mutually exclusive. The aws_access_key_id alias was added in release 5.1.0 for consistency with the AWS botocore SDK. The ec2_access_key alias has been deprecated and will be removed in a release after 2024-12-01. Support for the |
|
The amount of storage in gibibytes (GiB) to allocate to each DB instance in the Multi-AZ DB cluster. This setting is required to create a Multi-AZ DB cluster. allocated_storage require botocore >= 1.23.44. |
|
A value that specifies whether modifying a cluster with new_db_cluster_identifier and master_user_password should be applied as soon as possible, regardless of the preferred_maintenance_window setting. If Choices:
|
|
A list of EC2 Availability Zones that instances in the DB cluster can be created in. May be used when creating a cluster or when restoring from S3 or a snapshot. |
|
The location of a CA Bundle to use when validating SSL certificates. The |
|
A dictionary to modify the botocore configuration. Parameters can be found in the AWS documentation https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config. |
|
The timestamp of the time to backtrack the DB cluster to in ISO 8601 format, such as “2017-07-08T18:00Z”. |
|
The target backtrack window, in seconds. To disable backtracking, set this value to If specified, this value must be set to a number from |
|
The number of days for which automated backups are retained (must be within Default: |
|
The character set to associate with the DB cluster. |
|
Indicates whether to copy all tags from the DB cluster to snapshots of the DB cluster. The default is not to copy them. Choices:
|
|
Which source to use if creating from a template (an existing cluster, S3 bucket, or snapshot). Choices:
|
|
The name for your database. If a name is not provided Amazon RDS will not create a database. |
|
The DB cluster (lowercase) identifier. The identifier must contain from 1 to 63 letters, numbers, or hyphens and the first character must be a letter and may not end in a hyphen or contain consecutive hyphens. |
|
The compute and memory capacity of each DB instance in the Multi-AZ DB cluster, for example Not all DB instance classes are available in all Amazon Web Services Regions, or for all database engines. For the full list of DB instance classes and availability for your engine visit https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.DBInstanceClass.html. This setting is required to create a Multi-AZ DB cluster. db_cluster_instance_class require botocore >= 1.23.44. |
|
The name of the DB cluster parameter group to associate with this DB cluster. If this argument is omitted when creating a cluster, the default DB cluster parameter group for the specified DB engine and version is used. |
|
A DB subnet group to associate with this DB cluster if not using the default. |
|
Use a The Choices:
|
|
A value that indicates whether the DB cluster has deletion protection enabled. The database can’t be deleted when deletion protection is enabled. By default, deletion protection is disabled. Choices:
|
|
The Active Directory directory ID to create the DB cluster in. |
|
Specify the name of the IAM role to be used when making API calls to the Directory Service. |
|
A list of log types that need to be enabled for exporting to CloudWatch Logs. Engine aurora-mysql supports Engine aurora-postgresql supports |
|
A value that indicates whether to enable this DB cluster to forward write operations to the primary cluster of an Aurora global database. By default, write operations are not allowed on Aurora DB clusters that are secondary clusters in an Aurora global database. This value can be only set on Aurora DB clusters that are members of an Aurora global database. Choices:
|
|
A value that indicates whether to enable the HTTP endpoint for an Aurora Serverless DB cluster. By default, the HTTP endpoint is disabled. Choices:
|
|
Enable mapping of AWS Identity and Access Management (IAM) accounts to database accounts. If this option is omitted when creating the cluster, Amazon RDS sets this to Choices:
|
|
URL to connect to instead of the default AWS endpoints. While this can be used to connection to other AWS-compatible services the amazon.aws and community.aws collections are only tested against AWS. The The ec2_url and s3_url aliases have been deprecated and will be removed in a release after 2024-12-01. Support for the |
|
The name of the database engine to be used for this DB cluster. This is required to create a cluster. The combinaison of engine and engine_mode may not be supported. See AWS documentation for details: Amazon RDS Documentation. When engine=mysql, allocated_storage, iops and db_cluster_instance_class must also be specified. When engine=postgres, allocated_storage, iops and db_cluster_instance_class must also be specified. Support for Choices:
|
|
The DB engine mode of the DB cluster. The combination of engine and engine_mode may not be supported. See AWS documentation for details: Amazon RDS Documentation. Choices:
|
|
The version number of the database engine to use. For Aurora MySQL that could be Aurora PostgreSQL example, |
|
The DB cluster snapshot identifier of the new DB cluster snapshot created when skip_final_snapshot=false. |
|
A boolean to indicate if the DB cluster should be forced to backtrack when binary logging is enabled. Otherwise, an error occurs when binary logging is enabled. Choices:
|
|
Set to Since comparing passwords to determine if it needs to be updated is not possible this is set to Choices:
|
|
The global cluster ID of an Aurora cluster that becomes the primary cluster in the new global database cluster. |
|
The amount of Provisioned IOPS (input/output operations per second) to be initially allocated for each DB instance in the Multi-AZ DB cluster. This setting is required to create a Multi-AZ DB cluster Must be a multiple between .5 and 50 of the storage amount for the DB cluster. iops require botocore >= 1.23.44. |
|
The AWS KMS key identifier (the ARN, unless you are creating a cluster in the same account that owns the KMS key, in which case the KMS key alias may be used). If replication_source_identifier specifies an encrypted source Amazon RDS will use the key used toe encrypt the source. If storage_encrypted=true and and replication_source_identifier is not provided, the default encryption key is used. |
|
An 8-41 character password for the master database user. The password can contain any printable ASCII character except To modify the password use force_password_update. Use apply immediately to change the password immediately, otherwise it is updated during the next maintenance window. |
|
The name of the master user for the DB cluster. Must be 1-16 letters or numbers and begin with a letter. |
|
The new DB cluster (lowercase) identifier for the DB cluster when renaming a DB cluster. The identifier must contain from 1 to 63 letters, numbers, or hyphens and the first character must be a letter and may not end in a hyphen or contain consecutive hyphens. Use apply_immediately to rename immediately, otherwise it is updated during the next maintenance window. |
|
The option group to associate with the DB cluster. |
|
The port number on which the instances in the DB cluster accept connections. If not specified, Amazon RDS defaults this to |
|
The daily time range (in UTC) of at least 30 minutes, during which automated backups are created if automated backups are enabled using backup_retention_period. The option must be in the format of “hh24:mi-hh24:mi” and not conflict with preferred_maintenance_window. |
|
The weekly time range (in UTC) of at least 30 minutes, during which system maintenance can occur. The option must be in the format “ddd:hh24:mi-ddd:hh24:mi” where ddd is one of Mon, Tue, Wed, Thu, Fri, Sat, Sun. |
|
A named AWS profile to use for authentication. See the AWS documentation for more information about named profiles https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html. The The profile option is mutually exclusive with the aws_access_key, aws_secret_key and security_token options. |
|
Set to Choices:
|
|
Whether or not to disable Cloudwatch logs enabled for the DB cluster that are not provided in enable_cloudwatch_logs_exports. Set enable_cloudwatch_logs_exports to an empty list to disable all. Choices:
|
|
Set to Can be applied to vpc_security_group_ids Choices:
|
|
If purge_tags=true and tags is set, existing tags will be purged from the resource to match exactly what is defined by tags parameter. If the tags parameter is not set then tags will not be modified, even if purge_tags=True. Tag keys beginning with Choices:
|
|
The AWS region to use. For global services such as IAM, Route53 and CloudFront, region is ignored. The See the Amazon AWS documentation for more information http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region. The Support for the |
|
If set to Parameters global_cluster_identifier, db_cluster_identifier must be specified when remove_from_global_db=true. Choices:
|
|
The Amazon Resource Name (ARN) of the source DB instance or DB cluster if this DB cluster is created as a Read Replica. |
|
The UTC date and time to restore the DB cluster to. Must be in the format “2015-03-07T23:45:00Z”. If this is not provided while restoring a cluster, use_latest_restorable_time must be. May not be specified if restore_type is copy-on-write. |
|
The type of restore to be performed. If not provided, Amazon RDS uses full-copy. Choices:
|
|
The Amazon Resource Name (ARN) of the IAM role to associate with the Aurora DB cluster, for example “arn:aws:iam::123456789012:role/AuroraAccessRole” |
|
The name of the Amazon S3 bucket that contains the data used to create the Amazon Aurora DB cluster. |
|
The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that authorizes Amazon RDS to access the Amazon S3 bucket on your behalf. |
|
The prefix for all of the file names that contain the data used to create the Amazon Aurora DB cluster. If you do not specify a SourceS3Prefix value, then the Amazon Aurora DB cluster is created by using all of the files in the Amazon S3 bucket. |
|
AWS secret access key. See the AWS documentation for more information about access tokens https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys. The The secret_key and profile options are mutually exclusive. The aws_secret_access_key alias was added in release 5.1.0 for consistency with the AWS botocore SDK. The ec2_secret_key alias has been deprecated and will be removed in a release after 2024-12-01. Support for the |
|
Contains the scaling configuration of an Aurora Serverless v2 DB cluster. |
|
The maximum number of Aurora capacity units (ACUs) for a DB instance in an Aurora Serverless v2 cluster. ACU values can be specified in in half-step increments, such as The largest possible value is |
|
The minimum number of Aurora capacity units (ACUs) for a DB instance in an Aurora Serverless v2 cluster. ACU values can be specified in in half-step increments, such as The smallest possible value is |
|
AWS STS session token for use with temporary credentials. See the AWS documentation for more information about access tokens https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys. The The security_token and profile options are mutually exclusive. Aliases aws_session_token and session_token were added in release 3.2.0, with the parameter being renamed from security_token to session_token in release 6.0.0. The security_token, aws_security_token, and access_token aliases have been deprecated and will be removed in a release after 2024-12-01. Support for the |
|
Whether a final DB cluster snapshot is created before the DB cluster is deleted. If this is Choices:
|
|
The identifier for the DB snapshot or DB cluster snapshot to restore from. You can use either the name or the ARN to specify a DB cluster snapshot. However, you can use only the ARN to specify a DB snapshot. |
|
The identifier of the source DB cluster from which to restore. |
|
The identifier for the database engine that was backed up to create the files stored in the Amazon S3 bucket. Choices:
|
|
The version of the database that the backup files were created from. |
|
The ID of the region that contains the source for the DB cluster. |
|
Whether the snapshot should exist or not.
Support for Choices:
|
|
Whether the DB cluster is encrypted. Choices:
|
|
Specifies the storage type to be associated with the DB cluster. This setting is required to create a Multi-AZ DB cluster. When specified, a value for the iops parameter is required. storage_type require botocore >= 1.23.44. Defaults to Choices:
|
|
A dictionary representing the tags to be applied to the resource. If the tags parameter is not set then tags will not be modified. |
|
If backtrack_to is set to a timestamp earlier than the earliest backtrack time, this value backtracks the DB cluster to the earliest possible backtrack time. Otherwise, an error occurs. Choices:
|
|
Whether to restore the DB cluster to the latest restorable backup time. Only one of use_latest_restorable_time and restore_to_time may be provided. Choices:
|
|
When set to Setting validate_certs=false is strongly discouraged, as an alternative, consider setting aws_ca_bundle instead. Choices:
|
|
A list of EC2 VPC security groups to associate with the DB cluster. |
|
Whether to wait for the cluster to be available or deleted. Choices:
|
Notes
Note
Caution: For modules, environment variables and configuration files are read from the Ansible ‘host’ context and not the ‘controller’ context. As such, files may need to be explicitly copied to the ‘host’. For lookup and connection plugins, environment variables and configuration files are read from the Ansible ‘controller’ context and not the ‘host’ context.
The AWS SDK (boto3) that Ansible uses may also read defaults for credentials and other settings, such as the region, from its configuration files in the Ansible ‘host’ context (typically
~/.aws/credentials). See https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html for more information.
Examples
# Note: These examples do not set authentication details, see the AWS Guide for details.
- name: Create minimal aurora cluster in default VPC and default subnet group
amazon.aws.rds_cluster:
cluster_id: "{{ cluster_id }}"
engine: "aurora"
password: "{{ password }}"
username: "{{ username }}"
- name: Add a new security group without purge
amazon.aws.rds_cluster:
id: "{{ cluster_id }}"
state: present
vpc_security_group_ids:
- sg-0be17ba10c9286b0b
purge_security_groups: false
- name: Modify password
amazon.aws.rds_cluster:
id: "{{ cluster_id }}"
state: present
password: "{{ new_password }}"
force_update_password: true
apply_immediately: true
- name: Rename the cluster
amazon.aws.rds_cluster:
engine: aurora
password: "{{ password }}"
username: "{{ username }}"
cluster_id: "cluster-{{ resource_prefix }}"
new_cluster_id: "cluster-{{ resource_prefix }}-renamed"
apply_immediately: true
- name: Delete aurora cluster without creating a final snapshot
amazon.aws.rds_cluster:
engine: aurora
password: "{{ password }}"
username: "{{ username }}"
cluster_id: "{{ cluster_id }}"
skip_final_snapshot: true
tags:
Name: "cluster-{{ resource_prefix }}"
Created_By: "Ansible_rds_cluster_integration_test"
state: absent
- name: Restore cluster from source snapshot
amazon.aws.rds_cluster:
engine: aurora
password: "{{ password }}"
username: "{{ username }}"
cluster_id: "cluster-{{ resource_prefix }}-restored"
snapshot_identifier: "cluster-{{ resource_prefix }}-snapshot"
- name: Create an Aurora PostgreSQL cluster and attach an intance
amazon.aws.rds_cluster:
state: present
engine: aurora-postgresql
engine_mode: provisioned
cluster_id: '{{ cluster_id }}'
username: '{{ username }}'
password: '{{ password }}'
- name: Attach a new instance to the cluster
amazon.aws.rds_instance:
id: '{{ instance_id }}'
cluster_id: '{{ cluster_id }}'
engine: aurora-postgresql
state: present
db_instance_class: 'db.t3.medium'
- name: Remove a cluster from global DB (do not delete)
amazon.aws.rds_cluster:
db_cluster_identifier: '{{ cluster_id }}'
global_cluster_identifier: '{{ global_cluster_id }}'
remove_from_global_db: true
- name: Remove a cluster from global DB and Delete without creating a final snapshot
amazon.aws.rds_cluster:
engine: aurora
password: "{{ password }}"
username: "{{ username }}"
cluster_id: "{{ cluster_id }}"
skip_final_snapshot: true
remove_from_global_db: true
wait: true
state: absent
- name: Update cluster port and WAIT for remove secondary DB cluster from global DB to complete
amazon.aws.rds_cluster:
db_cluster_identifier: "{{ secondary_cluster_name }}"
global_cluster_identifier: "{{ global_cluster_name }}"
remove_from_global_db: true
state: present
port: 3389
region: "{{ secondary_cluster_region }}"
- name: Update cluster port and DO NOT WAIT for remove secondary DB cluster from global DB to complete
amazon.aws.rds_cluster:
db_cluster_identifier: "{{ secondary_cluster_name }}"
global_cluster_identifier: "{{ global_cluster_name }}"
remove_from_global_db: true
state: present
port: 3389
region: "{{ secondary_cluster_region }}"
wait: false
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
The status of the database activity stream. Returned: always Sample: |
|
The allocated storage size in gigabytes. Since aurora storage size is not fixed this is always 1 for aurora database engines. Returned: always Sample: |
|
A list of dictionaries of the AWS Identity and Access Management (IAM) roles that are associated with the DB cluster. Each dictionary contains the role_arn and the status of the role. Returned: always Sample: |
|
The list of availability zones that instances in the DB cluster can be created in. Returned: always Sample: |
|
The number of days for which automatic DB snapshots are retained. Returned: always Sample: |
|
If the RDS cluster has changed. Returned: always Sample: |
|
The time in UTC when the DB cluster was created. Returned: always Sample: |
|
Specifies whether tags are copied from the DB cluster to snapshots of the DB cluster. Returned: always Sample: |
|
Specifies whether the DB cluster is a clone of a DB cluster owned by a different Amazon Web Services account. Returned: always Sample: |
|
The Amazon Resource Name (ARN) for the DB cluster. Returned: always Sample: |
|
The lowercase user-supplied DB cluster identifier. Returned: always Sample: |
|
A list of dictionaries containing information about the instances in the cluster. Each dictionary contains the db_instance_identifier, is_cluster_writer (bool), db_cluster_parameter_group_status, and promotion_tier (int). Returned: always Sample: |
|
The parameter group associated with the DB cluster. Returned: always Sample: |
|
The AWS Region-unique, immutable identifier for the DB cluster. Returned: always Sample: |
|
The name of the subnet group associated with the DB Cluster. Returned: always Sample: |
|
Indicates if the DB cluster has deletion protection enabled. The database can’t be deleted when deletion protection is enabled. Returned: always Sample: |
|
The Active Directory Domain membership records associated with the DB cluster. Returned: always Sample: |
|
The earliest time to which a database can be restored with point-in-time restore. Returned: always Sample: |
|
The connection endpoint for the primary instance of the DB cluster. Returned: always Sample: |
|
The database engine of the DB cluster. Returned: always Sample: |
|
The DB engine mode of the DB cluster. Returned: always Sample: |
|
The database engine version. Returned: always Sample: |
|
The ID that Amazon Route 53 assigns when you create a hosted zone. Returned: always Sample: |
|
A value that indicates whether the HTTP endpoint for an Aurora Serverless DB cluster is enabled. Returned: always Sample: |
|
Whether IAM accounts may be mapped to database accounts. Returned: always Sample: |
|
The latest time to which a database can be restored with point-in-time restore. Returned: always Sample: |
|
The master username for the DB cluster. Returned: always Sample: |
|
Whether the DB cluster has instances in multiple availability zones. Returned: always Sample: |
|
The port that the database engine is listening on. Returned: always Sample: |
|
The UTC weekly time range during which system maintenance can occur. Returned: always Sample: |
|
The UTC weekly time range during which system maintenance can occur. Returned: always Sample: |
|
A list of read replica ID strings associated with the DB cluster. Returned: always Sample: |
|
The reader endpoint for the DB cluster. Returned: always Sample: |
|
The scaling configuration for an Aurora Serverless v2 DB cluster. Returned: when configured Sample: |
|
The status of the DB cluster. Returned: always Sample: |
|
Whether the DB cluster is storage encrypted. Returned: always Sample: |
|
A list of tags consisting of key-value pairs. Returned: always Sample: |
|
A dictionary of key value pairs. Returned: always Sample: |
|
A list of the DB cluster’s security groups and their status. Returned: always |
|
Status of the security group. Returned: always Sample: |
|
Security group of the cluster. Returned: always Sample: |