resource/aws_cloudformation_stack_set: Adds guidance about required permissions to error message

.changelog/37069.txt

@@ -0,0 +1,3 @@
+```release-note:enhancement
+resource/aws_cloudformation_stack_set: Adds guidance on permissions when using delegated administrator account
+```

internal/service/cloudformation/stack_set.go

@@ -19,6 +19,7 @@ import (
  "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
  "github.com/hashicorp/terraform-plugin-sdk/v2/helper/validation"
  "github.com/hashicorp/terraform-provider-aws/internal/conns"
+ "github.com/hashicorp/terraform-provider-aws/internal/errs"
  "github.com/hashicorp/terraform-provider-aws/internal/errs/sdkdiag"
  "github.com/hashicorp/terraform-provider-aws/internal/flex"
  tftags "github.com/hashicorp/terraform-provider-aws/internal/tags"
@@ -319,7 +320,13 @@ func resourceStackSetCreate(ctx context.Context, d *schema.ResourceData, meta in
  )
 
  if err != nil {
- return sdkdiag.AppendErrorf(diags, "creating CloudFormation StackSet (%s): %s", name, err)
+ var detail string
+ if tfawserr.ErrMessageContains(err, errCodeValidationError, "Account used is not a delegated administrator") {
+ detail = "If you confirm that you are using a delegated administrator account, verify that the IAM User or Role has the permission \"organizations:ListDelegatedAdministrators\"."
+ }
+
+ d := errs.NewErrorDiagnostic(fmt.Sprintf("creating CloudFormation StackSet (%s): %s", name, err), detail)
+ return append(diags, d)
  }
 
  d.SetId(name)

internal/service/cloudformation/stack_set_test.go

@@ -828,6 +828,11 @@ func TestAccCloudFormationStackSet_autoDeploymentDisabled(t *testing.T) {
 }
 
 // https://github.com/hashicorp/terraform-provider-aws/issues/32536.
+// Prerequisites:
+// * Organizations root account
+// * Organization member account
+// * Deleegated administrator not configured
+// Authenticate with member account as target account and root account as alternate.
 func TestAccCloudFormationStackSet_delegatedAdministrator(t *testing.T) {
  ctx := acctest.Context(t)
  providers := make(map[string]*schema.Provider)

website/docs/r/cloudformation_stack_set.html.markdown

@@ -14,6 +14,8 @@ Manages a CloudFormation StackSet. StackSets allow CloudFormation templates to b
 
 ~> **NOTE:** All `NoEcho` template parameters must be ignored with the `lifecycle` configuration block `ignore_changes` argument.
 
+~> **NOTE:** When using a delegated administrator account, ensure that your IAM User or Role has the `organizations:ListDelegatedAdministrators` permission. Otherwise, you may get an error like `ValidationError: Account used is not a delegated administrator`.
+
 ## Example Usage
 
 ```terraform