/terraform-intel-aws-postgresql

Intel Cloud Optimization Module - AWS RDS PostgreSQL

Primary LanguageHCLApache License 2.0Apache-2.0

Intel Logo

Intel® Optimized Cloud Modules for Terraform

© Copyright 2024, Intel Corporation

AWS RDS PostgreSQL module

This module can be used to deploy an Intel optimized Amazon RDS PostgreSQL Server database instance. Instance selection and PostgreSQL optimization are included by default in the code.

The PostgreSQL Optimizations were based off Intel Xeon Tuning guides

Performance Data

Handle up to 1.54x more PostgreSQL queries/second using AWS m6i instances featuring 3rd Generation Intel® Xeon® Scalable Processor (Ice Lake)

Link

Process up to 1.43x more PostgreSQL transactions on AWS m6i instances featuring 3rd Generation Intel® Xeon® Scalable Processor (Ice Lake) vs. previous generation

Link

Achieve up to 1.24x better PostgreSQL performance by choosing AWS m6i instances featuring 3rd Generation Intel® Xeon® Scalable Processor (Ice Lake)

Link

Usage

See examples folder for complete examples.

By default, you will only have to pass three variables

db_password
rds_identifier
vpc_id

variables.tf

variable "db_password" {
  description = "Password for the master database user."
  type        = string
  sensitive   = true
}

main.tf

module "optimized-postgresql-server" {
  source         = "intel/aws-postgresql/intel"
  db_password    = var.db_password
  rds_identifier = "<NAME-FOR-RDS-INSTANCE>"
  vpc_id         = "<YOUR-VPC-ID>"
}

Run Terraform

export TF_VAR_db_password ='<USE_A_STRONG_PASSWORD>'

terraform init  
terraform plan
terraform apply

Note that this example may create resources. Run terraform destroy when you don't need these resources.

Considerations

  • Check in the variables.tf file for the region where this database instance will be created. For using any other AWS region, make changes accordingly within the Terraform code

  • Check if you getting errors while running this Terraform code due to AWS defined soft limits or hard limits within your AWS account. Please work with your AWS support team to resolve limit constraints

  • Using HashiCorp Modules alongside green-blue deployment allows for a secure and efficient deployment process. The modules can be easily integrated into both the active and inactive environments, ensuring consistency across both environments.

    • Instance - If you apply the instances will shut down immediately and restart, creating service interruption.
    • Platform - If you apply, it will wait for the next maintenance window to change the instance & configuration. You can force apply with additional TF code.

Requirements

Name Version
terraform >=1.3.0
aws ~> 5.31
random ~>3.4.3

Providers

Name Version
aws ~> 5.31
random ~>3.4.3

Modules

No modules.

Resources

Name Type
aws_db_instance.rds resource
aws_db_parameter_group.rds resource
aws_db_subnet_group.rds resource
aws_security_group.rds resource
random_id.rid resource
aws_subnets.vpc_subnets data source

Inputs

