amazon.cloud.rds_db_instance module – Creates and manages resource creates an Amazon DB instance

Note

This module is part of the amazon.cloud collection (version 0.4.0).

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.cloud. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: amazon.cloud.rds_db_instance.

New in amazon.cloud 0.3.0

Synopsis

  • Creates and manages resource creates an Amazon DB instance.

  • The new DB instance can be an RDS DB instance, or it can be a DB instance in an Aurora DB cluster.

Requirements

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

  • python >= 3.9

  • boto3 >= 1.25.0

  • botocore >= 1.28.0

  • jsonpatch

Parameters

Parameter

Comments

access_key

aliases: aws_access_key_id, aws_access_key, ec2_access_key

string

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 AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variables may also be used in decreasing order of preference.

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 EC2_ACCESS_KEY environment variable has been deprecated and will be removed in a release after 2024-12-01.

allocated_storage

string

The amount of storage (in gigabytes) to be initially allocated for the database instance.

allow_major_version_upgrade

boolean

A value that indicates whether major version upgrades are allowed.

Changing this parameter doesnt result in an outage and the change is asynchronously applied as soon as possible.

Choices:

  • false

  • true

associated_roles

list / elements=dictionary

The AWS Identity and Access Management (IAM) roles associated with the DB instance.

feature_name

string

The name of the feature associated with the AWS Identity and Access Management (IAM) role.

IAM roles that are associated with a DB instance grant permission for the DB instance to access other AWS services on your behalf.

role_arn

string

The Amazon Resource Name (ARN) of the IAM role that is associated with the DB instance.

auto_minor_version_upgrade

boolean

A value that indicates whether minor engine upgrades are applied automatically to the DB instance during the maintenance window.

By default, minor engine upgrades are applied automatically.

Choices:

  • false

  • true

availability_zone

string

The Availability Zone (AZ) where the database will be created.

For information on AWS Regions and Availability Zones.

aws_ca_bundle

path

The location of a CA Bundle to use when validating SSL certificates.

The AWS_CA_BUNDLE environment variable may also be used.

aws_config

dictionary

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.

backup_retention_period

integer

The number of days for which automated backups are retained.

Setting this parameter to a positive number enables backups.

Setting this parameter to 0 disables automated backups.

Default: 1

ca_certificate_identifier

string

The identifier of the CA certificate for this DB instance.

certificate_details

dictionary

Returns the details of the DB instances server certificate.

certificate_rotation_restart

boolean

A value that indicates whether the DB instance is restarted when you rotate your SSL/TLS certificate.

By default, the DB instance is restarted when you rotate your SSL/TLS certificate.

The certificate is not updated until the DB instance is restarted.

If you are using SSL/TLS to connect to the DB instance, follow the appropriate instructions for your DB engine to rotate your SSL/TLS certificate.

This setting doesnt apply to RDS Custom.

Choices:

  • false

  • true

character_set_name

string

For supported engines, indicates that the DB instance should be associated with the specified character set.

copy_tags_to_snapshot

boolean

A value that indicates whether to copy tags from the DB instance to snapshots of the DB instance.

By default, tags are not copied.

Choices:

  • false

  • true

custom_iam_instance_profile

string

The instance profile associated with the underlying Amazon EC2 instance of an RDS Custom DB instance.

The instance profile must meet the following requirements:.

* The profile must exist in your account.

* The profile must have an IAM role that Amazon EC2 has permissions to assume.

* The instance profile name and the associated IAM role name must start with the prefix AWSRDSCustom .

For the list of permissions required for the IAM role, see Configure IAM and your VPC in the Amazon RDS User Guide .

This setting is required for RDS Custom.

db_cluster_identifier

string

The identifier of the DB cluster that the instance will belong to.

db_cluster_snapshot_identifier

string

The identifier for the RDS for MySQL Multi-AZ DB cluster snapshot to restore from.

For more information on Multi-AZ DB clusters, see Multi-AZ deployments with two readable standby DB instances in the Amazon RDS User Guide .

Constraints:.

* Must match the identifier of an existing Multi-AZ DB cluster snapshot.

* Cant be specified when DBSnapshotIdentifier is specified.

* Must be specified when DBSnapshotIdentifier isnt specified.

* If you are restoring from a shared manual Multi-AZ DB cluster snapshot, the DBClusterSnapshotIdentifier must be the ARN of the shared snapshot.

* Cant be the identifier of an Aurora DB cluster snapshot.

* Cant be the identifier of an RDS for PostgreSQL Multi-AZ DB cluster snapshot.

db_instance_class

string

The compute and memory capacity of the DB instance, for example, db.m4.large.

Not all DB instance classes are available in all AWS Regions, or for all database engines.

db_instance_identifier

string

A name for the DB instance.

If you specify a name, AWS CloudFormation converts it to lowercase.

If you dont specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the DB instance.

db_name

string

