Skip to content

Commit dda4d8a

Browse files
bryantbiggsbryantbiggs
committed
chore: update migration documentation, still more to add
1 parent aac49df commit dda4d8a

File tree

2 files changed

+154
-16
lines changed

2 files changed

+154
-16
lines changed

‎UPGRADE-6.0.md

Lines changed: 152 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -11,27 +11,76 @@ If you have any questions regarding this upgrade process, please consult the `ex
1111

1212
If you find a bug, please open an issue with supporting configuration to reproduce.
1313

14+
## Changes
15+
16+
- Added `create_db_subnet_group` variable to control whether a DB subnet group is created or not; previously if `db_subnet_group_name` was specified then an existing subnet group was used. Now the combination of `create_db_subnet_group` and `db_subnet_group_name` determine the name of the subnet group AND whether to create anew or use existing
17+
- Minimum version of AWS provider increased to v3.63.0 to support features added
18+
- Added `random_password_length` to give users control over the length of the random password that can be created; defaults to prior existing value of `10`
19+
- Local variable check added on `aws_rds_cluster` for attributes `database_name`, `master_username` and `master_pass` to support secondary clusters (global cluster, replication cluster, etc.)
20+
- Conditional creation check for `is_serverless` added to `aws_rds_cluster_instance`, `aws_appautoscaling_target`, and `aws_appautoscaling_policy` since these are not applicable for serverless clusters
21+
- Added `availability_zone`, `copy_tags_to_snapshot` attributes to `aws_rds_cluster_instance` which are now accessible via the `instances` map
22+
- Removed `engine_version` from `aws_rds_cluster_instance` lifecycle ignore block now that this has been [patched in upstream AWS provider](https://github.com/hashicorp/terraform-provider-aws/pull/17111)
23+
- New resource `aws_rds_cluster_endpoint` added to allow for creation of custom, additional endpoints
24+
- New resource `aws_rds_cluster_role_association` added to allow for association IAM roles with the cluster
25+
- Where applicable, variable default values have been set to `null` to use upstream AWS provider default values
26+
- Update variable descriptions from upstream provider docs
27+
1428
## List of backwards incompatible changes
1529

16-
- TODO
30+
- Coalesce of previous, default IAM enhanced monitoring role name has been removed (this was marked as a `TODO` to remove at next breaking change)
31+
- `Name` tag removed from DB subnet group and enhanced monitoring role; the name is now set by the provider resource and this is no longer necessary
32+
- `iam_roles` removed from `aws_rds_cluster` resource with the addition of `aws_rds_cluster_role_association`; per the docs this will cause conflicts and only one should be used and the role association resource contains more functionality/features
33+
- `replication_source_identifier` added to `aws_rds_cluster` ignore lifecycle block to support [secondary, replication clusters per the docs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/rds_cluster#replication_source_identifier)
34+
- `global_cluster_identifier` added to `aws_rds_clsuter` ignore lifecycle block to support [global clusters per the docs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/rds_global_cluster#new-global-cluster-from-existing-db-cluster)
35+
- `replica_count`replaced with `instances`; instances are now controlled by a map of maps, allowing users to create a homogenous cluster or a heterogenous cluster with fine grain control over the instances provisioned through the use of the new map attributes. This means the `aws_rds_cluster_instance` no longer uses `count` and now uses `for_each` for better stability and isolated change control.
36+
- `iam_roles` variable has been re-purposed from a list of IAM roles to associate with the cluster via the `aws_rds_cluster` resource and instead is now a map of maps to associate roles via the new `aws_rds_cluster_role_association` resource
37+
- `aws_appautoscaling_target` resource identifier changed from `read_replica_count` to `this` to follow conventions. This change requires either re-creation or a Terraform state rename to avoid disruption (see below)
1738

1839
### Variable and output changes
1940

2041
1. Removed variables:
2142

22-
- `todo`
43+
- `replica_count`replaced with `instances`; instances are now controlled by a map of maps, allowing users to create a homogenous cluster or a heterogenous cluster with fine grain control over the instances provisioned through the use of the new map attributes
44+
- `instances_parameters` - no longer required now that individual instance attributes are defined within the map of maps passed to `instances`
45+
- `instance_type_replica` - no longer required now that individual instance attributes are defined within the map of maps passed to `instances`
2346

2447
2. Renamed variables:
2548

26-
- `todo` -> `todo`
49+
- `password` -> `master_password` to match resource's convention
50+
- `username` -> `master_username` to match resource's convention'
51+
- `replica_scale_enabled` -> `autoscaling_enabled`
52+
- `replica_scale_min` -> `autoscaling_min_capacity`
53+
- `replica_scale_max` -> `autoscaling_max_capacity`
54+
- `replica_scale_cpu` -> `autoscaling_target_cpu`
55+
- `replica_scale_connections` -> `autoscaling_target_connections`
56+
57+
3. Added variables:
58+
59+
- `create_db_subnet_group` to control whether a DB subnet group is created or not; previously controlled by whether `db_subnet_group_name` was specified or not
60+
- `random_password_length` to give users control over the length of the random password that can be created
61+
- `enable_global_write_forwarding` to support the same attribute on `aws_rds_cluster`
62+
- `performance_insights_retention_period` to support the same attribute on `aws_rds_cluster`
63+
- `db_cluster_db_instance_parameter_group_name` to support the `db_instance_parameter_group_name` attribute on `aws_rds_cluster`
64+
- `cluster_timeouts` to support `create`, `update`, and `delete` timeouts on `aws_rds_cluster`
65+
- `instances_use_identifier_prefix` to enable the option of using a prefix name strategy on cluster instances created
66+
- `instance_timeouts` to support `create`, `update`, and `delete` timeouts on `aws_rds_cluster_instance`
67+
- `endpoints` to support new resources `aws_rds_cluster_endpoint` resource(s)
68+
69+
4. Removed outputs:
2770

28-
3. Removed outputs:
71+
- `rds_cluster_instance_*` outputs have been removed in favor of one output `cluster_instances` which contains a map of all instances created and their attributes
2972

30-
- `todo`
73+
5. Renamed outputs:
3174

32-
4. Renamed outputs:
75+
- Outputs that started with `rds_cluster_*` have been updated to start with `cluster_*` (dropping the preceding `rds_`)
3376

34-
- `todo`
77+
6. Added outputs:
78+
79+
- `db_subnet_group_name`
80+
- `cluster_members`
81+
- `cluster_engine_version_actual`
82+
- `additional_cluster_endpoints`
83+
- `cluster_role_associations`
3584

3685
## Upgrade State Migrations
3786

@@ -42,9 +91,52 @@ module "cluster_before" {
4291
source = "terraform-aws-modules/rds-aurora/aws"
4392
version = "~> 5.0"
4493
45-
# TODO
46-
47-
tags = local.tags
94+
name = "before-5.x"
95+
engine = "aurora-postgresql"
96+
engine_version = "11.9"
97+
instance_type = "db.r5.large"
98+
- replica_count = 3
99+
100+
- instances_parameters = [
101+
# List index should be equal to `replica_count`
102+
# Omitted keys replaced by module defaults
103+
{
104+
instance_type = "db.r5.2xlarge"
105+
publicly_accessible = true
106+
},
107+
{
108+
instance_type = "db.r5.2xlarge"
109+
},
110+
{
111+
instance_name = "reporting"
112+
instance_type = "db.r5.large"
113+
instance_promotion_tier = 15
114+
}
115+
]
116+
117+
- autoscaling_enabled = true
118+
- autoscaling_min_capacity = 1
119+
- autoscaling_max_capacity = 5
120+
121+
vpc_id = "vpc-12345678"
122+
subnets = ["subnet-12345678", "subnet-87654321"]
123+
124+
allowed_security_groups = ["sg-12345678"]
125+
allowed_cidr_blocks = ["10.20.0.0/20"]
126+
127+
storage_encrypted = true
128+
apply_immediately = true
129+
monitoring_interval = 10
130+
131+
db_parameter_group_name = "default"
132+
db_cluster_parameter_group_name = "default"
133+
134+
enabled_cloudwatch_logs_exports = ["postgresql"]
135+
136+
tags = {
137+
Environment = "dev"
138+
Terraform = "true"
139+
}
48140
}
49141
```
50142

