AWS Database Blog

Automate the deployment of Amazon RDS for Db2 Instances with Terraform

Amazon Relational Database Service (Amazon RDS) for Db2 makes it easy to set up, operate, and scale Db2 deployments in the cloud. IBM Db2 is a relational database that supports large-scale transactional and analytical workloads. Amazon RDS manages time-consuming database administration tasks, such as provisioning, patching, backups, recovery, failure detection, and repair, so you can focus on applications and running your business. It also offers high availability through Multi-AZ deployment, disaster recovery solutions with cross-Region automated backups, and security features to support your business-critical workloads. In addition, you can integrate with other AWS or IBM services, such as a data warehouse, to scale your analytics and artificial intelligence and machine learning (AI/ML) workloads.

Infrastructure as Code (IaC) is the practice of provisioning and managing your computing infrastructure using code, rather than manual processes and settings. Managing infrastructure manually is time-consuming and prone to errors, especially at scale. IaC automates this process, allowing developers to define and maintain the desired state of their infrastructure efficiently. This reduces costs, minimizes risks, and enables the use of version control for infrastructure configurations.

Popular IaC tools, services, and platforms include Terraform, AWS CloudFormation, Ansible, and Pulumi, each offering unique features to automate and manage infrastructure across various cloud environments. In this post, we demonstrate how Terraform, one of our partner products, can be used to deploy and manage RDS for Db2 instance.

Terraform by HashiCorp allows you to define and provision infrastructure resources using HashiCorp Configuration Language (HCL), a declarative language. Terraform’s key strengths include version control integration, state management, and automatic handling of resource dependencies.

We recommend that you have a working understanding of both Terraform and Amazon RDS for Db2 before diving into this post. For more information on Terraform, visit the Introduction to Terraform on AWS workshop. For more details on RDS for Db2, refer to AWS documentation.

Overview of solution

In this post, we provide a sample set of Terraform configuration file and highlight key properties to consider, such as IBM Db2 version, database parameters, access control, data security, and monitoring features. Terraform simplifies and automates the provisioning of an RDS for Db2 instance and makes the process repeatable. In the following sections, we guide you through provisioning an RDS for Db2 instance with Terraform.

Overview of Amazon RDS for Db2

Before we begin deploying Amazon RDS for Db2 with Terraform, let’s review in detail some important deployment options and parameters that we’ll use in the Terraform configuration file.

Engine options

In the Terraform configuration file, you need to specify the database engine type using the engine argument for the RDS DB instance you want to deploy. RDS for Db2 supports DB instances running the Db2 Standard Edition and Db2 Advanced Edition of the IBM Db2 database. For RDS for Db2, the allowed values for the engine argument are db2-ae for Db2 Advanced Edition and db2-se for Db2 Standard Edition.

For details on IBM Db2 engines refer to Db2 database product editions and Db2 offerings.

Licensing options

Amazon RDS for Db2 offers two licensing options: Bring Your Own License (BYOL) and Db2 licensing through AWS Marketplace. In the BYOL model, you provide your IBM Customer ID and Site ID for IBM to track your license entitlements. As a customer, you work with IBM directly to manage your licenses. In the AWS Marketplace model, you can obtain an hourly-based license for IBM Db2 Standard or Advanced edition directly from AWS, allowing you to get started quickly without needing to purchase licenses.

If using BYOL model, you must create a custom parameter group and enter your IBM Customer ID and Site ID. We discuss custom parameter group later in this post. Additionally, you must integrate the RDS for Db2 instance with AWS License Manager to monitor license usage. Refer to Integrating with AWS License Manager for more information.

In the Terraform configuration file, you need to specify the licensing model using the license_model argument, with accepted values being bring-your-own-license and marketplace-license for the RDS for Db2 instance you want to deploy.

Db2 versions

The Db2 version has the format major.minor.build.revision.

Refer to Db2 on Amazon RDS versions for details on version nomenclature and AWS CLI commands to find the available versions.

