[Docs]: aws_rds_cluster add section for Major version upgrades and parameter db_instance_parameter_group_name

[carlosjgp]

Documentation Link

https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/rds_cluster#db_instance_parameter_group_name

Description

Looks like the way to perform a major version upgrade of an RDS cluster with instances is to specify the instance parameter group on the cluster resource which is counter-intuitive.

This is not clearly explained anywhere on the AWS API docs, AWS documentation, AWS CLI or Terraform AWS provider

It seemed something that you have to know because you have suffered it 😅

I think a simple section explaining just a little bit better what is that parameter for and why you might need to use it whenever you are not using the default parameter groups would be incredibly helpful

References

• https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.PostgreSQL.html#USER_UpgradeDBInstance.PostgreSQL.MajorVersion.Process
• https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html?highlight=modify_db_cluster#RDS.Client.modify_db_cluster
• https://awscli.amazonaws.com/v2/documentation/api/latest/reference/rds/modify-db-cluster.html
• https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/rds_cluster#db_instance_parameter_group_name

Would you like to implement a fix?

Yes

[github-actions]

Community Note

Voting for Prioritization

• Please vote on this issue by adding a 👍 reaction to the original post to help the community and maintainers prioritize this request.
• Please see our prioritization guide for information on how we prioritize.
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request.

Volunteering to Work on This Issue

• If you are interested in working on this issue, please leave a comment.
• If this would be your first contribution, please review the contribution guide.

[bennylu2]

@carlosjgp could you provide some sample terraform code for performing an upgrade? I believe it also requires instance

[carlosjgp]

Sorry for the delay

variable "allow_major_version_upgrade" {
  description = "Enable to allow major engine version upgrades when changing engine versions"
  type        = bool
  default     = false
}

variable "db_parameter_group_name" {
  description = "The name of a DB parameter group to use for each instance"
  type        = string
}

variable "db_cluster_parameter_group_name" {
  description = "The name of a DB Cluster parameter group to use"
  type        = string
}

resource "aws_rds_cluster" "this" {
  <...>
  db_cluster_parameter_group_name  = var.db_cluster_parameter_group_name
  allow_major_version_upgrade      = var.allow_major_version_upgrade
  db_instance_parameter_group_name = var.allow_major_version_upgrade ? var.db_parameter_group_name : null

}

resource "aws_rds_cluster_instance" "this" {
  <...>
  db_parameter_group_name = var.db_parameter_group_name
}

[carlosjgp]

Here is our documentation about engine upgrades

---

Engine upgrades

AWS documentation

Automated minor upgrades

AWS auto minor upgrades only trigger for versions that AWS itself consider contains necessary security patches

• PG major version upgrade reference
• Extension versions by PG version

Minor

• Ensure auto_minor_version_upgrade = false.
• Update the engine_version value to the desired version.
• Set apply_immediately = true or leave false to be updated over the next RDS maintenance window
• Terraform Apply
• Set back auto_minor_version_upgrade = true, leave only the major verisonon engine_version and apply_immediately = false if you want
• Terraform Apply

Major

• Set allow_major_version_upgrade = true.
• Update the engine_version value to the desired version following AWS documentation
• Set apply_immediately = true or left false to be updated over the next RDS maintenance window
• Terraform Apply
• Set back allow_major_version_upgrade = false and apply_immediately = false
• Terraform Apply

PostGIS

PostGIS

When upgrading major PG version check if PostGIS extension is installed.

Upgrade version 2 to 3

Upgrade guide

[arianvp]

The provider already handles this in the code it seems:

terraform-provider-aws/internal/service/rds/cluster.go

Line 1462 in 6535984

input.DBInstanceParameterGroupName = nil