# Upgrade rollout policies


Amazon Organizations upgrade rollout policies allow you to centrally manage and stagger automatic upgrades across multiple Amazon resources and accounts in your organization. With these policies, you can define the order in which resources receive upgrades, ensuring changes are validated in less critical environments before reaching production.

In today's complex cloud environments, managing upgrades across numerous resources and accounts can be challenging. Upgrade rollout policies address this challenge by providing a systematic approach to implementing upgrades. By using these policies, you can align your upgrade process with your organization's change management practices, reducing risk and improving operational efficiency.

Upgrade rollout policies leverage the hierarchical structure of Amazon Organizations to apply policies across your entire organization or specific organizational units (OUs). This integration allows you to manage upgrades at scale, eliminating the need for manual coordination or custom automation scripts.

## Key features and benefits


Upgrade rollout policies provide comprehensive capabilities for managing upgrades while offering significant advantages for organizations managing resources across multiple accounts and environments. The following table outlines the key features and their associated benefits:


**Features and benefits of upgrade rollout policies**  
[\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/en_us/organizations/latest/userguide/orgs_manage_policies_upgrade_rollout.html)

For more information about policy inheritance, see [Understanding management policy inheritance](orgs_manage_policies_inheritance_mgmt.md).

## What are upgrade rollout policies?


Upgrade rollout policies are a set of rules that determine how and when automatic upgrades are applied to your Amazon resources. These policies allow you to designate different upgrade orders for your resources, typically aligning with your development, testing, and production environments. By doing so, you can ensure that upgrades are first applied to less critical systems, allowing you to identify and address any issues before they affect your production workloads.

The policies support three upgrade orders: First, Second, and Last. These orders create a staged approach to upgrades, with resources designated as "First" receiving upgrades initially, followed by "Second" after a waiting period, and finally "Last" after another waiting period. This staggered approach gives you time to validate upgrades at each stage before they progress to more critical systems.

Upgrade rollout policies are particularly valuable for organizations with complex, multi-account structures or those with strict change management requirements. They provide a balance between maintaining up-to-date systems and minimizing the risk of upgrade-related disruptions to critical services.

## How upgrade rollout policies work


Upgrade rollout policies integrate seamlessly with your existing Amazon infrastructure and processes. When you create and attach an upgrade rollout policy to an organizational unit, it applies to all accounts within that OU. You can then use resource tags or patch orders to specify which resources should be upgraded in which order.

When a supported Amazon service releases an upgrade, it consults the upgrade rollout policies to determine the order in which resources should receive the upgrade. The service first applies the upgrade to resources marked as "First" during their configured maintenance windows. After a service-specific waiting period, typically around one week, resources marked as "Second" become eligible for the upgrade. Finally, after another waiting period, resources marked as "Last" receive the upgrade.

This process ensures that upgrades are applied in a controlled, predictable manner across your organization. It allows you to monitor the impact of upgrades at each stage and take corrective action if needed before the changes reach your most critical environments. The automated nature of this process reduces the operational overhead of managing upgrades, while still providing you with the control and visibility you need to maintain the stability and security of your Amazon resources.

## Terminology


Here are the key terms you should understand when working with upgrade rollout policies:


**Upgrade rollout policy terms**  

| Term | Definition | 
| --- | --- | 
| Active Date | The date when the AmVU becomes visible in the Describe Pending Maintenance Actions API and available for application. | 
| AmVU (Auto minor version upgrade) | The automatic upgrade process for minor versions of database engines. | 
| Effective policy | The final set of rules that apply to an account or resource after considering all inherited and directly attached policies. | 
| Maintenance window | A recurring time period during which automatic upgrades can be applied to a resource. Upgrade rollout policies work within these configured maintenance windows. | 
| Organizational unit (OU) | A container for Amazon accounts in your organization. Upgrade rollout policies can be attached at the OU level to affect all accounts within it. | 
| Patch order | The sequence in which resources receive upgrades (First, Second, Last). | 
| Policy target | The scope to which an upgrade rollout policy applies, which can be an entire organization, specific OUs, or individual accounts. | 
| Resource tags | Key-value pairs that can be used to identify which resources should follow specific upgrade orders within a policy. | 
| Scheduling window | The time frame during which resources of a specific patch order receive upgrades. | 
| Service-specific waiting period | The designated time interval between upgrading resources of different upgrade orders. This period varies by Amazon service and upgrade type. | 
| Upgrade order | A designation that determines when a resource receives upgrades relative to other resources. Can be set to First, Second, or Last. | 
| Upgrade rollout policy | The Amazon Organizations policy type used to manage upgrade schedules across resources. | 

