Merge pull request #20211 from hashicorp/f-standardize_engine_version…

…_handling_rds_cluster

Use engine_version and engine_version_actual for aws_rds_cluster and rds_cluster_instance

.changelog/20211.txt

@@ -0,0 +1,7 @@
+```release-note:enhancement
+resource/aws_rds_cluster: Use engine_version and engine_version_actual to set and track engine versions
+```
+
+```release-note:enhancement
+resource/aws_rds_cluster_instance: Use engine_version and engine_version_actual to set and track engine versions
+```

aws/resource_aws_rds_cluster.go

@@ -170,6 +170,11 @@ func resourceAwsRDSCluster() *schema.Resource {
 				Computed: true,
 			},
 
+			"engine_version_actual": {
+				Type:     schema.TypeString,
+				Computed: true,
+			},
+
 			"scaling_configuration": {
 				Type:             schema.TypeList,
 				Optional:         true,
@@ -1053,11 +1058,12 @@ func resourceAwsRDSClusterRead(d *schema.ResourceData, meta interface{}) error {
 
 	d.Set("endpoint", dbc.Endpoint)
 	d.Set("engine_mode", dbc.EngineMode)
-	d.Set("engine_version", dbc.EngineVersion)
 	d.Set("engine", dbc.Engine)
 	d.Set("hosted_zone_id", dbc.HostedZoneId)
 	d.Set("iam_database_authentication_enabled", dbc.IAMDatabaseAuthenticationEnabled)
 
+	rdsClusterSetResourceDataEngineVersionFromCluster(d, dbc)
+
 	var roles []string
 	for _, r := range dbc.AssociatedRoles {
 		roles = append(roles, aws.StringValue(r.RoleArn))
@@ -1496,3 +1502,16 @@ func waitForRDSClusterDeletion(conn *rds.RDS, id string, timeout time.Duration)
 
 	return err
 }
+
+func rdsClusterSetResourceDataEngineVersionFromCluster(d *schema.ResourceData, c *rds.DBCluster) {
+	oldVersion := d.Get("engine_version").(string)
+	newVersion := aws.StringValue(c.EngineVersion)
+	compareActualEngineVersion(d, oldVersion, newVersion)
+}
+
+func compareActualEngineVersion(d *schema.ResourceData, oldVersion string, newVersion string) {
+	if oldVersion != newVersion && string(append([]byte(oldVersion), []byte(".")...)) != string([]byte(newVersion)[0:len(oldVersion)+1]) {
+		d.Set("engine_version", newVersion)
+	}
+	d.Set("engine_version_actual", newVersion)
+}

aws/resource_aws_rds_cluster_instance.go

@@ -106,6 +106,11 @@ func resourceAwsRDSClusterInstance() *schema.Resource {
 				Computed: true,
 			},
 
+			"engine_version_actual": {
+				Type:     schema.TypeString,
+				Computed: true,
+			},
+
 			"db_parameter_group_name": {
 				Type:     schema.TypeString,
 				Optional: true,
@@ -447,7 +452,6 @@ func resourceAwsRDSClusterInstanceRead(d *schema.ResourceData, meta interface{})
 	d.Set("cluster_identifier", db.DBClusterIdentifier)
 	d.Set("copy_tags_to_snapshot", db.CopyTagsToSnapshot)
 	d.Set("dbi_resource_id", db.DbiResourceId)
-	d.Set("engine_version", db.EngineVersion)
 	d.Set("engine", db.Engine)
 	d.Set("identifier", db.DBInstanceIdentifier)
 	d.Set("instance_class", db.DBInstanceClass)
@@ -463,6 +467,8 @@ func resourceAwsRDSClusterInstanceRead(d *schema.ResourceData, meta interface{})
 	d.Set("storage_encrypted", db.StorageEncrypted)
 	d.Set("ca_cert_identifier", db.CACertificateIdentifier)
 
+	rdsClusterSetResourceDataEngineVersionFromClusterInstance(d, db)
+
 	if len(db.DBParameterGroups) > 0 {
 		d.Set("db_parameter_group_name", db.DBParameterGroups[0].DBParameterGroupName)
 	}
@@ -658,3 +664,9 @@ var resourceAwsRdsClusterInstanceDeletePendingStates = []string{
 	"modifying",
 	"deleting",
 }
+
+func rdsClusterSetResourceDataEngineVersionFromClusterInstance(d *schema.ResourceData, c *rds.DBInstance) {
+	oldVersion := d.Get("engine_version").(string)
+	newVersion := aws.StringValue(c.EngineVersion)
+	compareActualEngineVersion(d, oldVersion, newVersion)
+}

aws/resource_aws_rds_cluster_test.go

@@ -209,6 +209,47 @@ func TestAccAWSRDSCluster_AllowMajorVersionUpgrade(t *testing.T) {
 	})
 }
 
+func TestAccAWSRDSCluster_OnlyMajorVersion(t *testing.T) {
+	var dbCluster1 rds.DBCluster
+	rName := acctest.RandomWithPrefix("tf-acc-test")
+	resourceName := "aws_rds_cluster.test"
+	// If these hardcoded versions become a maintenance burden, use DescribeDBEngineVersions
+	// either by having a new data source created or implementing the testing similar
+	// to TestAccAWSDmsReplicationInstance_EngineVersion
+	engine := "aurora-postgresql"
+	engineVersion1 := "11"
+
+	resource.ParallelTest(t, resource.TestCase{
+		PreCheck:     func() { testAccPreCheck(t) },
+		ErrorCheck:   testAccErrorCheck(t, rds.EndpointsID),
+		Providers:    testAccProviders,
+		CheckDestroy: testAccCheckAWSClusterDestroy,
+		Steps: []resource.TestStep{
+			{
+				Config: testAccAWSClusterConfig_MajorVersionOnly(rName, false, engine, engineVersion1),
+				Check: resource.ComposeTestCheckFunc(
+					testAccCheckAWSClusterExists(resourceName, &dbCluster1),
+					resource.TestCheckResourceAttr(resourceName, "engine", engine),
+					resource.TestCheckResourceAttr(resourceName, "engine_version", engineVersion1),
+				),
+			},
+			{
+				ResourceName:      resourceName,
+				ImportState:       true,
+				ImportStateVerify: true,
+				ImportStateVerifyIgnore: []string{
+					"allow_major_version_upgrade",
+					"apply_immediately",
+					"cluster_identifier_prefix",
+					"master_password",
+					"skip_final_snapshot",
+					"engine_version",
+				},
+			},
+		},
+	})
+}
+
 func TestAccAWSRDSCluster_AvailabilityZones(t *testing.T) {
 	var dbCluster rds.DBCluster
 	rName := acctest.RandomWithPrefix("tf-acc-test")
@@ -2528,6 +2569,30 @@ resource "aws_rds_cluster_instance" "test" {
 `, allowMajorVersionUpgrade, rName, engine, engineVersion)
 }
 
+func testAccAWSClusterConfig_MajorVersionOnly(rName string, allowMajorVersionUpgrade bool, engine string, engineVersion string) string {
+	return fmt.Sprintf(`
+resource "aws_rds_cluster" "test" {
+  allow_major_version_upgrade = %[1]t
+  apply_immediately           = true
+  cluster_identifier          = %[2]q
+  engine                      = %[3]q
+  engine_version              = %[4]q
+  master_password             = "mustbeeightcharaters"
+  master_username             = "test"
+  skip_final_snapshot         = true
+}
+
+# Upgrading requires a healthy primary instance
+resource "aws_rds_cluster_instance" "test" {
+  cluster_identifier = aws_rds_cluster.test.id
+  engine             = aws_rds_cluster.test.engine
+  engine_version     = aws_rds_cluster.test.engine_version
+  identifier         = %[2]q
+  instance_class     = "db.r4.large"
+}
+`, allowMajorVersionUpgrade, rName, engine, engineVersion)
+}
+
 func testAccAWSClusterConfig_AvailabilityZones(rName string) string {
 	return fmt.Sprintf(`
 data "aws_availability_zones" "available" {

website/docs/r/rds_cluster.html.markdown

@@ -116,9 +116,9 @@ The following arguments are supported:
 * `deletion_protection` - (Optional) If the DB instance should have deletion protection enabled. The database can't be deleted when this value is set to `true`. The default is `false`.
 * `enable_http_endpoint` - (Optional) Enable HTTP endpoint (data API). Only valid when `engine_mode` is set to `serverless`.
 * `enabled_cloudwatch_logs_exports` - (Optional) Set of log types to export to cloudwatch. If omitted, no logs will be exported. The following log types are supported: `audit`, `error`, `general`, `slowquery`, `postgresql` (PostgreSQL).
-* `engine_mode` - (Optional) The database engine mode. Valid values: `global` (only valid for Aurora MySQL 1.21 and earlier), `multimaster`, `parallelquery`, `provisioned`, `serverless`. Defaults to: `provisioned`. See the [RDS User Guide](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/aurora-serverless.html) for limitations when using `serverless`.
-* `engine_version` - (Optional) The database engine version. Updating this argument results in an outage. See the [Aurora MySQL](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Updates.html) and [Aurora Postgres](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Updates.html) documentation for your configured engine to determine this value. For example with Aurora MySQL 2, a potential value for this argument is `5.7.mysql_aurora.2.03.2`.
 * `engine` - (Optional) The name of the database engine to be used for this DB cluster. Defaults to `aurora`. Valid Values: `aurora`, `aurora-mysql`, `aurora-postgresql`
+* `engine_mode` - (Optional) The database engine mode. Valid values: `global` (only valid for Aurora MySQL 1.21 and earlier), `multimaster`, `parallelquery`, `provisioned`, `serverless`. Defaults to: `provisioned`. See the [RDS User Guide](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/aurora-serverless.html) for limitations when using `serverless`.
+* `engine_version` - (Optional) The database engine version. Updating this argument results in an outage. See the [Aurora MySQL](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Updates.html) and [Aurora Postgres](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Updates.html) documentation for your configured engine to determine this value. For example with Aurora MySQL 2, a potential value for this argument is `5.7.mysql_aurora.2.03.2`. The value can contain a partial version where supported by the API. The actual engine version used is returned in the attribute `engine_version_actual`, [defined below](#engine_version_actual).
 * `final_snapshot_identifier` - (Optional) The name of your final DB snapshot when this DB cluster is deleted. If omitted, no final snapshot will be made.
 * `global_cluster_identifier` - (Optional) The global cluster identifier specified on [`aws_rds_global_cluster`](/docs/providers/aws/r/rds_global_cluster.html).
 * `iam_database_authentication_enabled` - (Optional) Specifies whether or mappings of AWS Identity and Access Management (IAM) accounts to database accounts is enabled. Please see [AWS Documentation](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/UsingWithRDS.IAMDBAuth.html) for availability and limitations.
@@ -236,7 +236,7 @@ In addition to all arguments above, the following attributes are exported:
 * `reader_endpoint` - A read-only endpoint for the Aurora cluster, automatically
 load-balanced across replicas
 * `engine` - The database engine
-* `engine_version` - The database engine version
+* `engine_version_actual` - The running version of the database.
 * `database_name` - The database name
 * `port` - The database port
 * `master_username` - The master username for the database

website/docs/r/rds_cluster_instance.html.markdown

@@ -97,7 +97,7 @@ In addition to all arguments above, the following attributes are exported:
 * `availability_zone` - The availability zone of the instance
 * `endpoint` - The DNS address for this instance. May not be writable
 * `engine` - The database engine
-* `engine_version` - The database engine version
+* `engine_version_actual` - The database engine version
 * `port` - The database port
 * `storage_encrypted` - Specifies whether the DB cluster is encrypted.
 * `kms_key_id` - The ARN for the KMS encryption key if one is set to the cluster.