amazon.aws.rds_instance module – Manage RDS instances
Note
This module is part of the amazon.aws collection (version 6.5.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_instance.
New in amazon.aws 5.0.0
Synopsis
Create, modify, and delete RDS instances.
This module was originally added to
community.awsin release 1.0.0.
Requirements
The below requirements are needed on the host that executes this module.
python >= 3.6
boto3 >= 1.22.0
botocore >= 1.25.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) 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. |
|
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 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 The 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. |
|
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:
|
|
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 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 |
|
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 |
|
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. |
|
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:
|
|
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:
|
|
Set to 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 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. |
|
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 |
|
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 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. |
|
Desired state of the RDS Instance. state=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. Choices:
|
|
Whether the DB instance is encrypted. Choices:
|
|
The storage throughput when the storage_type is When the allocated storage is below 400 GB, the storage throughput will always be 125 mb/s. When the allocated storage is large than or equal 400 GB, the througput starts at 500 mb/s. Requires botocore >= 1.29.0. |
|
The storage type to be associated with the DB instance. storage_type does not apply to Aurora DB instances. 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. |
|
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 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 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
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 instance in default VPC and default subnet group
amazon.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
amazon.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
amazon.aws.rds_instance:
id: "{{ instance_id }}"
state: absent
skip_final_snapshot: True
- name: remove the DB instance with a final snapshot
amazon.aws.rds_instance:
id: "{{ instance_id }}"
state: absent
final_snapshot_identifier: "{{ snapshot_id }}"
- name: Add a new security group without purge
amazon.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
amazon.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
amazon.aws.rds_instance:
id: "my-instance-id"
state: present
purge_iam_roles: true
# Restore DB instance from snapshot
- name: Create a snapshot and wait until completion
amazon.aws.rds_instance_snapshot:
instance_id: 'my-instance-id'
snapshot_id: 'my-new-snapshot'
state: present
wait: true
register: snapshot
- name: Restore DB from snapshot
amazon.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. Requires minimum botocore version 1.29.44. 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: |