community.aws.rds_instance module – Manage RDS instances
Note
This module is part of the community.aws collection (version 3.6.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 community.aws.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.aws.rds_instance.
New in community.aws 1.0.0
Synopsis
Create, modify, and delete RDS instances.
Requirements
The below requirements are needed on the host that executes this module.
python >= 3.6
boto3 >= 1.16.0
botocore >= 1.19.0
Parameters
Parameter |
Comments |
|---|---|
The amount of storage (in gibibytes) to allocate for the DB instance. |
|
Whether to allow major version upgrades. Choices:
|
|
A value that specifies whether modifying an instance with new_db_instance_identifier and master_user_password should be applied as soon as possible, regardless of the preferred_maintenance_window setting. If false, changes are applied during the next maintenance window. Choices:
|
|
Whether minor version upgrades are applied automatically to the DB instance during the maintenance window. Choices:
|
|
A list of EC2 Availability Zones that the DB instance can be created in. May be used when creating an instance or when restoring from S3 or a snapshot. Mutually exclusive with multi_az. |
|
If profile is set this parameter is ignored. Passing the aws_access_key and profile options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. |
|
The location of a CA Bundle to use when validating SSL certificates. Not used by boto 2 based modules. Note: The CA Bundle is read ‘module’ side and may need to be explicitly copied from the controller if not run locally. |
|
A dictionary to modify the botocore configuration. Parameters can be found at https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config. Only the ‘user_agent’ key is used for boto modules. See http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto for more boto configuration. |
|
If profile is set this parameter is ignored. Passing the aws_secret_key and profile options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. |
|
The number of days for which automated backups are retained. When set to May be used when creating a new instance, when restoring from S3, or when modifying an instance. |
|
The identifier of the CA certificate for the DB instance. |
|
The character set to associate with the DB instance. |
|
Whether or not to copy all tags from the DB instance to snapshots of the instance. When initially creating a DB instance the RDS API defaults this to false if unspecified. Choices:
|
|
Which source to use if restoring from a template (an existing instance, S3 bucket, or snapshot). Choices:
|
|
The DB cluster (lowercase) identifier to add the aurora DB instance to. 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 the DB instance, for example db.t2.micro. |
|
The DB instance (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 name for your database. If a name is not provided Amazon RDS will not create a database. |
|
The name of the DB parameter group to associate with this DB instance. When creating the DB instance if this argument is omitted the default DBParameterGroup for the specified engine is used. |
|
(EC2-Classic platform) A list of DB security groups to associate with this DB instance. |
|
The identifier or ARN of the DB snapshot to restore from when using creation_source=snapshot. |
|
The DB subnet group name to use for the DB instance. |
|
Use a botocore.endpoint logger to parse the unique (rather than total) “resource:action” API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used. Choices:
|
|
A value that indicates whether the DB instance 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 Domain to restore the instance in. |
|
The name of the IAM role to be used when making API calls to the Directory Service. |
|
URL to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used. |
|
A list of log types that need to be enabled for exporting to CloudWatch Logs. |
|
Enable mapping of AWS Identity and Access Management (IAM) accounts to database accounts. If this option is omitted when creating the instance, Amazon RDS sets this to False. Choices:
|
|
Whether to enable Performance Insights for the DB instance. Choices:
|
|
The name of the database engine to be used for this DB instance. This is required to create an instance. Choices:
|
|
The version number of the database engine to use. For Aurora MySQL that could be 5.6.10a , 5.7.12. Aurora PostgreSQL example, 9.6.3 |
|
The DB instance snapshot identifier of the new DB instance snapshot created when skip_final_snapshot is false. |
|
Set to true to conduct the reboot through a MultiAZ failover. Choices:
|
|
Set to Choices:
|
|
List of Amazon Web Services Identity and Access Management (IAM) roles to associate with DB instance. |
|
The name of the feature associated with the IAM role. |
|
The ARN of the IAM role to associate with the DB instance. |
|
The Provisioned IOPS (I/O operations per second) value. Is only set when using storage_type is set to io1. |
|
The ARN of the AWS KMS key identifier for an encrypted DB instance. If you are creating a DB instance with the same AWS account that owns the KMS encryption key used to encrypt the new DB instance, then you can use the KMS key alias instead of the ARN for the KM encryption key. If storage_encrypted is true and and this option is not provided, the default encryption key is used. |
|
The license model for the DB instance. Several options are license-included, bring-your-own-license, and general-public-license. This option can also be omitted to default to an accepted value. |
|
An 8-41 character password for the master database user. The password can contain any printable ASCII character except “/”, “””, or “@”. To modify the password use force_update_password. 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 instance. Must be 1-16 letters or numbers and begin with a letter. |
|
The upper limit to which Amazon RDS can automatically scale the storage of the DB instance. |
|
The interval, in seconds, when Enhanced Monitoring metrics are collected for the DB instance. To disable collecting metrics, specify 0. Amazon RDS defaults this to 0 if omitted when initially creating a DB instance. |
|
The ARN for the IAM role that permits RDS to send enhanced monitoring metrics to Amazon CloudWatch Logs. |
|
Specifies if the DB instance is a Multi-AZ deployment. Mutually exclusive with availability_zone. Choices:
|
|
The new DB instance (lowercase) identifier for the DB instance when renaming a DB instance. 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 instance. |
|
The AWS KMS key identifier (ARN, name, or alias) for encryption of Performance Insights data. |
|
The amount of time, in days, to retain Performance Insights data. Valid values are 7 or 731. |
|
The port number on which the instances accept connections. |
|
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 dictionary of Name, Value pairs to indicate the number of CPU cores and the number of threads per core for the DB instance class of the DB instance. Names are threadsPerCore and coreCount. Set this option to an empty dictionary to use the default processor features. |
|
The number of CPU cores |
|
The number of threads per core |
|
Using profile will override aws_access_key, aws_secret_key and security_token and support for passing them at the same time as profile has been deprecated. aws_access_key, aws_secret_key and security_token will be made mutually exclusive with profile after 2022-06-01. |
|
An integer that specifies the order in which an Aurora Replica is promoted to the primary instance after a failure of the existing primary instance. |
|
Specifies the accessibility options for the DB instance. A value of true specifies an Internet-facing instance with a publicly resolvable DNS name, which resolves to a public IP address. A value of false specifies an internal instance with a DNS name that resolves to a private IP address. Choices:
|
|
Set to False to retain any enabled cloudwatch logs that aren’t specified in the task and are associated with the instance. Choices:
|
|
Set to Choices:
|
|
Set to False to retain any enabled security groups that aren’t specified in the task and are associated with the instance. Can be applied to vpc_security_group_ids and db_security_groups Choices:
|
|
Set to False to retain any tags that aren’t specified in task and are associated with the instance. Choices:
|
|
Set to Choices:
|
|
The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region |
|
If using creation_source=instance this indicates the UTC date and time to restore from the source instance. For example, “2009-09-07T23:45:00Z”. May alternatively set use_latest_restore_time=True. Only one of use_latest_restorable_time and restore_time may be provided. |
|
The name of the Amazon S3 bucket that contains the data used to create the Amazon DB instance. |
|
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 DB instance. If you do not specify a SourceS3Prefix value, then the Amazon DB instance is created by using all of the files in the Amazon S3 bucket. |
|
If profile is set this parameter is ignored. Passing the security_token and profile options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. Aliases aws_session_token and session_token have been added in version 3.2.0. |
|
Whether a final DB instance snapshot is created before the DB instance is deleted. If this is false final_db_snapshot_identifier must be provided. Choices:
|
|
The identifier or ARN of the source DB instance from which to restore when creating a read replica or spinning up a point-in-time DB instance using creation_source=instance. If the source DB is not in the same region this should be an ARN. |
|
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 region of the DB instance from which the replica is created. |
|
Whether the snapshot should exist or not. rebooted is not idempotent and will leave the DB instance in a running state and start it prior to rebooting if it was stopped. present will leave the DB instance in the current running/stopped state, (running if creating the DB instance). state=running and state=started are synonyms, as are state=rebooted and state=restarted. Note - rebooting the instance is not idempotent. Choices:
|
|
Whether the DB instance is encrypted. Choices:
|
|
The storage type to be associated with the DB instance. storage_type does not apply to Aurora DB instances. Choices:
|
|
A dictionary of key value pairs to assign the DB instance. |
|
The ARN from the key store with which to associate the instance for Transparent Data Encryption. This is supported by Oracle or SQL Server DB instances and may be used in conjunction with |
|
The password for the given ARN from the key store in order to access the device. |
|
The time zone of the DB instance. |
|
Whether to restore the DB instance to the latest restorable backup time. Only one of use_latest_restorable_time and restore_time may be provided. Choices:
|
|
When set to “no”, SSL certificates will not be validated for communication with the AWS APIs. Choices:
|
|
A list of EC2 VPC security groups to associate with the DB instance. |
|
Whether to wait for the instance to be available, stopped, or deleted. At a later time a wait_timeout option may be added. Following each API call to create/modify/delete the instance a waiter is used with a 60 second delay 30 times until the instance reaches the expected state (available/stopped/deleted). The total task time may also be influenced by AWSRetry which helps stabilize if the instance is in an invalid state to operate on to begin with (such as if you try to stop it when it is in the process of rebooting). If setting this to False task retries and delays may make your playbook execution better handle timeouts for major modifications. Choices:
|
Notes
Note
If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence
AWS_URLorEC2_URL,AWS_PROFILEorAWS_DEFAULT_PROFILE,AWS_ACCESS_KEY_IDorAWS_ACCESS_KEYorEC2_ACCESS_KEY,AWS_SECRET_ACCESS_KEYorAWS_SECRET_KEYorEC2_SECRET_KEY,AWS_SECURITY_TOKENorEC2_SECURITY_TOKEN,AWS_REGIONorEC2_REGION,AWS_CA_BUNDLEWhen no credentials are explicitly provided the AWS SDK (boto3) that Ansible uses will fall back to its configuration files (typically
~/.aws/credentials). See https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html for more information.Modules based on the original AWS SDK (boto) may read their default configuration from different files. See https://boto.readthedocs.io/en/latest/boto_config_tut.html for more information.
AWS_REGIONorEC2_REGIONcan be typically be used to specify the AWS region, when required, but this can also be defined in the configuration files.
Examples
# Note: These examples do not set authentication details, see the AWS Guide for details.
- name: create minimal aurora instance in default VPC and default subnet group
community.aws.rds_instance:
engine: aurora
db_instance_identifier: ansible-test-aurora-db-instance
instance_type: db.t2.small
password: "{{ password }}"
username: "{{ username }}"
cluster_id: ansible-test-cluster # This cluster must exist - see rds_cluster to manage it
- name: Create a DB instance using the default AWS KMS encryption key
community.aws.rds_instance:
id: test-encrypted-db
state: present
engine: mariadb
storage_encrypted: True
db_instance_class: db.t2.medium
username: "{{ username }}"
password: "{{ password }}"
allocated_storage: "{{ allocated_storage }}"
- name: remove the DB instance without a final snapshot
community.aws.rds_instance:
id: "{{ instance_id }}"
state: absent
skip_final_snapshot: True
- name: remove the DB instance with a final snapshot
community.aws.rds_instance:
id: "{{ instance_id }}"
state: absent
final_snapshot_identifier: "{{ snapshot_id }}"
- name: Add a new security group without purge
community.aws.rds_instance:
id: "{{ instance_id }}"
state: present
vpc_security_group_ids:
- sg-0be17ba10c9286b0b
purge_security_groups: false
register: result
# Add IAM role to db instance
- name: Create IAM policy
community.aws.iam_managed_policy:
policy_name: "my-policy"
policy: "{{ lookup('file','files/policy.json') }}"
state: present
register: iam_policy
- name: Create IAM role
community.aws.iam_role:
assume_role_policy_document: "{{ lookup('file','files/assume_policy.json') }}"
name: "my-role"
state: present
managed_policy: "{{ iam_policy.policy.arn }}"
register: iam_role
- name: Create DB instance with added IAM role
community.aws.rds_instance:
id: "my-instance-id"
state: present
engine: postgres
engine_version: 14.2
username: "{{ username }}"
password: "{{ password }}"
db_instance_class: db.m6g.large
allocated_storage: "{{ allocated_storage }}"
iam_roles:
- role_arn: "{{ iam_role.arn }}"
feature_name: 's3Export'
- name: Remove IAM role from DB instance
community.aws.rds_instance:
id: "my-instance-id"
state: present
purge_iam_roles: yes
# Restore DB instance from snapshot
- name: Create a snapshot and wait until completion
community.aws.rds_instance_snapshot:
instance_id: 'my-instance-id'
snapshot_id: 'my-new-snapshot'
state: present
wait: yes
register: snapshot
- name: Restore DB from snapshot
community.aws.rds_instance:
id: 'my-restored-db'
creation_source: snapshot
snapshot_identifier: 'my-new-snapshot'
engine: mariadb
state: present
register: restored_db
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
The allocated storage size in gigabytes. This is always 1 for aurora database engines. Returned: always Sample: |
|
The list of currently associated roles. Returned: always Sample: |
|
Whether minor engine upgrades are applied automatically to the DB instance during the maintenance window. Returned: always Sample: |
|
The availability zone for the DB instance. Returned: always Sample: |
|
The number of days for which automated backups are retained. Returned: always Sample: |
|
The identifier of the CA certificate for the DB instance. Returned: always Sample: |
|
Whether tags are copied from the DB instance to snapshots of the DB instance. Returned: always Sample: |
|
The Amazon Resource Name (ARN) for the DB instance. Returned: always Sample: |
|
The name of the compute and memory capacity class of the DB instance. Returned: always Sample: |
|
The identifier of the DB instance Returned: always Sample: |
|
The port that the DB instance listens on. Returned: always Sample: |
|
The current state of this database. Returned: always Sample: |
|
The list of DB parameter groups applied to this DB instance. Returned: always |
|
The name of the DP parameter group. Returned: always Sample: |
|
The status of parameter updates. Returned: always Sample: |
|
A list of DB security groups associated with this DB instance. Returned: always Sample: |
|
The subnet group associated with the DB instance. Returned: always |
|
The description of the DB subnet group. Returned: always Sample: |
|
The name of the DB subnet group. Returned: always Sample: |
|
The status of the DB subnet group. Returned: always Sample: |
|
A list of Subnet elements. Returned: always |
|
The availability zone of the subnet. Returned: always |
|
The name of the Availability Zone. Returned: always Sample: |
|
The ID of the subnet. Returned: always Sample: |
|
The status of the subnet. Returned: always Sample: |
|
The VpcId of the DB subnet group. Returned: always Sample: |
|
The AWS Region-unique, immutable identifier for the DB instance. Returned: always Sample: |
|
Returned: always Sample: |
|
The Active Directory Domain membership records associated with the DB instance. Returned: always Sample: |
|
The connection endpoint. Returned: always |
|
The DNS address of the DB instance. Returned: always Sample: |
|
The ID that Amazon Route 53 assigns when you create a hosted zone. Returned: always Sample: |
|
The port that the database engine is listening on. Returned: always Sample: |
|
The database engine version. Returned: always Sample: |
|
The database engine version. Returned: always Sample: |
|
Whether mapping of AWS Identity and Access Management (IAM) accounts to database accounts is enabled. Returned: always Sample: |
|
The date and time the DB instance was created. Returned: always Sample: |
|
The AWS KMS key identifier for the encrypted DB instance when storage_encrypted is true. Returned: When storage_encrypted is true Sample: |
|
The latest time to which a database can be restored with point-in-time restore. Returned: always Sample: |
|
The License model information for this DB instance. Returned: always Sample: |
|
The master username for the DB instance. Returned: always Sample: |
|
The upper limit to which Amazon RDS can automatically scale the storage of the DB instance. Returned: When max allocated storage is present. Sample: |
|
The interval, in seconds, between points when Enhanced Monitoring metrics are collected for the DB instance. 0 means collecting Enhanced Monitoring metrics is disabled. Returned: always Sample: |
|
Whether the DB instance is a Multi-AZ deployment. Returned: always Sample: |
|
The list of option group memberships for this DB instance. Returned: always |
|
The name of the option group that the instance belongs to. Returned: always Sample: |
|
The status of the DB instance’s option group membership. Returned: always Sample: |
|
The changes to the DB instance that are pending. Returned: always |
|
True if Performance Insights is enabled for the DB instance, and otherwise false. Returned: always Sample: |
|
The daily time range during which automated backups are created if automated backups are enabled. Returned: always Sample: |
|
The weekly time range (in UTC) during which system maintenance can occur. Returned: always Sample: |
|
True for an Internet-facing instance with a publicly resolvable DNS name, False to indicate an internal instance with a DNS name that resolves to a private IP address. Returned: always Sample: |
|
Identifiers of the Read Replicas associated with this DB instance. Returned: always Sample: |
|
Whether the DB instance is encrypted. Returned: always Sample: |
|
The storage type to be associated with the DB instance. Returned: always Sample: |
|
A dictionary of tags associated with the DB instance. Returned: always |
|
A list of VPC security group elements that the DB instance belongs to. Returned: always |
|
The status of the VPC security group. Returned: always Sample: |
|
The name of the VPC security group. Returned: always Sample: |