For example, to list the supported engine versions for Amazon RDS for Db2 in the US East (N. Virginia) AWS Region, run the following AWS CLI command:

aws rds describe-db-engine-versions \
--filters Name=engine,Values=db2-ae,db2-se \
--query "DBEngineVersions[].{Engine:Engine,EngineVersion:EngineVersion }" \
--region us-east-1

You can specify any currently supported Db2 version using the engine_version argument in the Terraform configuration file, and the accepted values of the argument are the list of supported engine versions from the preceding AWS CLI command. As a best practice, we suggest using the latest available version.

DB instance settings

Instance Identifier

The DB instance identifier is a unique name that you provide when creating an RDS for Db2 DB instance. It serves as a way to identify and reference your specific Db2 instance when interacting with the Amazon RDS API, AWS CLI commands, or the AWS Management Console. You can specify the RDS for Db2 instance identifier using the identifier argument in the Terraform configuration file. For more information about DB instances, see Amazon RDS DB instances.

Credential settings

The master user in Amazon RDS for DB2 is a special user account that is created automatically when you provision a new Db2 DB instance. This user has administrative privileges and can be used to perform various database management tasks. The master user is granted the database administrator authority, which allows you to perform administrative tasks such as creating additional database accounts, granting privileges, and managing database objects. As a best practice, it’s recommended to create additional user accounts with appropriate privileges for different application roles and not use the master user for regular application access. The master user name is provided using the username argument. For more information about roles, see Amazon RDS for Db2 default roles.

Securing the master user credentials is important. You can choose from two options: AWS Secrets Manager (the most secure option) or self-managed (specify your own password or have Amazon RDS generate a password for you). We recommend using Amazon RDS to generate and manage the master user password in Secrets Manager. To enable this feature, use the Terraform argument manage_master_user_password. Amazon RDS encrypts the secret with the default Secrets Manager key; however, you can use a customer managed key by providing it in the master_user_secret_kms_key_id argument. For more information about credentials management, see Password management with Amazon RDS and AWS Secrets Manager.

DB instance configuration

DB Instance Class

The computation and memory capacity of a DB instance is determined by its instance class. The DB instance class you need depends on your processing power and memory requirements. Amazon RDS for Db2 supports various instance classes to support a wide variety of database workloads. For more details, refer to Supported RDS for Db2 instance classes. You can specify the instance class using the instance_class argument in the Terraform configuration file.

Storage options

Amazon RDS for Db2 supports Provisioned IOPS SSD storage (io2 Block Express, io1 storage) and General Purpose SSD (gp3) storage types. For more details, refer to Amazon RDS DB instance storage.

You can specify storage type, size, and IOPS using the storage_type, allocated_storage, and iops Terraform arguments. Furthermore, as a best practice, we recommend using Amazon RDS storage auto scaling if your workload is unpredictable and log retention is set. This feature can be enabled by using the max_allocated_storage argument in Terraform.

Availability and durability

Amazon RDS for Db2 offers Multi-AZ deployment with one standby in a different Availability Zone but in the same Region as your primary database. It uses synchronous storage replication to keep data in your standby database up to date. In the event of a failure, the primary database automatically fails over to the standby database with zero data loss and automatic update to the DNS record to point to the multi-az second instance in as little as 60 seconds. You can configure Multi-AZ by using the multi_az argument in Terraform. Multi-AZ is recommended for production deployments.

Connectivity

Amazon Virtual Private Cloud (Amazon VPC) enables you to launch AWS resources, including RDS instances, into a customizable virtual network. With VPC, you have fine-grained control over your virtual networking environment, allowing you to specify your IP address range, create subnets, and configure routing, security groups, and access controls lists. For more details, see Amazon VPC and Amazon RDS.