@@ -55,16 +147,62 @@ module "cluster_after" {
55147
source = "terraform-aws-modules/rds-aurora/aws"
56148
version = "~> 6.0"
57149
58-
# TODO
59-
60-
tags = local.tags
150+
name = "after-6.x"
151+
engine = "aurora-postgresql"
152+
engine_version = "11.9"
153+
instance_type = "db.r5.large"
154+
155+
+ instances = {
156+
1 = {
157+
instance_type = "db.r5.2xlarge"
158+
publicly_accessible = true
159+
}
160+
2 = {
161+
instance_type = "db.r5.2xlarge"
162+
}
163+
3 = {
164+
identifier = "reporting"
165+
instance_type = "db.r5.large"
166+
instance_promotion_tier = 15
167+
}
168+
]
169+
170+
+ autoscaling_enabled = true
171+
+ autoscaling_min_capacity = 1
172+
+ autoscaling_max_capacity = 5
173+
174+
vpc_id = "vpc-12345678"
175+
subnets = ["subnet-12345678", "subnet-87654321"]
176+
177+
allowed_security_groups = ["sg-12345678"]
178+
allowed_cidr_blocks = ["10.20.0.0/20"]
179+
180+
storage_encrypted = true
181+
apply_immediately = true
182+
monitoring_interval = 10
183+
184+
db_parameter_group_name = "default"
185+
db_cluster_parameter_group_name = "default"
186+
187+
enabled_cloudwatch_logs_exports = ["postgresql"]
188+
189+
tags = {
190+
Environment = "dev"
191+
Terraform = "true"
192+
}
61193
}
62194
```
63195

64196
To migrate from the `v5.x` version to `v6.x` version example shown above, the following state move commands can be performed to maintain the current resources without modification:
65197

66198
```bash
67-
terraform state mv 'module.cluster_before.todo[0]' 'module.cluster_after.todo.this[0]'
199+
terraform state mv 'module.cluster_before.aws_rds_cluster_instance.this[0]' 'module.cluster_after.aws_rds_cluster_instance.this["0"]'
200+
# Note: this move will need to be made for each instance in the cluster, where `<n>` is the instance creation order and is mapped to its new `<key>` specified
201+
# in the `var.instances` map. See next line for rough pattern to follow for all instances in your cluster
202+
# terraform state mv 'module.cluster_before.aws_rds_cluster_instance.this[<n>]' 'module.cluster_after.aws_rds_cluster_instance.this["<key>"]'
203+
204+
terraform state mv 'module.cluster_before.aws_appautoscaling_policy.autoscaling_read_replica_count[0]' 'module.cluster_after.aws_appautoscaling_policy.this[0]'
205+
terraform state mv 'module.cluster_before.aws_appautoscaling_target.read_replica_count[0]' 'module.cluster_after.aws_appautoscaling_target.this[0]'
68206
```
69207

70208
:info: Notes

‎main.tf

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ resource "aws_rds_cluster" "this" {
9191
}
9292

9393
dynamic "scaling_configuration" {
94-
for_each = length(keys(var.scaling_configuration)) == 0 ? [] : [var.scaling_configuration]
94+
for_each = length(keys(var.scaling_configuration)) == 0 || !local.is_serverless ? [] : [var.scaling_configuration]
9595

9696
content {
9797
auto_pause = lookup(scaling_configuration.value, "auto_pause", null)
@@ -141,7 +141,7 @@ resource "aws_rds_cluster_instance" "this" {
141141
for_each = var.create_cluster && !local.is_serverless ? var.instances : {}
142142

143143
# Notes:
144-
# Do not set preferred_backup_window - its set at the clsuter level and will error if provided here
144+
# Do not set preferred_backup_window - its set at the cluster level and will error if provided here
145145

146146
identifier = var.instances_use_identifier_prefix ? null : lookup(each.value, "identifier", "${var.name}-${each.key}")
147147
identifier_prefix = var.instances_use_identifier_prefix ? lookup(each.value, "identifier_prefix", "${var.name}-${each.key}-") : null

0 commit comments

Comments
 (0)