Name Description Type Default Required
auto_major_version_upgrades Flag that specifices if major version upgrades are allowed. Changing this parameter does not result in an outage and the change is asynchronously applied as soon as possible. bool false no
auto_minor_version_upgrades Flag that specifies if minor engine upgrades will be applied automatically to the DB instance during the maintenance window. bool true no
availability_zone Availability zone where the RDS instance will be instantiated. string null no
aws_security_group_name security group name for the rds string "postgresql_rds" no
create_security_group Flag that allows for the creation of a security group that allows access to the instance. Please use this for non-production use cases only. bool false no
create_subnet_group Flag that allows for the creation of a subnet group that allows public access. bool false no
db_allocated_storage Allocated storage for AWS database instance. number 200 no
db_apply_immediately Flag that specifies whether any database modifications are applied immediately, or during the next maintenance window. bool false no
db_automated_backup_arn The ARN of the automated backup from which to restore. Required if source_db_instance_identifier or source_dbi_resource_id is not specified. string null no
db_backup_retention_period The days to retain backups for. Must be between 0 and 35. Must be greater than 0 if the database is used as a source for a Read Replica. number 7 no
db_backup_window The daily time range (in UTC) during which automated backups are created if they are enabled. Example: 09:46-10:16. Must not overlap with maintenance_window. string null no
db_ca_cert_identifier The identifier of the CA certificate for the DB instance. string null no
db_cloudwatch_logs_export Set of log types to enable for exporting to CloudWatch logs. If omitted, no logs will be exported. list(string) [] no
db_custom_iam_profile (The instance profile associated with the underlying Amazon EC2 instance of an RDS Custom DB instance. string null no
db_deletion_protection Flag that specifies whether the DB instance is protected from deletion. bool false no
db_domain The ID of the Directory Service Active Directory domain to create the instance in. string null no
db_domain_iam_role (Required if db_domain is provided) The name of the IAM role to be used when making API calls to the Directory Service. string null no
db_encryption Flag that specifies whether the DB instance is encrypted. bool true no
db_engine Database engine version for AWS database instance. string "postgres" no
db_engine_version Database engine version for AWS database instance. string "14.5" no
db_iam_authentication Flag that specifies whether mappings of AWS Identity and Access Management (IAM) accounts to database accounts is enabled. bool false no
db_iops The amount of provisioned IOPS. Setting this implies a storage_type of io1. number 10000 no
db_maintenance_window The window to perform maintenance in. Syntax: ddd:hh24:mi-ddd:hh24:mi string null no
db_max_allocated_storage When configured, the upper limit to which Amazon RDS can automatically scale the storage of the DB instance. Configuring this will automatically ignore differences to allocated_storage. Must be greater than or equal to allocated_storage or 0 to disable Storage Autoscaling. number 10000 no
db_monitoring_interval The interval, in seconds, between points when Enhanced Monitoring metrics are collected for the DB instance string 0 no
db_monitoring_role_arn The ARN for the IAM role that permits RDS to send enhanced monitoring metrics to CloudWatch Logs string null no
db_name Name of the database that will be created on the RDS instance. If this is specified then a database will be created as a part of the instance provisioning process. string null no
db_option_group Option group name to associate with the database instance. string null no
db_parameter_group_family Family identifier for the RDS database parameter group. string "postgres14" no
db_parameter_group_name Name for the RDS database parameter group. string "postgresql" no
db_parameters Intel Cloud optimizations for Xeon processors 
object({
    postgres = optional(object({
      temp_buffers = optional(object({
        value        = optional(string, 4096 * 1024 / 8)
        apply_method = optional(string, "immediate")
      }))
      work_mem = optional(object({
        value        = optional(string, 4096 * 1024)
        apply_method = optional(string, "immediate")
      }))
      maintenance_work_mem = optional(object({
        value        = optional(string, 512 * 1024)
        apply_method = optional(string, "immediate")
      }))
      autovacuum_work_mem = optional(object({
        value        = optional(string, "-1")
        apply_method = optional(string, "immediate")
      }))
      max_stack_depth = optional(object({
        value        = optional(string, 7 * 1024)
        apply_method = optional(string, "immediate")
      }))
      effective_io_concurrency = optional(object({
        value        = optional(string, "32")
        apply_method = optional(string, "immediate")
      }))
      synchronous_commit = optional(object({
        value        = optional(string, "off")
        apply_method = optional(string, "immediate")
      }))
      min_wal_size = optional(object({
        value        = optional(string, "256")
        apply_method = optional(string, "immediate")
      }))
      max_wal_size = optional(object({
        value        = optional(string, "49152")
        apply_method = optional(string, "immediate")
      }))
      checkpoint_warning = optional(object({
        value        = optional(string, 1 * 60 * 60)
        apply_method = optional(string, "immediate")
      }))
      random_page_cost = optional(object({
        value        = optional(string, "1.1")
        apply_method = optional(string, "immediate")
      }))
      cpu_tuple_cost = optional(object({
        value        = optional(string, "0.03")
        apply_method = optional(string, "immediate")
      }))
      effective_cache_size = optional(object({
        value        = optional(string, 350 * 1024 * 1024 / 8)
        apply_method = optional(string, "immediate")
      }))
      autovacuum = optional(object({
        value        = optional(string, "1")
        apply_method = optional(string, "immediate")
      }))
      autovacuum_vacuum_cost_limit = optional(object({
        value        = optional(string, "3000")
        apply_method = optional(string, "immediate")
      }))
      vacuum_freeze_min_age = optional(object({
        value        = optional(string, "10000000")
        apply_method = optional(string, "immediate")
      }))
      max_connections = optional(object({
        value        = optional(string, "256")
        apply_method = optional(string, "pending-reboot")
      }))
      huge_pages = optional(object({
        value        = optional(string, "on")
        apply_method = optional(string, "pending-reboot")
      }))
      shared_buffers = optional(object({
        value        = optional(string, "{DBInstanceClassMemory/32768}")
        apply_method = optional(string, "pending-reboot")
      }))
      max_files_per_process = optional(object({
        value        = optional(string, "4000")
        apply_method = optional(string, "pending-reboot")
      }))
      max_worker_processes = optional(object({
        value        = optional(string, "{DBInstanceVCPU}")
        apply_method = optional(string, "pending-reboot")
      }))
      wal_buffers = optional(object({
        value        = optional(string, "-1")
        apply_method = optional(string, "pending-reboot")
      }))
      max_wal_senders = optional(object({
        value        = optional(string, "5")
        apply_method = optional(string, "pending-reboot")
      }))
      timezone = optional(object({
        value        = optional(string, "UTC")
        apply_method = optional(string, "pending-reboot")
      }))
      max_locks_per_transaction = optional(object({
        value        = optional(string, "64")
        apply_method = optional(string, "pending-reboot")
      }))
      max_pred_locks_per_transaction = optional(object({
        value        = optional(string, "64")
        apply_method = optional(string, "pending-reboot")
      }))
      checkpoint_completion_target = optional(object({
        value        = optional(string, "0.9")
        apply_method = optional(string, "pending-reboot")
      }))
      autovacuum_max_workers = optional(object({
        value        = optional(string, "10")
        apply_method = optional(string, "pending-reboot")
      }))
      autovacuum_freeze_max_age = optional(object({
        value        = optional(string, "750000000")
        apply_method = optional(string, "pending-reboot")
      }))
    }))
  })
 
{
  "postgres": {
    "autovacuum": {},
    "autovacuum_freeze_max_age": {},
    "autovacuum_max_workers": {},
    "autovacuum_vacuum_cost_limit": {},
    "autovacuum_work_mem": {},
    "checkpoint_completion_target": {},
    "checkpoint_warning": {},
    "cpu_tuple_cost": {},
    "effective_cache_size": {},
    "effective_io_concurrency": {},
    "huge_pages": {},
    "maintenance_work_mem": {},
    "max_connections": {},
    "max_files_per_process": {},
    "max_locks_per_transaction": {},
    "max_pred_locks_per_transaction": {},
    "max_stack_depth": {},
    "max_wal_senders": {},
    "max_wal_size": {},
    "max_worker_processes": {},
    "min_wal_size": {},
    "random_page_cost": {},
    "shared_buffers": {},
    "synchronous_commit": {},
    "temp_buffers": {},
    "timezone": {},
    "vacuum_freeze_min_age": {},
    "wal_buffers": {},
    "work_mem": {}
  }
}
 no
db_password Password for the master database user. string n/a yes
db_performance_insights Flag that specifies whether Performance Insights are enabled. bool false no
db_performance_insights_kms_key_id The ARN for the KMS key to encrypt Performance Insights data. string null no
db_performance_retention_period Amount of time in days to retain Performance Insights data.Valid values are 7, 731 (2 years) or a multiple of 31. string null no
db_port The port on which the DB accepts connections. number null no
db_publicly_accessible Flag to indicate whether the database will be publicly accessible. bool false no
db_replicate_source_db Specifies that this resource is a Replicate database, and to use this value as the source database. This correlates to the identifier of another Amazon RDS Database to replicate (if replicating within a single region) or ARN of the Amazon RDS Database to replicate (if replicating cross-region). Note that if you are creating a cross-region replica of an encrypted database you will also need to specify a kms_key_id. string null no
db_restore_time The date and time to restore from. Value must be a time in Universal Coordinated Time (UTC) format and must be before the latest restorable time for the DB instance. string null no
db_snapshot_identifier Specifies whether or not to create this database from a snapshot. This correlates to the snapshot ID you'd find in the RDS console. string null no
db_source_db_instance_id The identifier of the source DB instance from which to restore. Must match the identifier of an existing DB instance. Required if source_db_instance_automated_backups_arn or source_dbi_resource_id is not specified. string null no
db_source_dbi_resource_id The resource ID of the source DB instance from which to restore. Required if source_db_instance_identifier or source_db_instance_automated_backups_arn is not specified. string null no
db_storage_type The storage type that will be set on the instance. If db_iops is set then this will be set to io1 string "io1" no
db_subnet_group_name Database subnet group name. string "postgresql" no
db_subnet_group_tag Tag for the database subnet group. map(string) 
{
  "Name": "postgresql"
}
 no
db_tags Map of tags to apply to the database instance. map(string) null no
db_timeouts Map of timeouts that can be adjusted when executing the module. This allows you to customize how long certain operations are allowed to take before being considered to have failed. 
object({
    create = optional(string, null)
    delete = optional(string, null)
    update = optional(string, null)
  })
 
{
  "db_timeouts": {}
}
 no
db_use_latest_restore_time Flag that indicates whether the DB instance is restored from the latest backup time. bool null no
db_username Username for the master database user. string null no
egress_cidr_blocks Egress CIDR block for the RDS security group. list(string) 
[
  "0.0.0.0/0"
]
 no
egress_from_port Starting egress port for the RDS security group. number 5432 no
egress_protocol Egress protocol for the port defined in the RDS security group. string "tcp" no
egress_to_port Ending egress port for the RDS security group. number 5432 no
final_snapshot_prefix The name which is prefixed to the final snapshot on database termination. string "pgsql-snap-" no
ingress_cidr_blocks Ingress CIDR block for the RDS security group. list(string) 
[
  "136.52.34.145/32"
]
 no
ingress_from_port Starting ingress port for the RDS security group. number 5432 no
ingress_protocol Ingress protocol for the port defined in the RDS security group. string "tcp" no
ingress_to_port Ending ingress port for the RDS security group. number 5432 no
instance_class Instance class that will be used by the RDS instance. string "db.m6i.2xlarge" no
kms_key_id The ARN for the KMS encryption key. If creating an encrypted replica, set this to the destination KMS ARN. string null no
multi_az Flag that specifies if the RDS instance is multi_az. bool true no
rds_identifier Name of the RDS instance that will be created. string n/a yes
rds_security_group_tag Map of tags for the RDS security group. map(string) 
{
  "Name": "postgresql_rds"
}
 no
security_group_ids List of existing AWS security groups that will be attached to the RDS instance. list(string) null no
skip_final_snapshot Flag to indicate whether a final snapshot will be skipped upon database termination. bool false no
vpc_id VPC ID within which the database resource will be created. string n/a yes

Outputs

Name Description
db_allocated_storage Storage that was allocated to the instance when it configured.
db_arn ARN of the database instance.
db_automated_backup_arn The ARN of the automated backup from which to restore.
db_backup_retention Number of configured backups to keep for the database instance.
db_backup_window Configured backup window for the database instance.
db_ca_cert_identifier The identifier of the CA certificate for the DB instance.
db_custom_iam_profile The instance profile associated with the underlying Amazon EC2 instance of an RDS Custom DB instance.
db_delete_automated_backups Flag that specifies if automated backups are deleted.
db_domain_iam_role The name of the IAM role to be used when making API calls to the Directory Service.
db_encryption Flag that indicates if storage encryption is enabled.
db_endpoint Connection endpoint for the database instance that has been created.
db_engine Database instance engine that was configured.
db_engine_version_actual Running engine version of the database (full version number)
db_final_snapshot_identifier Final snapshot identifier for the database instance.
db_hosted_zone_id Hosted zone ID for the database instance.
db_hostname Database instance hostname.
db_iam_auth_enabled Flag that specifies if iam authenticaiton is enabled on the database
db_instance_id RDS instance ID.
db_iops Database instance iops that was configured.
db_kms_key_id KMS key that is configured on the database instance if storage encryption is enabled.
db_latest_restore_time Latest available restorable time for the database instance.
db_maintenance_window Maintainence window for the database instance.
db_max_allocated_storage Maximum storage allocation that is configured on the database instance.
db_monitoring_interval Monitoring interval configuration.
db_name Name of the database that was created (if specified) during instance creation.
db_parameter_group Parameter group that was created
db_password Database instance master password.
db_performance_insights Flag that indiciates if Performance Insights is enabled.
db_performance_insights_kms_key_id ARN of the KMS key that Performance Insights is utilizing (if enabled).
db_performance_insights_retention_period Data retention period for Performance Insights (if enabled).
db_port Database instance port.
db_restore_time The date and time to restore from.
db_security_group Security Group that was created (if specified) during the run.
db_security_group_ids Security Group IDs that were associated with the database instance.
db_source_db_instance_id The identifier of the source DB instance from which to restore.
db_source_dbi_resource_id The resource ID of the source DB instance from which to restore.
db_status Status of the database instance that was created.
db_storage_type Storage type that is configured on the database instance.
db_subnet_group Name of the subnet group that is associated with the database instance.
db_username Database instance master username.
instance_class Instance class in use for the database instance that was created.