A DB subnet group is a collection of subnets that you designate for your RDS database instances within a VPC. To ensure high availability, a DB subnet group must include subnets in at least two Availability Zones in a Region. The subnets in a DB subnet group can be either public or private, depending on their routing table configuration. For security reasons, the subnets in a DB subnet group are typically private; for more details, refer to Hiding a DB instance in a VPC from the internet. You can configure a DB subnet group by using the db_subnet_group_name argument. Within the DB subnet group, Amazon RDS selects a subnet and assigns an IP address from that subnet to the DB instance. You also have the option to specify the desired Availability Zone for the primary DB instance using the availability_zone argument. The chosen Availability Zone must be part of the DB subnet group. For more information about using DB instances with VPCs, see Working with a DB instance in a VPC.

You can manage the public accessibility of your RDS for Db2 instance using the publicly_accessible argument in Terraform. As a best practice, we recommend setting it to false to prevent internet access. This setting controls only internet accessibility; regardless of whether the instance is in a public or private subnet, it can still be accessed within the VPC and a private network via AWS Site-to-Site VPN connection or an AWS Direct Connect connection.

A security group acts as a virtual firewall that controls inbound and outbound traffic to your database. To allow connectivity to the database, it’s important to add inbound rules for the DB instance’s TCPIP and SSL/TLS service ports from the relevant source IP addresses to the security group. It is strongly advised to keep these rules as restrictive as possible, granting access solely to the necessary sources, to maintain a robust security posture. To attach a security group for your RDS for Db2 instance using Terraform, use the argument vpc_security_group_ids. For more information about using security groups, see Considerations for security groups with Amazon RDS for Db2.

Database authentication

Amazon RDS for Db2 provides two options to authenticate database users: password authentication and Kerberos authentication.

With password authentication, the local database users are used for authentication. Refer to Stored procedures for granting and revoking privileges for RDS for Db2 for details on how to create local users. This is the default option.

In addition to password authentication, Amazon RDS for Db2 supports authentication of database users using Kerberos and an AWS managed Microsoft AD created with AWS Directory Service. This way, you can centrally store and manage user credentials instead of individually for each DB instance. Refer to Using Kerberos authentication for Amazon RDS for Db2 for instructions to set up Kerberos for your database. In the Terraform configuration file, you need to provide the domain and domain_iam_role_name arguments to enable Kerberos authentication.

For more information about database authentication, see Database authentication with Amazon RDS.

Monitoring

You can monitor an RDS for Db2 DB instance by using Amazon CloudWatch metrics, events, and enhanced monitoring.

CloudWatch is a metrics repository. The repository collects and processes raw data from Amazon RDS into readable, near real-time metrics. By default, Amazon RDS automatically sends metric data to CloudWatch in 1-minute periods. For example, the CPUUtilization metric records the percentage of CPU utilization for a DB instance over time. For more details, refer to Metrics reference for Amazon RDS and Viewing metrics in the Amazon RDS console.

Amazon RDS Enhanced Monitoring is a feature that allows you to get real-time metrics for the operating system of your DB instances. Amazon RDS sends these metrics to CloudWatch. To enable enhanced monitoring, you must specify an IAM role that permits Amazon RDS to send enhanced monitoring metrics to CloudWatch. In Terraform, you can create a new role using the create_monitoring_role argument or use an existing role by specifying it in the monitoring_role_arn argument.

Terraform’s monitoring_interval argument defines metrics granularity. This includes over 50 different CPU, memory, file system, and disk I/O metrics. The metrics are provided at high granularity, up to one time every 1 second, allowing you to better monitor, troubleshoot, and optimize database performance and resource usage.

Amazon CloudWatch alarms allow you to proactively monitor key performance metrics for your RDS databases and automatically receive notifications or take recovery actions when issues arise, before they potentially impact applications. You should set up CloudWatch alarms on the metrics that you deem important, such as CPU, memory, storage, and others.

Amazon RDS events notify you when your database is undergoing changes, such as a restart, backup, or configuration parameter change. The events are grouped into categories, and you can subscribe to categories that are most relevant to you.

At the time of writing this post, Performance Insights is not available on Amazon RDS for Db2. You can connect monitoring tools such as IBM Db2 Data Management Console, Datadog, DynaTrace, Solarwinds, and others to your database for monitoring.

Log exports

