aws iam create-policy: Create Customer-Managed Policies

aws iam create-policy creates a new customer-managed policy from a JSON permissions document and returns its ARN for attaching to roles, users, or groups.

Least-privilege pipelines version their policy JSON in the repo and create it via the CLI. The document syntax and the "already exists" case are the two things that trip CI.

What it does

aws iam create-policy registers the JSON at --policy-document as a managed policy named --policy-name, returning its ARN and default version v1. The document is validated server-side against the IAM policy grammar before it is accepted.

Common usage

Terminal

aws iam create-policy \
  --policy-name ci-deploy-policy \
  --policy-document file://policy.json \
  --query 'Policy.Arn' --output text

Options

Flag	What it does
--policy-name <name>	Name of the new policy (required)
--policy-document file://<f>	JSON document (use file:// to avoid quoting hell)
--description <text>	Human description of the policy
--path <path>	Optional IAM path prefix
--query Policy.Arn --output text	Capture the new ARN

In CI

Always pass the document as file://policy.json rather than inline JSON; shell quoting of nested JSON is the top cause of MalformedPolicyDocument. create-policy is not idempotent: a second run with the same name fails with EntityAlreadyExists, so use create-policy-version --set-as-default to update an existing policy instead of recreating it.

Common errors in CI

"An error occurred (EntityAlreadyExists) when calling the CreatePolicy operation: A policy called ci-deploy-policy already exists" means it was created on a prior run; switch to create-policy-version. "MalformedPolicyDocument: Syntax errors in policy" means invalid JSON or an unknown action/condition key. "LimitExceeded: Cannot exceed quota for PolicySize" means the document is too large. "AccessDenied" means missing iam:CreatePolicy.