Versioning for Managed Policies
When you make changes to a customer managed policy, and when AWS makes changes to an AWS managed policy, the changed policy doesn't overwrite the existing policy. Instead, IAM creates a new version of the managed policy. The following diagram illustrates this.
You can use versions to track changes to a managed policy. For example, you might make a change to a managed policy and then discover that the change had unintended effects. In this case, you can roll back to a previous version of the managed policy by setting the previous version as the default version.
The following sections explain how you can use versioning for managed policies.
Setting the Default Version
One of the versions of a managed policy is set as the default version. The policy's default version is the operative version—that is, it's the version that is in effect for all of the principal entities (users, groups, and roles) that the managed policy is attached to.
When you create a customer managed policy, the policy begins with a single version identified as v1. For managed policies with only a single version, that version is automatically set as the default. For customer managed policies with more than one version, you choose which version to set as the default. For AWS managed policies, the default version is set by AWS. The following diagrams illustrate this concept.
You can set the default version of your customer managed policies, but AWS sets the default version of AWS managed policies. You set the default version of a customer managed policy using the AWS Management Console, the AWS Command Line Interface, or the IAM API.
Using Versions to Roll Back Changes
When you make changes to a customer managed policy, your changes are stored as policy versions. In some cases, you may want to roll back your changes. For example, consider the following scenario.
You create a customer managed policy that allows users to administer a particular Amazon S3 bucket using the AWS Management Console. Upon creation, your customer managed policy has only one version, identified as v1, so that version is automatically set as the default. The policy works as intended.
Later, you update the policy to add permission to administer a second Amazon S3 bucket. IAM creates a new version of the policy, identified as v2, that contains your changes. You set version v2 as the default, and a short time later your users report that they are unable to use the Amazon S3 console at all due to a permissions error. In this case, you can roll back to version v1 of the policy, which you know works as intended. To do this, you set version v1 as the default version. Your users are now able to use the Amazon S3 console to administer the original bucket.
Later, after you determine the error in version v2 of the policy, you update the policy again to add permission to administer the second Amazon S3 bucket. IAM creates another new version of the policy, identified as v3. You set version v3 as the default, and this version works as intended. At this point, you delete version v2 of the policy.
A managed policy can have up to five versions. If you need to make changes to a managed policy beyond five versions, you must first delete one or more existing versions. You can delete any version of the managed policy that you want, except for the default version.
When you delete a version, the version identifiers for the remaining versions do not change. As a result, version identifiers might not be sequential. For example, if you delete versions v2 and v4 of a managed policy and add two new versions, the remaining version identifiers might be v1, v3, v5, v6, and v7.