# terraform-rds

## Overview

This module provides functionality to create RDS Aurora clusters. Consult the test directory for working examples.

> [!WARNING]
> Breaking changes! Starting with version 7.0.0, the Route 53 zone ID is automatically selected based on the environment.
> The `route53_zone_id` variable has been removed. See [Route 53 Records](#route-53-records) for more information.

> [!WARNING]
> Breaking changes! Starting with version 6.0.0, the module has been refactored to use a second provider for DNS record creation. See [Providers](#providers) for more information.

> [!WARNING]
> Breaking changes! Starting with version 5.0.0, we enforce the use of Graviton instances for Aurora clusters.

> [!WARNING]
> Breaking changes! Starting with version 4.0.0, vpc_id and route53_zone_id are now required variables. This change was made to ensure that the module can be used in a multi-account setup. Dropped support for provisioning a replica cluster and removed all associated variables.

> [!WARNING]
> Breaking changes! Starting with version 3.0.0, we changed the default value for `custom_kms_key_enabled` from false to true. This means that new clusters will be created with a customer-managed KMS key. To prevent accidental cluster recreation, we have updated the value of `custom_kms_key_enabled` in all existing configurations. If you have a cluster in the QA environment created with the older version of the module and need to create a new cluster in production with the new version, please ensure you set `custom_kms_key_enabled` to false.

## Workflow

### Cluster Mode

This module supports the following Aurora cluster modes:
* Provisioned (traditional)
* Parallel Query
* Serverless

Select one by setting the following variables to match your desired mode: 

```
  rds_engine
  rds_engine_version
  rds_engine_mode
```

### Variables

Irrespective of mode or cluster-specific settings, there are three variables that must be provided for the module to function properly:
```
* environment
* service_name
* vpc_id
```

#### Route 53 Records

The module manages Route 53 records for the cluster by default. This can be disabled by setting the `route53_record_creation_enabled` variable to false.

The Route 53 Zone ID is automatically selected based on the environment. If `environment` is dev, the zone ID defaults to that of the `dev.theorchard.io` domain. Otherwise, the zone ID defaults to that of the `theorchard.io` domain.

If you require a different zone to the default selection, you can specify it using the `override_route53_zone_id` variable instead.

The Route 53 records are created in the AWS account specified by the `dns` provider. See [Providers](#providers) for more information.

### Subnet Groups

One of `rds_db_subnet_ids` or `rds_db_subnet_group_name` must be set. Use of `rds_db_subnet_ids` is preferred, and will result in the creation of a dedicated subnet group for the cluster, while `rds_db_subnet_group_name` can be used to specify a pre-existing subnet group.

> [!WARNING]
> Switching between the use of `rds_db_subnet_ids` and `rds_db_subnet_group_name` will result in the cluster being recreated.

#### Cloudwatch Log Exports

Variable that sets which type of logs will be sent to CloudWatch.
```
enabled_cloudwatch_logs_exports
```
For PostgreSQL only avaliable option is:
```
["postgresql"]
```
For others DB engines, like MySQL you can pick required ones:
```
["audit", "error", "general", "slowquery"]
```

#### Instance Classes

We support only certain instance classes. The following variable should be set to one of the supported values:
```
* rds_cluster_instance_class
```

#### Other Variables

**Note:** Supported values are listed in the variable definition file.

Consult the variable definition file for additional options, which can be optionally overridden.

### Resources

#### The module manages the following: 

* RDS clusters
* RDS event subscriptions
* SNS topics for RDS event subscriptions
* RDS proxy
* Route53 record for the cluster
* KMS key for the cluster

#### The module also manages the following unless configured to use pre-existing resources:

* Parameter groups
* Subnet groups

#### The module does not manage the following: 

* IAM roles associated with the cluster

This module assumes these resources already exist and can be specified in variables. While it is expected that most use cases can use pre-existing groups, since these are input variables, you could conceivably create new ones via Terraform and pass them in as well.

> [!IMPORTANT]
> The module does not manage the IAM roles associated with the cluster. You will need to create these roles manually and attach the necessary policies. It's important to follow the naming convention for the roles. The role name should be in the format `${var.environment}-${var.service_name}-s3-upload-role`.

#### Sensitive Values

As noted in the variable definition file, `master_username` and `master_password` should not be specified in files under version control. As such, apply this module following one of the approaches listed [here](https://www.terraform.io/intro/getting-started/variables.html), e.g.
```
terraform apply \
-var rds_master_username=master_username \
-var rds_master_password=password123
```

### Providers

The module requires an explicitly defined second AWS provider which specifies where Route 53 records will be created.

If you are creating Route 53 records in the same account as the RDS cluster (e.g. in dev), you can simply alias the default provider as `dns` as follows:

```hcl
provider "aws" {
  region  = var.aws_region
}

module "database" {
  source = "git@github.com:theorchard/terraform-rds.git//?ref=x.x.x"

  providers = {
    aws.dns = aws
  }

  // other settings
}
```

If you are creating Route 53 records in a different account to the RDS cluster (e.g. `theorchard.io`), you will need to define a second provider with the appropriate credentials:

```hcl
provider "aws" {
  region  = var.aws_region
}

provider "aws" {
  region  = var.aws_region
  alias   = "networking"
  profile = "networking"
}

module "database" {
  source = "git@github.com:theorchard/terraform-rds.git//?ref=x.x.x"

  providers = {
    aws.dns = aws.networking
  }
  
  // other settings
}
```

### Notes

Every engine mode is not supported across all engines and versions. For more information, check https://aws.amazon.com/rds/aurora/faqs/ or run `aws rds describe-db-engine-versions` to check compatibility.