Merge pull request #30158 from hashicorp/td-aws_rds_cluster-snapshot-…

…with-global-id-warning

`r/aws_rds_cluster`: Conflict `snapshot_identifier` and `global_cluster_identifier`

.changelog/30158.txt

@@ -0,0 +1,3 @@
+```release-note:enhancement
+resource/aws_rds_cluster: Conflict `snapshot_identifier` and `global_cluster_identifier` attributes, preventing misleading results on restore
+```

internal/service/rds/cluster.go

@@ -432,6 +432,13 @@ func ResourceCluster() *schema.Resource {
 			"snapshot_identifier": {
 				Type:     schema.TypeString,
 				Optional: true,
+				ConflictsWith: []string{
+					// Clusters cannot be joined to an existing global cluster as part of
+					// the "restore from snapshot" operation. Trigger an error during plan
+					// to prevent an apply with unexpected results (ie. a regional
+					// cluster which is not joined to the provided global cluster).
+					"global_cluster_identifier",
+				},
 			},
 			"source_region": {
 				Type:     schema.TypeString,

website/docs/r/rds_cluster.html.markdown

@@ -145,6 +145,36 @@ resource "aws_rds_cluster_instance" "example" {
 }
 ```
 
+### Global Cluster Restored From Snapshot
+
+```terraform
+data "aws_db_cluster_snapshot" "example" {
+  db_cluster_identifier = "example-original-cluster"
+  most_recent           = true
+}
+
+resource "aws_rds_cluster" "example" {
+  # Because the global cluster is sourced from this cluster, the initial 
+  # engine and engine_version values are defined here and automatically
+  # inherited by the global cluster.
+  engine         = "aurora"
+  engine_version = "5.6.mysql_aurora.1.22.4"
+
+  cluster_identifier  = "example"
+  snapshot_identifier = data.aws_db_cluster_snapshot.example.id
+
+  lifecycle {
+    ignore_changes = [snapshot_identifier, global_cluster_identifier]
+  }
+}
+
+resource "aws_rds_global_cluster" "example" {
+  global_cluster_identifier    = "example"
+  source_db_cluster_identifier = aws_rds_cluster.example.arn
+  force_destroy                = true
+}
+```
+
 ## Argument Reference
 
 For more detailed documentation about each argument, refer to
@@ -191,7 +221,7 @@ The following arguments are supported:
 * `scaling_configuration` - (Optional) Nested attribute with scaling properties. Only valid when `engine_mode` is set to `serverless`. More details below.
 * `serverlessv2_scaling_configuration`- (Optional) Nested attribute with scaling properties for ServerlessV2. Only valid when `engine_mode` is set to `provisioned`. More details below.
 * `skip_final_snapshot` - (Optional) Determines whether a final DB snapshot is created before the DB cluster is deleted. If true is specified, no DB snapshot is created. If false is specified, a DB snapshot is created before the DB cluster is deleted, using the value from `final_snapshot_identifier`. Default is `false`.
-* `snapshot_identifier` - (Optional) Specifies whether or not to create this cluster from a snapshot. You can use either the name or ARN when specifying a DB cluster snapshot, or the ARN when specifying a DB snapshot.
+* `snapshot_identifier` - (Optional) Specifies whether or not to create this cluster from a snapshot. You can use either the name or ARN when specifying a DB cluster snapshot, or the ARN when specifying a DB snapshot. Conflicts with `global_cluster_identifier`. Clusters cannot be restored from snapshot **and** joined to an existing global cluster in a single operation. See the [AWS documentation](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-global-database-getting-started.html#aurora-global-database.use-snapshot) or the [Global Cluster Restored From Snapshot example](#global-cluster-restored-from-snapshot) for instructions on building a global cluster starting with a snapshot.
 * `source_region` - (Optional) The source region for an encrypted replica DB cluster.
 * `allocated_storage` - (Optional) The amount of storage in gibibytes (GiB) to allocate to each DB instance in the Multi-AZ DB cluster. (This setting is required to create a Multi-AZ DB cluster).
 * `storage_type` - (Optional) Specifies the storage type to be associated with the DB cluster. (This setting is required to create a Multi-AZ DB cluster). Valid values: `io1`, Default: `io1`.