W3cubDocs

/Ansible 2.10

community.aws.rds_instance – Manage RDS instances

Note

This plugin is part of the community.aws collection.

To install it use: ansible-galaxy collection install community.aws.

To use it in a playbook, specify: community.aws.rds_instance.

New in version 1.0.0: of community.aws

Synopsis

  • Create, modify, and delete RDS instances.

Requirements

The below requirements are needed on the host that executes this module.

  • boto
  • boto3 >= 1.5.0
  • botocore
  • python >= 2.6

Parameters

Parameter Choices/Defaults Comments
allocated_storage
integer
The amount of storage (in gibibytes) to allocate for the DB instance.
allow_major_version_upgrade
boolean
    Choices:
  • no
  • yes
Whether to allow major version upgrades.
apply_immediately
boolean
    Choices:
  • no ←
  • yes
A value that specifies whether modifying a cluster 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.
auto_minor_version_upgrade
boolean
    Choices:
  • no
  • yes
Whether minor version upgrades are applied automatically to the DB instance during the maintenance window.
availability_zone
string
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. Mutually exclusive with multi_az.

aliases: az, zone
aws_access_key
string
AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.
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.

aliases: ec2_access_key, access_key
aws_ca_bundle
path
The location of a CA Bundle to use when validating SSL certificates.
Only used for boto3 based modules.
Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.
aws_config
dictionary
A dictionary to modify the botocore configuration.
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.
aws_secret_key
string
AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.
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.

aliases: ec2_secret_key, secret_key
backup_retention_period
integer
The number of days for which automated backups are retained.
When set to 0, automated backups will be disabled. (Not applicable if the DB instance is a source to read replicas)
May be used when creating a new cluster, when restoring from S3, or when modifying a cluster.
ca_certificate_identifier
string
The identifier of the CA certificate for the DB instance.
character_set_name
string
The character set to associate with the DB cluster.
copy_tags_to_snapshot
boolean
    Choices:
  • no
  • yes
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.
creation_source
string
    Choices:
  • snapshot
  • s3
  • instance
Which source to use if restoring from a template (an existing instance, S3 bucket, or snapshot).
db_cluster_identifier
string
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.

aliases: cluster_id
db_instance_class
string
The compute and memory capacity of the DB instance, for example db.t2.micro.

aliases: class, instance_type
db_instance_identifier
string / required
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.

aliases: instance_id, id
db_name
string
The name for your database. If a name is not provided Amazon RDS will not create a database.
db_parameter_group_name
string
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.
db_security_groups
list / elements=string
(EC2-Classic platform) A list of DB security groups to associate with this DB instance.
db_snapshot_identifier
string
The identifier for the DB snapshot to restore from if using creation_source=snapshot.
db_subnet_group_name
string
The DB subnet group name to use for the DB instance.

aliases: subnet_group
debug_botocore_endpoint_logs
boolean
    Choices:
  • no ←
  • yes
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.
domain
string
The Active Directory Domain to restore the instance in.
domain_iam_role_name
string
The name of the IAM role to be used when making API calls to the Directory Service.
ec2_url
string
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.

aliases: aws_endpoint_url, endpoint_url
enable_cloudwatch_logs_exports
list / elements=string
A list of log types that need to be enabled for exporting to CloudWatch Logs.

aliases: cloudwatch_log_exports
enable_iam_database_authentication
boolean
    Choices:
  • no
  • yes
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 False.
enable_performance_insights
boolean
    Choices:
  • no
  • yes
Whether to enable Performance Insights for the DB instance.
engine
string
The name of the database engine to be used for this DB instance. This is required to create an instance. Valid choices are aurora | aurora-mysql | aurora-postgresql | mariadb | mysql | oracle-ee | oracle-se | oracle-se1 | oracle-se2 | postgres | sqlserver-ee | sqlserver-ex | sqlserver-se | sqlserver-web
engine_version
string
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
final_db_snapshot_identifier
string
The DB instance snapshot identifier of the new DB instance snapshot created when skip_final_snapshot is false.

aliases: final_snapshot_identifier
force_failover
boolean
    Choices:
  • no
  • yes
Set to true to conduct the reboot through a MultiAZ failover.
force_update_password
boolean
    Choices:
  • no ←
  • yes
Set to True to update your cluster password with master_user_password. Since comparing passwords to determine if it needs to be updated is not possible this is set to False by default to allow idempotence.
iops
integer
The Provisioned IOPS (I/O operations per second) value. Is only set when using storage_type is set to io1.
kms_key_id
string
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.
license_model
string
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.
master_user_password
string
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_password_update. Use apply immediately to change the password immediately, otherwise it is updated during the next maintenance window.

aliases: password
master_username
string
The name of the master user for the DB cluster. Must be 1-16 letters or numbers and begin with a letter.

aliases: username
max_allocated_storage
integer
The upper limit to which Amazon RDS can automatically scale the storage of the DB instance.
monitoring_interval
integer
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.
monitoring_role_arn
string
The ARN for the IAM role that permits RDS to send enhanced monitoring metrics to Amazon CloudWatch Logs.
multi_az
boolean
    Choices:
  • no
  • yes