Amazon RDS for Db2 generates the Db2 diagnostic (db2diag) log files and the administration notification logs as diag.log and notify.log, respectively. You can access the logs from the Amazon RDS console, however we suggest publishing them to CloudWatch Logs to enable monitoring and alerting using metric filters. Use the enabled_cloudwatch_logs_exports argument to specify the logs you want to export. If enabled, Terraform uses the syntax /aws/rds/instance/<db identifier>/<filename> for the CloudWatch log groups. For example, if you used my-db2-instance as the identifier and exported diag.log, the CloudWatch log group would be /aws/rds/instance/my-db2-instance/diag.log.

In the sample Terraform configuration file, we export diag.log and notify.log to CloudWatch Logs and set up a metric filter to alert for Severe messages in diag.log. We enable Enhanced Monitoring and set up a CloudWatch alarm for high CPU usage.

Backup settings

Amazon RDS provides two types of backups for DB instances: automated backups and manual database snapshots. For more details, refer to Backing up, restoring, and exporting data. As a best practice, we recommend enabling automated backups for your RDS for Db2 databases, which provides a low-management, durable, cost-efficient, and flexible way to protect RDS databases against data loss or corruption with point-in-time recovery capabilities. You can enable Amazon RDS automated backups by using the backup_window and backup_retention_period arguments in the Terraform configuration file. Note, if backup_retention_period is set to zero, no backups will be taken and database is converted from archive to circular logging mode.

Encryption settings

Amazon RDS for Db2 offers two encryption settings: encryption at rest and encryption in transit.

Encryption at rest refers to encrypting underlying storage for DB instances, its automated backups, and snapshots using an AWS Key Management Service (AWS KMS) key. RDS for Db2 encrypted DB instances provide an additional layer of data protection by securing your data from unauthorized access to the underlying storage. The Terraform argument storage_encrypted enables data encryption at rest.

Encryption in transit involves encrypting a connection between your application client and your RDS for Db2 DB instance using SSL/TLS protocol. As a best practice, we suggest enabling both encryption at rest and encryption in transit for your RDS for Db2 instance. For more information about encryption settings, see RDS for Db2 Encryption at rest and Encryption in-transit.

By default, the Amazon RDS AWS managed key (aws/rds) is used for encryption. We suggest creating a customer managed key (CMK) for encryption within the Terraform configuration file. A CMK gives you more flexibility compared to the default key. For example, if you plan to transfer a database snapshot to another Region or account, you will encounter challenges by using the default key because it’s AWS managed and non-shareable. For more details, refer to Securing data in Amazon RDS using AWS KMS encryption.

The following steps enable encryption in transit with server identity verification for an RDS for Db2 DB instance:

  1. Assign a certificate authority (CA) to the DB instance. A CA signs the DB server certificate for your DB instance. The certificate establishes the DB server’s identity and enables encrypted connections between clients and the database. At the time of writing this post, Amazon RDS for Db2 supports two CAs: rds-ca-rsa2048-g1 (default) and rds-ca-rsa4096-g1. Choose the CA that suits your security requirements for the Terraform argument ca_cert_identifier. When you use the rds-ca-rsa2048-g1 or rds-ca-rsa4096-g1 CA, Amazon RDS manages the DB server certificate on the database. The server certificate is valid for 36 months. Both CAs support automatic rotation of DB server certificates, but Amazon RDS for Db2 requires a restart. Amazon RDS notifies you of a maintenance event at least 6 months before the DB server certificate expires.
  2. Modify the DB2COMM and SSL_SVCENAME parameters in the custom parameter group associated with the DB instance. DB2COMM set to value TCPIP,SSL allows both clear text and SSL-encrypted communication to occur at the same time between the DB instance and a Db2 client. You can set DB2COMM to SSL to allow only SSL/TLS connections. Specify the SSL port number to be used for SSL/TLS connections in the SSL_SVCENAME.
  3. To access the RDS for Db2 database over SSL/TLS with certificate verification, you need to provide a trust certificate from Amazon RDS. Refer to Download certificate bundles for Amazon RDS for guidelines to download the certificate bundle for the Region where you host your database. Depending on the tool or application being used to connect to the database, you can use the downloaded PEM or PKCS7 certificate bundle file directly or import it into a trust store. Refer to Connect to your Db2 database server for more details.