The meaning of this parameter differs according to the database engine you use.

db_parameter_group_name

string

The name of an existing DB parameter group or a reference to an AWS::RDS::DBParameterGroup resource created in the template.

db_security_groups

list / elements=string

A list of the DB security groups to assign to the DB instance.

The list can include both the name of existing DB security groups or references to AWS::RDS::DBSecurityGroup resources created in the template.

db_snapshot_identifier

string

The name or Amazon Resource Name (ARN) of the DB snapshot thats used to restore the DB instance.

If youre restoring from a shared manual DB snapshot, you must specify the ARN of the snapshot.

db_subnet_group_name

string

A DB subnet group to associate with the DB instance.

If you update this value, the new subnet group must be a subnet group in a new VPC.

debug_botocore_endpoint_logs

boolean

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:

  • false ← (default)

  • true

delete_automated_backups

boolean

A value that indicates whether to remove automated backups immediately after the DB instance is deleted.

This parameter isnt case-sensitive.

The default is to remove automated backups immediately after the DB instance is deleted.

Choices:

  • false

  • true

deletion_protection

boolean

A value that indicates whether the DB instance has deletion protection enabled.

The database cant be deleted when deletion protection is enabled.

By default, deletion protection is disabled.

Choices:

  • false

  • true

domain

string

The Active Directory directory ID to create the DB instance in.

Currently, only MySQL, Microsoft SQL Server, Oracle, and PostgreSQL DB instances can be created in an Active Directory Domain.

domain_iam_role_name

string

Specify the name of the IAM role to be used when making API calls to the Directory Service.

enable_cloudwatch_logs_exports

list / elements=string

The list of log types that need to be enabled for exporting to CloudWatch Logs.

The values in the list depend on the DB engine being used.

enable_iam_database_authentication

boolean

A value that indicates whether to enable mapping of AWS Identity and Access Management (IAM) accounts to database accounts.

By default, mapping is disabled.

Choices:

  • false

  • true

enable_performance_insights

boolean

A value that indicates whether to enable Performance Insights for the DB instance.

Choices:

  • false

  • true

endpoint

dictionary

Specifies the connection endpoint.

endpoint_url

aliases: ec2_url, aws_endpoint_url, s3_url

string

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 AWS_URL or EC2_URL environment variables may also be used, in decreasing order of preference.

The ec2_url and s3_url aliases have been deprecated and will be removed in a release after 2024-12-01.

Support for the EC2_URL environment variable has been deprecated and will be removed in a release after 2024-12-01.

engine

string

The name of the database engine that you want to use for this DB instance.

engine_version

string

The version number of the database engine to use.

force

boolean

Cancel IN_PROGRESS and PENDING resource requestes.

Because you can only perform a single operation on a given resource at a time, there might be cases where you need to cancel the current resource operation to make the resource available so that another operation may be performed on it.

Choices:

  • false ← (default)

  • true

iops

integer

The number of I/O operations per second (IOPS) that the database provisions.

kms_key_id

string

The ARN of the AWS Key Management Service (AWS KMS) master key thats used to encrypt the DB instance.

license_model

string

License model information for this DB instance.

manage_master_user_password

boolean

A value that indicates whether to manage the master user password with AWS Secrets Manager.

Choices:

  • false

  • true

master_user_password

string

The password for the master user.

master_user_secret

dictionary

Contains the secret managed by RDS in AWS Secrets Manager for the master user password.

kms_key_id

string

The AWS KMS key identifier that is used to encrypt the secret.

master_username

string

The master user name for the DB instance.

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, between points when Enhanced Monitoring metrics are collected for the DB instance.

To disable collecting Enhanced Monitoring metrics, specify 0.

The default is 0.

Default: 0

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

Specifies whether the database instance is a multiple Availability Zone deployment.

Choices:

  • false

  • true

nchar_character_set_name

string

The name of the NCHAR character set for the Oracle DB instance.

This parameter doesnt apply to RDS Custom.

network_type

string

The network type of the DB cluster.

option_group_name

string

Indicates that the DB instance should be associated with the specified option group.

performance_insights_kms_key_id

string

The AWS KMS key identifier for encryption of Performance Insights data.

The KMS key ID is the Amazon Resource Name (ARN), KMS key identifier, or the KMS key alias for the KMS encryption key.

performance_insights_retention_period

integer

The amount of time, in days, to retain Performance Insights data.

Valid values are 7 or 731 (2 years).

preferred_backup_window

string

The daily time range during which automated backups are created if automated backups are enabled, using the BackupRetentionPeriod parameter.

preferred_maintenance_window

string

he weekly time range during which system maintenance can occur, in Universal Coordinated Time (UTC).

processor_features

list / elements=dictionary

The number of CPU cores and the number of threads per core for the DB instance class of the DB instance.

name

string

The name of the processor feature.

Valid names are coreCount and threadsPerCore.

