Terraform MalformedPolicyDocument Error Fix: AWS Policy Creation

• Introduction
• Step-by-Step Guide
• Code Example
• Additional Notes
• Summary
• Conclusion
• References

Encountering the "MalformedPolicyDocument" error in your Terraform code can be frustrating, but it often stems from subtle mistakes within your IAM policy definitions. This guide will walk you through the common culprits behind this error and provide solutions to get your Terraform deployments back on track. We'll cover issues like extra commas, incorrect "Principal" usage, "Resource" specification, data type mismatches, and template formatting errors. Additionally, you'll find debugging tips to help you pinpoint the root cause of the problem.

The error "MalformedPolicyDocument" in Terraform typically arises from issues within your IAM policy definitions. Here's a breakdown of common causes and solutions:

1. Extra/Missing Commas:

• Ensure your JSON policy document doesn't have trailing commas after the last element in lists or objects.
• Example: "Action": ["s3:GetObject", "s3:PutObject" ] (incorrect) vs. "Action": ["s3:GetObject", "s3:PutObject"] (correct)

2. Incorrect "Principal" Usage:

• When defining policies for aws_iam_role_policy or aws_iam_user_policy, avoid using the "Principal" field. It's automatically handled by AWS.
• Example: Remove "Principal": {"AWS": "arn:aws:iam::123456789012:root"} from these policy types.

3. "Resource" Specification:

• The "Resource" field is mandatory in most cases. Ensure you're specifying the ARN of the resource the policy applies to.
• Example: "Resource": "arn:aws:s3:::my-bucket"

4. String vs. List Data Types:

• "Action", "Resource", and "Condition" often require lists, not strings.
• Example: "Action": "s3:GetObject" (incorrect) vs. "Action": ["s3:GetObject"] (correct)

5. Template Formatting:

• If using templates, ensure proper formatting to avoid extra spaces or characters that might break the JSON structure.

Debugging Tips:

• Use terraform validate to catch syntax errors early.
• Print the generated policy document using output or terraform console to inspect its structure.
• Compare your policy with AWS examples or documentation for reference.

Example:

data "aws_iam_policy_document" "s3_policy" {
  statement {
    actions = ["s3:GetObject", "s3:PutObject"]
    resources = ["arn:aws:s3:::my-bucket/*"]
  }
}

resource "aws_iam_role_policy" "example" {
  name   = "example"
  role   = aws_iam_role.example.id
  policy = data.aws_iam_policy_document.s3_policy.json
}

By carefully reviewing your policy structure and addressing these common issues, you can resolve "MalformedPolicyDocument" errors and ensure your Terraform deployments run smoothly.

This Terraform code defines an IAM policy document that grants permissions to interact with an S3 bucket. It demonstrates common pitfalls and correct usage patterns for creating IAM policies in Terraform, including avoiding trailing commas in lists, not using the "Principal" field in role policies, and ensuring "Action" is always a list. The code also includes an output to display the generated policy document for inspection.

# Incorrect: Trailing comma in "Action" list
# data "aws_iam_policy_document" "incorrect_policy" {
#   statement {
#     actions = ["s3:GetObject", "s3:PutObject",] # Incorrect!
#     resources = ["arn:aws:s3:::my-bucket/*"]
#   }
# }

# Correct: No trailing comma
data "aws_iam_policy_document" "s3_policy" {
  statement {
    actions = ["s3:GetObject", "s3:PutObject"] # Correct
    resources = ["arn:aws:s3:::my-bucket/*"]
  }
}

# Incorrect: "Principal" used in aws_iam_role_policy
# resource "aws_iam_role_policy" "incorrect_example" {
#   name   = "incorrect_example"
#   role   = aws_iam_role.example.id
#   policy = <<EOF
# {
#   "Version": "2012-10-17",
#   "Statement": [
#     {
#       "Principal": {                # Incorrect! Remove this block
#         "AWS": "arn:aws:iam::123456789012:root"
#       },
#       "Action": "s3:GetObject",
#       "Resource": "arn:aws:s3:::my-bucket/*"
#     }
#   ]
# }
# EOF
# }

# Correct: No "Principal" field
resource "aws_iam_role_policy" "example" {
  name   = "example"
  role   = aws_iam_role.example.id
  policy = data.aws_iam_policy_document.s3_policy.json
}

# Incorrect: "Action" as string instead of list
# data "aws_iam_policy_document" "incorrect_policy_2" {
#   statement {
#     actions = "s3:GetObject" # Incorrect!
#     resources = ["arn:aws:s3:::my-bucket/*"]
#   }
# }

# Correct: "Action" as a list
data "aws_iam_policy_document" "correct_policy" {
  statement {
    actions = ["s3:GetObject"] # Correct
    resources = ["arn:aws:s3:::my-bucket/*"]
  }
}

# Output the policy document for inspection
output "policy_json" {
  value = data.aws_iam_policy_document.s3_policy.json
}

Explanation:

• Trailing Comma: The commented-out incorrect_policy example demonstrates the trailing comma issue.
• Principal in Role Policy: The commented-out incorrect_example shows how using "Principal" within aws_iam_role_policy is incorrect.
• String vs. List: The incorrect_policy_2 example highlights the common mistake of using a string for "Action" instead of a list.
• Debugging: The output "policy_json" block helps you visualize the generated policy document, making it easier to spot errors.