Additional configurations

Initial Database Name

The argument db_name is used to create a database at the time of RDS for Db2 instance deployment. When you enter a name for the initial database name, Amazon RDS creates a database in your RDS for Db2 DB instance. If you want to restore a backup of your Db2 on Linux database after creating the instance, don’t specify a name. In this case, Amazon RDS doesn’t create a database when it creates the DB instance. Do not specify this argument if you intend to create a database with custom options or plan to migrate a self-managed database to Amazon RDS for Db2. For more details, refer to Prerequisites for creating an Amazon RDS for Db2 DB instance and Additional considerations.

DB parameter group

Amazon RDS for Db2 uses three types of parameters: database manager configuration parameters (dbm cfg), registry variables, and database configuration (db cfg) parameters. You can manage dbm cfg parameters and registry variables through parameter groups and the db cfg parameters through the rdsadmin.update_db_param stored procedure. The parameter groups are available for each Db2 edition and the major version. At the time of writing this post, two parameter groups are available: db2-ae-11.5 and db2-se-11.5.

During the deployment of your RDS for Db2 instance, we suggest creating a custom parameter group and attaching it to the database using the argument parameter_group_name. This facilitates changing the parameters later because default parameter groups can’t be changed.

In the Terraform configuration file, the family argument defines the family of the parameter group to be used. You can use the describe-db-engine-versions AWS CLI command to find the family name for the Db2 edition and major version you will use. The following command returns the default family for db2-ae in the US East (N. Virginia) Region:

aws rds describe-db-engine-versions \
--default-only --engine db2-ae \
--query "DBEngineVersions[].{Engine:Engine, EngineVersion:EngineVersion, DBParameterGroupFamily:DBParameterGroupFamily}" \
--region us-east-1

Option group

You can enable additional features available for Amazon RDS for Db2 through option groups. For example, you can enable Db2 audit logging using an option group. Similar to parameter groups, we suggest creating a custom option group related to the database version to allow changes to options and attach it to the RDS for Db2 instance using the option_group_name Terraform argument.

Time zone

RDS for Db2 allows you to set a preferred time zone for the database at the time of DB instance creation using the timezone argument in Terraform. Refer to Local time zone for Amazon RDS for Db2 DB instance for details and a list of available time zones. The default is Coordinated Universal Time (UTC). You can’t modify the time zone of an existing RDS for Db2 DB instance.

Deletion protection

Amazon RDS deletion protection is a feature that helps prevent accidental or unauthorized deletion of your RDS instances. When deletion protection is enabled, you can’t delete the RDS instance unless you first disable the protection. This is particularly useful for safeguarding critical databases that you don’t want to lose due to human error or malicious activity. As a best practice, we recommend enabling this feature for all production RDS for Db2 instances. You can enable it by using the deletion_protection argument in the Terraform configuration file. For more details, see Deleting a DB instance.

Migration settings

Amazon RDS for Db2 enables you to read files from Amazon Simple Storage Service (Amazon S3). This feature is useful when restoring a database from a self-managed Db2 database backup or loading data files to tables in your database. In Terraform, you use the aws_db_instance_role_association resource to enable the S3_INTEGRATION feature. For more information about this integration, see Integrating an Amazon RDS for Db2 DB instance with Amazon S3. Note, an S3 Gateway Endpoint is required for secure and private connectivity between Amazon VPC and S3.

For more details on migration strategies to Amazon RDS for Db2, refer to Data migration strategies to Amazon RDS for Db2.

Deploy the RDS Db2 instance and associated resources