Choices:

  • "coreCount"

  • "threadsPerCore"

value

string

The value of a processor feature name.

profile

aliases: aws_profile

string

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 AWS_PROFILE environment variable may also be used.

The profile option is mutually exclusive with the aws_access_key, aws_secret_key and security_token options.

promotion_tier

integer

A value that specifies the order in which an Aurora Replica is promoted to the primary instance after a failure of the existing primary instance.

Default: 1

publicly_accessible

boolean

Indicates whether the DB instance is an internet-facing instance.

If you specify true, AWS CloudFormation creates an instance with a publicly resolvable DNS name, which resolves to a public IP address.

If you specify false, AWS CloudFormation creates an internal instance with a DNS name that resolves to a private IP address.

Choices:

  • false

  • true

purge_tags

boolean

Remove tags not listed in tags.

Choices:

  • false

  • true ← (default)

region

aliases: aws_region, ec2_region

string

The AWS region to use.

For global services such as IAM, Route53 and CloudFront, region is ignored.

The AWS_REGION or EC2_REGION environment variables may also be used.

See the Amazon AWS documentation for more information http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region.

The ec2_region alias has been deprecated and will be removed in a release after 2024-12-01

Support for the EC2_REGION environment variable has been deprecated and will be removed in a release after 2024-12-01.

replica_mode

string

The open mode of an Oracle read replica.

The default is open-read-only.

restore_time

string

The date and time to restore from.

secret_key

aliases: aws_secret_access_key, aws_secret_key, ec2_secret_key

string

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 AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variables may also be used in decreasing order of preference.

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 EC2_SECRET_KEY environment variable has been deprecated and will be removed in a release after 2024-12-01.

session_token

aliases: aws_session_token, security_token, aws_security_token, access_token

string

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 AWS_SESSION_TOKEN, AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variables may also be used in decreasing order of preference.

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 EC2_SECRET_KEY and AWS_SECURITY_TOKEN environment variables has been deprecated and will be removed in a release after 2024-12-01.

source_db_instance_automated_backups_arn

string

The Amazon Resource Name (ARN) of the replicated automated backups from which to restore.

source_db_instance_identifier

string

If you want to create a Read Replica DB instance, specify the ID of the source DB instance.

Each DB instance can have a limited number of Read Replicas.

source_dbi_resource_id

string

The resource ID of the source DB instance from which to restore.

source_region

string

The ID of the region that contains the source DB instance for the Read Replica.

state

string

Goal state for resource.

state=present creates the resource if it doesn’t exist, or updates to the provided state if the resource already exists.

state=absent ensures an existing instance is deleted.

state=list get all the existing resources.

state=describe or state=get retrieves information on an existing resource.

Choices:

  • "present" ← (default)

  • "absent"

  • "list"

  • "describe"

  • "get"

storage_encrypted

boolean

A value that indicates whether the DB instance is encrypted.

By default, it isnt encrypted.

Choices:

  • false

  • true

storage_throughput

integer

Specifies the storage throughput for the DB instance.

storage_type

string

Specifies the storage type to be associated with the DB instance.

tags

aliases: resource_tags

dictionary

A dict of tags to apply to the resource.

To remove all tags set tags={} and purge_tags=true.

tde_credential_arn

string

The ARN from the key store with which to associate the instance for TDE encryption.

tde_credential_password

string

The password for the given ARN from the key store in order to access the device.

timezone

string

The time zone of the DB instance.

The time zone parameter is currently supported only by Microsoft SQL Server.

use_default_processor_features

boolean

A value that indicates whether the DB instance class of the DB instance uses its default processor features.

Choices:

  • false

  • true

use_latest_restorable_time

boolean

A value that indicates whether the DB instance is restored from the latest backup time.

By default, the DB instance isnt restored from the latest backup time.

Choices:

  • false

  • true

validate_certs

boolean

When set to false, SSL certificates will not be validated for communication with the AWS APIs.

Setting validate_certs=false is strongly discouraged, as an alternative, consider setting aws_ca_bundle instead.

Choices:

  • false

  • true ← (default)

vpc_security_groups

list / elements=string

A list of the VPC security group IDs to assign to the DB instance.

The list can include both the physical IDs of existing VPC security groups and references to AWS::EC2::SecurityGroup resources created in the template.

wait

boolean

Wait for operation to complete before returning.

Choices:

  • false ← (default)

  • true

wait_timeout

integer

How many seconds to wait for an operation to complete before timing out.

Default: 320

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

Return Values

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

Key

Description

result

complex

When state=list, it is a list containing dictionaries of resource information.

Otherwise, it is a dictionary of resource information.

When state=absent, it is an empty dictionary.

Returned: always

identifier

string

The unique identifier of the resource.

Returned: success

properties

dictionary

The resource properties.

Returned: success

Authors

  • Ansible Cloud Team (@ansible-collections)