## Use cases for upgrade rollout policies


Organizations of different sizes and industries can benefit from upgrade rollout policies. The following fictitious scenarios demonstrate common upgrade management challenges and how upgrade rollout policies provide efficient solutions. These examples are based on typical customer experiences but have been simplified to highlight key benefits and implementation patterns.

Many organizations face similar challenges: they need to keep their resources up-to-date with the latest versions while minimizing risk to their production environments. Without a centralized policy-based approach, teams often resort to manual processes or complex automation scripts. The following examples demonstrate how two different organizations might solve similar challenges using upgrade rollout policies:

### Example use case: Global Financial Services Company


A financial services company operates hundreds of Aurora PostgreSQL databases across multiple Amazon accounts. Before upgrade rollout policies, their DevOps team spent several days each month manually coordinating database upgrades, ensuring changes were tested in development environments before reaching production systems. By implementing upgrade rollout policies, they:
+ Tagged development databases with upgrade order "First"
+ Assigned QA databases to upgrade order "Second"
+ Designated production databases as upgrade order "Last"
+ Reduced upgrade coordination from days to minutes
+ Automatically validated changes in lower environments first
+ Maintained compliance with their change management requirements

### Example use case: IoT Device Platform Provider


An IoT company processes millions of device events daily using multiple Amazon RDS databases. They needed to ensure automatic minor version upgrades wouldn't disrupt their production services. Using upgrade rollout policies, they:
+ Created a policy that applies across their organizational structure
+ Configured canary environments to receive upgrades first
+ Set up monitoring in early-upgrade environments
+ Gained time to detect and respond to any issues before production upgrades
+ Replaced complex custom upgrade automation with a simple policy
+ Maintained high availability for their production workloads while staying current with database versions

## Supported Amazon services


Upgrade rollout policies integrate with the following Amazon services while supporting automatic minor version upgrades:


**Supported services for upgrade rollout policies**  