Specifies if the DB instance is a Multi-AZ deployment. Mutually exclusive with availability_zone.
new_db_instance_identifier
string
The new DB cluster (lowercase) identifier for the DB cluster 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.

aliases: new_instance_id, new_id
option_group_name
string
The option group to associate with the DB instance.
performance_insights_kms_key_id
string
The AWS KMS key identifier (ARN, name, or alias) for encryption of Performance Insights data.
performance_insights_retention_period
integer
The amount of time, in days, to retain Performance Insights data. Valid values are 7 or 731.
port
integer
The port number on which the instances accept connections.
preferred_backup_window
string
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.

aliases: backup_window
preferred_maintenance_window
string
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.

aliases: maintenance_window
processor_features
dictionary
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.
coreCount
string
The number of CPU cores
threadsPerCore
string
The number of threads per core
profile
string
Uses a boto profile. Only works with boto >= 2.24.0.
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.

aliases: aws_profile
promotion_tier
string
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.
publicly_accessible
boolean
    Choices:
  • no
  • yes
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.
purge_cloudwatch_logs_exports
boolean
    Choices:
  • no
  • yes ←
Set to False to retain any enabled cloudwatch logs that aren't specified in the task and are associated with the instance.
purge_tags
boolean
    Choices:
  • no
  • yes ←
Set to False to retain any tags that aren't specified in task and are associated with the instance.
read_replica
boolean
    Choices:
  • no
  • yes
Set to False to promote a read replica cluster or true to create one. When creating a read replica creation_source should be set to 'instance' or not provided. source_db_instance_identifier must be provided with this option.
region
string
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

aliases: aws_region, ec2_region
restore_time
string
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.
s3_bucket_name
string
The name of the Amazon S3 bucket that contains the data used to create the Amazon DB instance.
s3_ingestion_role_arn
string
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.
s3_prefix
string
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.
security_token
string
AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.
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_security_token, access_token
skip_final_snapshot
boolean
    Choices:
  • no ←
  • yes
Whether a final DB cluster snapshot is created before the DB cluster is deleted. If this is false final_db_snapshot_identifier must be provided.
snapshot_identifier
string
The ARN of the DB snapshot to restore from when using creation_source=snapshot.
source_db_instance_identifier
string
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.
source_engine
string
    Choices:
  • mysql
The identifier for the database engine that was backed up to create the files stored in the Amazon S3 bucket.
source_engine_version
string
The version of the database that the backup files were created from.
source_region
string
The region of the DB instance from which the replica is created.
state
string
    Choices:
  • present ←
  • absent
  • terminated
  • running
  • started
  • stopped
  • rebooted
  • restarted
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.
storage_encrypted
boolean
    Choices:
  • no
  • yes
Whether the DB instance is encrypted.
storage_type
string
    Choices:
  • standard
  • gp2
  • io1
The storage type to be associated with the DB instance. storage_type does not apply to Aurora DB instances.
tags
dictionary
A dictionary of key value pairs to assign the DB cluster.
tde_credential_arn
string
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 storage_encrypted though it might slightly affect the performance of your database.

aliases: transparent_data_encryption_arn
tde_credential_password
string
The password for the given ARN from the key store in order to access the device.

aliases: transparent_data_encryption_password
timezone
string
The time zone of the DB instance.
use_latest_restorable_time
boolean
    Choices:
  • no
  • yes
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.

aliases: restore_from_latest
validate_certs
boolean
    Choices:
  • no
  • yes ←
When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.
vpc_security_group_ids
list / elements=string
A list of EC2 VPC security groups to associate with the DB cluster.
wait
boolean
    Choices:
  • no
  • yes ←
Whether to wait for the cluster 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.

Notes

Note

  • If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence AWS_URL or EC2_URL, AWS_PROFILE or AWS_DEFAULT_PROFILE, AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY or EC2_ACCESS_KEY, AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY or EC2_SECRET_KEY, AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN, AWS_REGION or EC2_REGION, AWS_CA_BUNDLE
  • Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html
  • AWS_REGION or EC2_REGION can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file

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 }}"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
allocated_storage
integer
always
The allocated storage size in gibibytes. This is always 1 for aurora database engines.

Sample:
20
auto_minor_version_upgrade
boolean
always
Whether minor engine upgrades are applied automatically to the DB instance during the maintenance window.

Sample:
True
availability_zone
string
always
The availability zone for the DB instance.

Sample:
us-east-1f
backup_retention_period
integer
always
The number of days for which automated backups are retained.

Sample:
1
ca_certificate_identifier
string
always
The identifier of the CA certificate for the DB instance.

Sample:
rds-ca-2015
copy_tags_to_snapshot
boolean
always
Whether tags are copied from the DB instance to snapshots of the DB instance.
db_instance_arn
string
always
The Amazon Resource Name (ARN) for the DB instance.