Remember:

• Replace "arn:aws:s3:::my-bucket/*" with your actual S3 bucket ARN.
• Use terraform validate to check for syntax errors.
• Refer to AWS IAM policy documentation for detailed guidance on policy structure and elements.

• Whitespace and JSON: JSON is sensitive to extra spaces or line breaks. Ensure your policy document adheres to valid JSON syntax. Online JSON validators can be helpful.
• "Effect" Statement: While often implicit, explicitly stating "Effect": "Allow" or "Effect": "Deny" for each statement is good practice.
• AWS Service Namespaces: Use correct service namespaces in actions (e.g., "s3:GetObject", "ec2:RunInstances"). Refer to AWS documentation for the appropriate namespaces.
• Terraform Version Compatibility: Be mindful of potential changes in IAM policy syntax or Terraform resource behavior across different Terraform versions. Consult the documentation for your specific version.
• Policy Simulator: Utilize the IAM Policy Simulator in the AWS Management Console to test your policies against real or simulated scenarios. This can help identify unintended access or errors.
• Principle vs. Principal: A common typo is misspelling "Principal" as "Principle." Double-check for this error, as it can lead to parsing issues.
• Wildcard Characters: Understand the implications of using wildcard characters (*) in ARNs. While powerful, they can lead to overly permissive policies if not used cautiously.
• Policy Variables: When using variables within your policy documents, ensure they are properly interpolated and result in valid JSON strings.
• Comments in JSON: Avoid using comments within your JSON policy documents, as Terraform's JSON parser may not handle them correctly.
• Troubleshooting Flow:
  1. Run terraform validate to catch basic syntax errors.
  2. Use terraform console or output to print the generated policy document.
  3. Compare the output with AWS examples and the IAM policy documentation.
  4. Test the policy using the IAM Policy Simulator if possible.
• Online Resources: Leverage online JSON validators and formatters to ensure your policy documents are structurally sound.
• Modularization: For complex policies, consider breaking them down into smaller, reusable modules. This improves readability and maintainability.

This table summarizes common causes and solutions for "MalformedPolicyDocument" errors in Terraform:

Debugging Tips:

• Use terraform validate for early syntax error detection.
• Print the generated policy document using output or terraform console for inspection.
• Refer to AWS examples and documentation for policy structure guidance.

By addressing common causes like extra commas, incorrect "Principal" usage, and data type mismatches, you can resolve "MalformedPolicyDocument" errors effectively. Remember to leverage debugging tools like terraform validate and policy output for inspection. Referencing AWS documentation and examples ensures your policies adhere to the correct structure. With careful attention to detail and the use of provided examples and debugging techniques, you can create robust and error-free IAM policies in your Terraform code.

• Terraform AWS IAM Error — “MalformedPolicyDocument: Policy ... | I’m still a bit lost when it comes to understanding the nitty-gritty of IAM and I was a little stumped when I encountered this error…
• how to fix MalformedPolicyDocument : r/Terraform | Posted by u/bibi143143 - 2 votes and 9 comments
• MalformedPolicyDocument: Policy document should not specify a ... | Terraform Version Terraform v0.9.2 Affected Resource(s) Please list the resources as a list, for example: aws_iam_role_policy Terraform Configuration Files data "aws_iam_policy_document" "trust-ass...
• Terraform malformed policy - Terraform - HashiCorp Discuss | Hi, I’m working with kms policy , I’ using templatefile, but the issue here is that terraform plan is rearranging the arn’s and adding a comma at the last arn. When running terraform apply its failing with malformed policy. Is there any way to avoid this ? Terraform 0.12.20 variable "allowed_resources" { description = "list of all principal resources" type = list(string) default = [ "arn:aws:iam::xxxxxxxxx:user/a", "arn:aws:iam::xxxxxxxxx:user/b", "arn:aws:iam::xxxx...
• MalformedPolicyDocument: Policy document should not specify a ... | Community Note Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request Please do not leave "+1" or "me too" comments, th...
• Lists with trailing commas templated by terraform, rejected by AWS ... | Hey! Background To give an overview of what I’m doing - I’m working on a project in tf 0.12. The goal is to stand up some databases and data migration infrastructure. I’ve put together a couple of modules to handle that and a calling module to supply input. In my test environment I have 3 RDS instances, 3 DMS replication instances (1 per RDS), and 6 DMS endpoints (3 source, 3 target). What I want to do is allow some database, dev types into the AWS console so they can configure the endpoints,...
• ![MalformedPolicyDocument: Invalid principal in policy: "AWS" Only ... [MalformedPolicyDocument: Invalid principal in policy: "AWS" Only ... | #1388 The documentation specifically says this is allowed: https://www.terraform.io/docs/providers/aws/d/iam_policy_document.html#example-with-multiple-principals data "aws_caller_identity" "caller...
• Fixing the Terraform Error creating IAM Role ... | Jun 20, 2023 ... Fixing the Terraform Error creating IAM Role. MalformedPolicyDocument Has prohibited field Resource · Unraveling The IAM Policy Document. To ...
• Terraform documentation lists IAM policy resources key as optional ... | Terraform Version Terraform v0.7.4 Affected Resource(s) aws_iam_policy data source Expected Behavior Either Terraform should have created a valid aws_iam_policy without me specifying resources, bec...