| Service name | Purpose | 
| --- | --- | 
| Amazon Aurora PostgreSQL-Compatible Edition | [ Automatic minor version upgrades](https://docs.amazonaws.cn/AmazonRDS/latest/AuroraUserGuide/USER_UpgradeDBInstance.Maintenance.html#Aurora.Maintenance.AMVU) | 
| Amazon Aurora MySQL-Compatible Edition | [ Automatic minor version upgrades](https://docs.amazonaws.cn/AmazonRDS/latest/AuroraUserGuide/USER_UpgradeDBInstance.Maintenance.html#Aurora.Maintenance.AMVU) | 
| Amazon Relational Database Service for PostgreSQL | [ Automatic minor version upgrades](https://docs.amazonaws.cn/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.PostgreSQL.Minor.html) | 
| Amazon Relational Database Service for SQL Server | [Automatic minor version upgrades](https://docs.amazonaws.cn/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.SQLServer.html) | 
| Amazon Relational Database Service for Oracle | [ Automatic minor version upgrades](https://docs.amazonaws.cn/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.Oracle.Minor.html#oracle-minor-version-upgrade-tuning-on) | 
| Amazon Relational Database Service for MariaDB | [ Automatic minor version upgrades](https://docs.amazonaws.cn/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.MariaDB.Minor.html) | 
| Amazon Relational Database Service for MySQL | [ Automatic minor version upgrades](https://docs.amazonaws.cn/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.MySQL.Minor.html) | 
| Amazon Relational Database Service for Db2 | [Automatic minor version upgrades](https://docs.amazonaws.cn/AmazonRDS/latest/UserGuide/Db2.Concepts.VersionMgmt.html) | 

## Prerequisites


The following are prerequisites and required permissions necessary for managing upgrade rollout policies in Amazon Organizations:
+ Amazon Organizations management account or delegated administrator access
+ Resources in supported services (currently Amazon Aurora and Amazon Relational Database Service database engines)
+ Proper IAM permissions to manage upgrade rollout policies

## Next steps


To begin using upgrade rollout policies:

1. Review the [Getting started with upgrade rollout policies](orgs_manage_policies_upgrade_getting_started.md) to learn how to create and manage policies

1. Explore [Best practices for using upgrade rollout policies](orgs_manage_policies_upgrade_best_practices.md) for implementing upgrade rollout policies

1. Understand [Upgrade rollout policy syntax and examples](orgs_manage_policies_upgrade_syntax.md)

# Getting started with upgrade rollout policies


Follow these steps to implement upgrade rollout policies in your organization. Each step links to detailed information to help you complete the implementation successfully.

## Before you begin


Ensure you have the following:
+ Administrative access to Amazon Organizations
+ Resources in supported Amazon services (such as Aurora or Amazon Relational Database Service)
+ Necessary IAM permissions configured

## Implementation steps


1. [Enable upgrade rollout policies for your organization.](enable-policy-type.md)

1. [Understand how upgrade rollout policies work.](orgs_manage_policies_upgrade_rollout.md#orgs_manage_policies_upgrade_rollout_how_work)
   + Identify development, testing, and production environments
   + Determine which resources should be upgraded first, second, and last
   + Document your tagging strategy for resource identification

1.  [Create a upgrade rollout policy](orgs_policies_create.md#create-upgrade-rollout-policy-procedure): 
   + Define the default rollout order (organizational unit or account level)
   + Specify resource targeting using tags
   + Configure any policy exclusions

1. [Attach an upgrade rollout policy to a single member account that you can use for testing.](orgs_policies_attach.md): 
   + Start with a test organizational unit
   + Verify policy inheritance
   + Confirm policy attachment status

1. Tag your resources according to your upgrade order strategy:
   + Apply tags to development resources for first upgrades
   + Tag testing resources for second-order upgrades
   + Designate production resources for last-order upgrades

1. Monitor and validate the policy:
   + Review upgrade order assignments
   + Verify policy effects on test resources

1. Test the upgrade process:
   + Wait for a service upgrade to become available
   + Monitor the upgrade progression through your environments
   + Verify that upgrades follow your specified order

1. Enable upgrade rollout policies for additional organizational units as needed

**Other information**
+ [Learn upgrade rollout policy syntax and see example policies](orgs_manage_policies_upgrade_syntax.md)

# Best practices for using upgrade rollout policies


Amazon recommends the following best practices for using upgrade rollout policies.

**Topics**
+ [

## Start small and scale gradually
](#orgs_manage_policies_upgrade_best_practices_scale)
+ [

## Establish review processes
](#orgs_manage_policies_upgrade_best_practices_review)
+ [

## Validate policy changes effectively
](#orgs_manage_policies_upgrade_best_practices_validate)
+ [

## Monitor and communicate changes
](#orgs_manage_policies_upgrade_best_practices_monitor)
+ [

## Maintain compliance and security
](#orgs_manage_policies_upgrade_best_practices_compliance)
+ [

## Optimize operational efficiency
](#orgs_manage_policies_upgrade_best_practices_optimize)

## Start small and scale gradually


Begin your implementation with a test policy attached to a single account in a non-critical environment. This approach allows you to validate the behavior and impact of upgrade rollout policies without risking disruption to critical workloads. Once you've confirmed the policy works as expected, incrementally move it up your organizational structure to include more accounts and organizational units.

This gradual scaling helps you identify and address any issues early in the implementation process. Consider creating a pilot group of resources that represents the diversity of your environment but carries minimal operational risk. Document the results of each expansion phase to inform future policy rollouts and adjustments.

## Establish review processes


Implement regular review processes to monitor for new upgrade rollout policy attributes and evaluate policy exceptions. These reviews should align with your organization's security and operational requirements. Create a schedule for reviewing policy effectiveness and maintain documentation of any adjustments made.

Your review process should include regular assessments of which resources are governed by policies, verification that upgrade orders align with your intended strategy, and evaluation of any policy exceptions. Consider establishing criteria for when policies need updating and maintain a change log to track policy evolution over time.

## Validate policy changes effectively


After making changes to an upgrade rollout policy, check the effective policies for representative accounts at each level of your organization. Use the Amazon Management Console or `DescribeEffectivePolicy` API operation to verify that your changes have the intended impact. This validation should include checking resources across different organizational units and confirming that inheritance works as expected.

Pay special attention to resources that have explicit upgrade orders assigned versus those using default values. Establish a validation checklist that includes verifying tag-based targeting, confirming maintenance window alignments, and testing policy inheritance.

## Monitor and communicate changes


Establish comprehensive monitoring for your upgrade rollout policies and create clear communication channels for sharing upgrade-related information. Document clear procedures for handling upgrade failures and create response plans for different scenarios.

Maintain regular communication with teams managing resources affected by upgrade policies. Consider creating dashboards that provide visibility into upcoming upgrades and their expected progression through your environments.

## Maintain compliance and security


Regularly audit your upgrade rollout policies to ensure they align with your compliance requirements. Document all policy decisions and maintain clear records of upgrade patterns and exceptions. Implement security controls around policy modifications and maintain an audit trail of policy changes using Amazon CloudTrail.

Review access permissions to policy management functions regularly and implement least-privilege access for policy administration. Create procedures for emergency policy modifications and maintain documentation of security-related upgrade requirements.

## Optimize operational efficiency


Design your policies to minimize operational overhead while maintaining necessary controls. To prevent unintended behavior, do not reuse tags across different use cases. Automate policy compliance checking where possible and create standard operating procedures for common policy management tasks.

Consider creating templates for different types of upgrade scenarios and maintain documentation of successful policy patterns. Regular review of operational metrics can help identify opportunities for policy optimization and process improvement.

# Upgrade rollout policy syntax and examples


An upgrade rollout policy defines how Amazon services apply automatic upgrades across your resources. Understanding the policy syntax helps you create effective policies that match your organization's upgrade requirements.

**Topics**
+ [

## Considerations
](#orgs_manage_policies_upgrade_syntax_considerations)
+ [

## Basic policy structure
](#orgs_manage_policies_upgrade_syntax_structure)
+ [

## Policy components
](#orgs_manage_policies_upgrade_syntax_components)
+ [

## Upgrade rollout policy examples
](#orgs_manage_policies_upgrade_syntax_examples)

## Considerations


When implementing upgrade rollout policies, consider these important factors:
+ Policy names must be unique within your organization and should be clear and descriptive. Choose names that reflect the policy's purpose and scope. For more information, see [Optimize operational efficiency](orgs_manage_policies_upgrade_best_practices.md#orgs_manage_policies_upgrade_best_practices_optimize).
+ Testing is crucial before broad deployment. Validate new policies in non-production environments first and expand gradually to ensure desired behavior. For more information, see [Start small and scale gradually](orgs_manage_policies_upgrade_best_practices.md#orgs_manage_policies_upgrade_best_practices_scale).
+ Policy changes may take several hours to propagate across your organization. Plan your implementations accordingly and ensure proper monitoring is in place. For more information, see [Monitor and communicate changes](orgs_manage_policies_upgrade_best_practices.md#orgs_manage_policies_upgrade_best_practices_monitor).
+ JSON formatting must be valid and stay within the maximum policy size of 5,120 bytes. Keep policy structures as simple as possible while meeting your requirements.
+ Regular policy reviews help maintain effectiveness. Schedule periodic evaluations of your policies to ensure they continue to meet your organizational needs. For more information, see [Establish review processes](orgs_manage_policies_upgrade_best_practices.md#orgs_manage_policies_upgrade_best_practices_review).
+ Resources without an assigned upgrade order default to the "Second" order. Consider explicitly setting upgrade orders for critical resources rather than relying on defaults. For more information, see [Validate policy changes effectively](orgs_manage_policies_upgrade_best_practices.md#orgs_manage_policies_upgrade_best_practices_validate).
+ Manual upgrades take precedence over policy-defined upgrade orders. Ensure your change management processes account for both automatic and manual upgrade scenarios. For more information, see [Establish review processes](orgs_manage_policies_upgrade_best_practices.md#orgs_manage_policies_upgrade_best_practices_review).

**Note**  
When implementing tag-based upgrade rollout policies from your management account, be aware that the management account cannot directly view or access resource-level tags in member accounts. We recommend establishing a process where member accounts apply consistent resource tags, and then create organization-level policies that reference these tags. This ensures proper coordination between resource-level tagging and organizational policy enforcement. You can also use [Tag policies](orgs_manage_policies_tag-policies.md) to help maintain consistent tags when resources are tagged across your organization.

## Basic policy structure


Upgrade rollout policies use a JSON structure that includes the following main elements:
+ Policy metadata (such as version information)
+ Resource targeting rules
+ Upgrade order specifications
+ Optional exception messages
+ Service-specific attributes

The following example shows a basic upgrade rollout policy structure:

```
{
   "upgrade_rollout":{
      "default":{
         "patch_order":{
            "@@assign":"last"
         }
      },
      "tags":{
         "devtag":{
            "tag_values":{
               "tag1":{
                  "patch_order":{
                     "@@assign":"first"
                  }
               },
               "tag2":{
                  "patch_order":{
                     "@@assign":"second"
                  }
               },
               "tag3":{
                  "patch_order":{
                     "@@assign":"last"
                  }
               }
            }
         }
      }
   }
}
```

## Policy components


An upgrade rollout policy consists of two key components that work together to control how upgrades are applied across your resources. These components include configuration options for both default behaviors and tag-based overrides. Understanding how these components interact helps you create effective policies that match your organizational needs.

### Default patch order setup


When you create an upgrade rollout policy without specifying any resource-specific overrides, all resources default to a base upgrade order. You can set this default using the "default" field in your policy. Resources without explicit upgrade order assignments through tags will follow this default order. 

**Note**  
The console experience today requires a default order to be specified.

The following example shows how to set all resources to receive upgrades last by default, unless overridden by tags. This approach is useful when you want to ensure most resources update later in the upgrade cycle:

```
"upgrade_rollout": {
    "default": {
        "patch_order": "last"
    }
}
```

### Resource level overriding via Tags


You can override the default upgrade order for specific resources using tags. This allows you to create granular control over which resources receive upgrades in which order. For example, you can assign different upgrade orders based on your environment types, development stages, or workload criticality.

The following example shows how to configure development resources to receive upgrades first and production resources to receive them last. This configuration ensures your development environments can validate upgrades before they reach production:

```
"upgrade_rollout": {
    "tags": {
        "environment": {
            "tag_values": {
                "development": {
                    "patch_order": "first"
                },
                "production": {
                    "patch_order": "last"
                }
            }
        }
    }
}
```

## Upgrade rollout policy examples


Here are common upgrade rollout policy scenarios:

### Example 1: Development environment first


This example shows how to configure resources in your development environment to receive upgrades first. By targeting resources with the "development" environment tag, you ensure your development environments are the first to receive and validate new upgrades. This pattern helps identify potential issues before upgrades reach more critical environments:

```
{
    "tags": {
        "environment": {
            "tag_values": {
                "development": {
                    "upgrade_order": "first"
                }
            }
        }
    }
}
```

### Example 2: Production environment last


This example demonstrates how to ensure your production environments receive upgrades last. By explicitly setting production-tagged resources to the last upgrade order, you maintain stability in your production environment while allowing adequate testing in pre-production environments. This approach is particularly useful for organizations with strict change management requirements:

```
{
    "tags": {
        "environment": {
            "tag_values": {
                "production": {
                    "upgrade_order": "last"
                }
            }
        }
    }
}
```

### Example 3: Multiple upgrade orders using tags


The following example demonstrates how to use a single tag key with different values to specify all three upgrade orders. This approach is useful when you want to manage upgrade orders through a single tagging scheme:

```
{
   "upgrade_rollout":{
      "default":{
         "patch_order":{
            "@@assign":"last"
         }
      },
      "tags":{
         "devtag":{
            "tag_values":{
               "tag1":{
                  "patch_order":{
                     "@@assign":"first"
                  }
               },
               "tag2":{
                  "patch_order":{
                     "@@assign":"second"
                  }
               },
               "tag3":{
                  "patch_order":{
                     "@@assign":"last"
                  }
               }
            }
         }
      }
   }
}
```