Create a new IAM managed policy version

Part 100 of AWS from Zero. This lesson changes or inspects one IAM concept so the permission model stays understandable.

What we are learning

Customer managed policy updates create immutable versions. Setting the new version as default changes permissions for every attachment.

Before you run it

POLICY_ARN="arn:aws:iam::123456789012:policy/AwsZeroListBuckets"
cat > updated-policy.json <<'EOF'
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["s3:ListAllMyBuckets", "s3:GetBucketLocation"],
    "Resource": "*"
  }]
}
EOF

Validate the policy and inventory every attached identity before changing the shared default.

The command

aws iam create-policy-version \
  --policy-arn "$POLICY_ARN" \
  --policy-document file://updated-policy.json \
  --set-as-default

IAM writes can take a short time to propagate. Inspect the resource after every change.

Inspect the result

aws iam get-policy \
  --policy-arn "$POLICY_ARN" \
  --query "Policy.{DefaultVersion:DefaultVersionId,Updated:UpdateDate}" \
  --output table

Read the returned ARN, path, IDs, and attachment state instead of checking only the command exit code.

One tiny variation

aws iam create-policy-version \
  --policy-arn "$POLICY_ARN" \
  --policy-document file://updated-policy.json

Without --set-as-default, the version is stored but does not change attached permissions.

Common mistake

A policy supports only a limited number of stored versions. Delete obsolete non-default versions deliberately before reaching the limit.

Cleanup

rm updated-policy.json
aws iam list-policy-versions --policy-arn "$POLICY_ARN"

Review version history; do not delete the previous version until rollback needs are understood.

Next, we will learn List IAM managed policy versions.

Official AWS CLI reference