In this post, we deploy an RDS for Db2 instance using the best practices discussed earlier, along with the following additional resources:

  • RDS for Db2 DB instance along with Secrets Manager for master user credential management.
  • DB subnet group
  • VPC Security group
  • IAM role to set up Enhanced Monitoring.
  • Parameter group with IBM Db2 licensing information (for example, BYOL model with dummy IBM Customer ID and IBM Site ID).
  • Option group.
  • KMS key with a policy used for encryption at rest and secrets encryption.
  • IAM policy with IAM role for Amazon S3 integration with RDS for Db2.
  • Amazon Simple Notification Service (Amazon SNS) topic for Amazon RDS event monitoring and alerting.
  • RDS for Db2 event subscriptions.
  • CloudWatch alarm for high CPU usage.
  • CloudWatch alarm for Level: Severe messages in log.

Prerequisites

This post assumes that you’re familiar with Terraform, GitHub, and Git commands.

For deployment, you need the following:

Deployment Steps

  1. Clone the GitHub repo to your workstation by running the following command in your terminal window: 
    git clone https://github.com/aws-samples/amazon-rds-db2-terraform.git

    This command creates a directory named amazon-rds-db2-terraform under your current directory. Your directory contains the following files:

    • main.tf – The primary configuration file that defines the infrastructure resources and settings for deployment.
    • variables.tf – The file that defines all the variables.
    • rdsdb2test.tfvars – The file that provides values for variables specific to an environment. For instance, it includes settings for deploying an RDS for Db2 test environment. Organizations often manage multiple environments, such as development, staging, and production, each with its own .tfvars file. This practice helps maintain organized and manageable configurations across different environments.
    • rdsdb2prod.tfvars – The sample file for Production environment.
    • versions.tf – The file used to specify the required Terraform and provider versions for a project.
    • outputs.tf – The Terraform configuration file used to define and output values from the Terraform configuration, typically for use by other configurations or for informational purposes.
  1. Establish temporary security credentials for the IAM user. Refer to instructions Using temporary security credentials with the AWS CLI.
  2. Modify the rdsdb2test.tfvars file based on your requirements.
  3. Run the following command in your project directory to initialize the working directory, download provider plugins, and set up the backend: 
    terraform init -var-file="rdsdb2test.tfvars"
  4. Run the following command to generate an execution plan, showing what actions Terraform will take to reach the desired state: 
    terraform plan -var-file="rdsdb2test.tfvars"
  5. Run the following command to apply the changes defined in your configuration and create or update the infrastructure: 
    terraform apply -var-file="rdsdb2test.tfvars"

During the build process, you can monitor the progress on the Amazon RDS console. In approximately 10–20 minutes, the instance will reach an Available status.

Clean up

AWS resources provisioned by Terraform for the RDS for Db2 instance will incur costs while they remain in use. If you need to tear down the infrastructure, run the following command in your project directory to remove all resources defined in your configuration:

terraform destroy -var-file="rdsdb2test.tfvars"

Conclusion

Deploying Amazon RDS for Db2 involves careful consideration of various properties to achieve a secure, efficient, and high-performing database environment. By using the provided sample Terraform configuration, you can streamline the deployment process while tailoring your configuration to meet specific business requirements.

Key aspects such as choosing the correct IBM Db2 version, setting appropriate database parameters, implementing robust access controls, securing data at rest, and enabling comprehensive database monitoring are essential for maintenance, reliability, and security of your database. By carefully planning and configuring these elements you can use the full potential of Amazon RDS to deliver a robust and scalable Db2 environment providing high availability, data integrity, and peace of mind in your production workloads.

Try out Amazon RDS for Db2 with Terraform with your own use case, and let us know your feedback and questions in the comments.

About the Authors

Divaker Goel is a Sr. Database Consultant at Amazon Web Services’ Professional Services team with over 20 years’ experience in databases. He specializes in guiding customers through their migration journey to AWS Cloud, helping them optimize and modernize their applications and databases.

Javeed Mohammed is a Sr. Database Specialist Solutions Architect with Amazon Web Services. He works with the Amazon RDS team, focusing on commercial database engines like Oracle and Db2. He enjoys working with customers to help design, deploy, and optimize relational database workloads on the AWS Cloud.