Sample:
arn:aws:rds:us-east-1:123456789012:db:ansible-test
db_instance_class
string
always
The name of the compute and memory capacity class of the DB instance.

Sample:
db.m4.large
db_instance_identifier
string
always
The identifier of the DB instance

Sample:
ansible-test
db_instance_port
integer
always
The port that the DB instance listens on.
db_instance_status
string
always
The current state of this database.

Sample:
stopped
db_parameter_groups
complex
always
The list of DB parameter groups applied to this DB instance.
db_parameter_group_name
string
always
The name of the DP parameter group.

Sample:
default.mariadb10.0
parameter_apply_status
string
always
The status of parameter updates.

Sample:
in-sync
db_security_groups
list / elements=string
always
A list of DB security groups associated with this DB instance.
db_subnet_group
complex
always
The subnet group associated with the DB instance.
db_subnet_group_description
string
always
The description of the DB subnet group.

Sample:
default
db_subnet_group_name
string
always
The name of the DB subnet group.

Sample:
default
subnet_group_status
string
always
The status of the DB subnet group.

Sample:
Complete
subnets
complex
always
A list of Subnet elements.
subnet_availability_zone
complex
always
The availability zone of the subnet.
name
string
always
The name of the Availability Zone.

Sample:
us-east-1c
subnet_identifier
string
always
The ID of the subnet.

Sample:
subnet-12345678
subnet_status
string
always
The status of the subnet.

Sample:
Active
vpc_id
string
always
The VpcId of the DB subnet group.

Sample:
vpc-12345678
dbi_resource_id
string
always
The AWS Region-unique, immutable identifier for the DB instance.

Sample:
db-UHV3QRNWX4KB6GALCIGRML6QFA
domain_memberships
list / elements=string
always
The Active Directory Domain membership records associated with the DB instance.
endpoint
complex
always
The connection endpoint.
address
string
always
The DNS address of the DB instance.

Sample:
ansible-test.cvlrtwiennww.us-east-1.rds.amazonaws.com
hosted_zone_id
string
always
The ID that Amazon Route 53 assigns when you create a hosted zone.

Sample:
ZTR2ITUGPA61AM
port
integer
always
The port that the database engine is listening on.

Sample:
3306
engine
string
always
The database engine version.

Sample:
mariadb
engine_version
string
always
The database engine version.

Sample:
10.0.35
iam_database_authentication_enabled
boolean
always
Whether mapping of AWS Identity and Access Management (IAM) accounts to database accounts is enabled.
instance_create_time
string
always
The date and time the DB instance was created.

Sample:
2018-07-04T16:48:35.332000+00:00
kms_key_id
string
When storage_encrypted is true
The AWS KMS key identifier for the encrypted DB instance when storage_encrypted is true.

Sample:
arn:aws:kms:us-east-1:123456789012:key/70c45553-ad2e-4a85-9f14-cfeb47555c33
latest_restorable_time
string
always
The latest time to which a database can be restored with point-in-time restore.

Sample:
2018-07-04T16:50:50.642000+00:00
license_model
string
always
The License model information for this DB instance.

Sample:
general-public-license
master_username
string
always
The master username for the DB instance.

Sample:
test
max_allocated_storage
integer
When max allocated storage is present.
The upper limit to which Amazon RDS can automatically scale the storage of the DB instance.

Sample:
100
monitoring_interval
integer
always
The interval, in seconds, between points when Enhanced Monitoring metrics are collected for the DB instance. 0 means collecting Enhanced Monitoring metrics is disabled.
multi_az
boolean
always
Whether the DB instance is a Multi-AZ deployment.
option_group_memberships
complex
always
The list of option group memberships for this DB instance.
option_group_name
string
always
The name of the option group that the instance belongs to.

Sample:
default:mariadb-10-0
status
string
always
The status of the DB instance's option group membership.

Sample:
in-sync
pending_modified_values
complex
always
The changes to the DB instance that are pending.
performance_insights_enabled
boolean
always
True if Performance Insights is enabled for the DB instance, and otherwise false.
preferred_backup_window
string
always
The daily time range during which automated backups are created if automated backups are enabled.

Sample:
07:01-07:31
preferred_maintenance_window
string
always
The weekly time range (in UTC) during which system maintenance can occur.

Sample:
sun:09:31-sun:10:01
publicly_accessible
boolean
always
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.

Sample:
True
read_replica_db_instance_identifiers
list / elements=string
always
Identifiers of the Read Replicas associated with this DB instance.
storage_encrypted
boolean
always
Whether the DB instance is encrypted.
storage_type
string
always
The storage type to be associated with the DB instance.

Sample:
standard
tags
complex
always
A dictionary of tags associated with the DB instance.
vpc_security_groups
complex
always
A list of VPC security group elements that the DB instance belongs to.
status
string
always
The status of the VPC security group.

Sample:
active
vpc_security_group_id
string
always
The name of the VPC security group.

Sample:
sg-12345678


Authors

  • Sloane Hertel (@s-hertel)

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/community/aws/rds_instance_module.html