How do I perform an in-place upgrade or replacement upgrade for my AWS::Elasticsearch::Domain resource in CloudFormation?

3 minute read

I want to perform an in-place upgrade for my AWS::Elasticsearch::Domain resource in AWS CloudFormation.

Short description

To enable an in-place upgrade for your AWS::Elasticsearch::Domain resource, you must use an UpdatePolicy attribute called EnableVersionUpgrade in your CloudFormation template. You can use the EnableVersionUpgrade policy to enable or disable in-place upgrades for an Amazon OpenSearch Service domain.

Before you perform an in-place upgrade or replacement upgrade, consider the following:

  • Amazon OpenSearch Service supports in-place OpenSearch Service upgrades for versions 5.1 or later.
  • If you change the value of the EngineVersion property during a stack update, then CloudFormation performs a replacement update for an OpenSearch Service domain. Then, CloudFormation creates a new domain.
  • With an in-place upgrade, you can track the upgrade history of your domain and keep the same domain endpoint URL. You don't have to make configuration changes to the services that interface with your domain. These services will have access to the new version of your domain.
  • A replacement upgrade doesn't allow you to track your upgrade history. The old domain is replaced with a new domain and new endpoint URL for that domain. To allow the services that interface with your domain to access the new domain, you must make configuration changes to your services. For more information, see Creating and managing OpenSearch Service domains.


1.    In your CloudFormation stack template, add the EnableVersionUpgrade update policy.

2.    To allow CloudFormation to perform an in-place upgrade, set EnableVersionUpgrade to true and set ElasticsearchVersion to the value of your version.


To replace the AWS::Elasticsearch::Domain resource with a new AWS::Elasticsearch::Domain resource, set EnableVersionUpgrade to false or don't specify any value.

For example, the UpdatePolicy attribute is configured for an in-place upgrade in the following template:

>AWSTemplateFormatVersion: 2010-09-09
Description: AWS CloudFormation sample template to launch an Amazon OpenSearch Service Domain. Performing an update using the same template and supplying a different ElasticsearchVersion will perform an in-place upgrade for an Elasticsearch Domain resource.
    Type: String
    AllowedValues: ['5.6', '5.5', '5.3', '5.1', '6.8', '6.7', '6.5', '6.4', '6.3', '6.2', '6.0', '7.4', '7.1']
    Default: 5.3
    Description: The version of Amazon OpenSearch Service to use.
    Type: String
    Default: m3.medium.elasticsearch
    Description: The instance type for your data nodes.
    Type: String
    Default: 1
    Description: The number of data nodes (instances) to use in the OpenSearch Service domain.
    Type: AWS::Elasticsearch::Domain
       EnableVersionUpgrade: true   ### In-place Upgrade
        InstanceCount: !Ref NumberOfDataNodes
        InstanceType: !Ref InstanceTypeForDataNode
      ElasticsearchVersion: !Ref ElasticsearchVersion

3.    To complete the in-place upgrade or replacement upgrade process, update your stack using either the CloudFormation console or AWS Command Line Interface (AWS CLI).

Related information

Upgrading Amazon OpenSearch Service domains

AWS OFFICIALUpdated 3 years ago