& (ampersand) in Terraform string or/and AWS IAM policy

Question

I coudn't find meaning of & sign in Terraform or/and AWS IAM policy. There is an example in Data Source: aws_iam_policy_document (docs) where you can see Basic Example (docs, github source):

data "aws_iam_policy_document" "example" {
  (..)

  statement {
    actions = [
      "s3:*",
    ]

    resources = [
      "arn:aws:s3:::${var.s3_bucket_name}/home/&{aws:username}",
      "arn:aws:s3:::${var.s3_bucket_name}/home/&{aws:username}/*",
    ]
  }
}

I cound't find the meaning of &{aws:username}. I'd try to look up in AWS IAM documentation but there is only explanation how to use variables with dollar ($):

The variable is marked using a $ prefix followed by a pair of curly braces ({ }).

Source

Question: What does & character mean in above example?

Answer 1

The note callout at the top of the aws_iam_policy_document documentation explains this syntax:

Note: AWS's IAM policy document syntax allows for replacement of policy variables within a statement using ${...}-style notation, which conflicts with Terraform's interpolation syntax. In order to use AWS policy variables with this data source, use &{...} notation for interpolations that should be processed by AWS rather than by Terraform.

In other words, this is a special syntax implemented as a special case inside the hashicorp/aws Terraform provider to make it easier to use the IAM policy interpolation syntax without conflicting with Terraform's own template interpolation syntax. The provider will automatically replace &{ with ${ while it is rendering the final policy document.