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

Short description

To allow 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 allow or disallow in-place upgrades for an Amazon OpenSearch Service domain.

Before you perform an in-place upgrade or replacement upgrade, take note of the following factors:

• 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.

Resolution

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.

   -or-

   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.
   Parameters:
     ElasticsearchVersion:
       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.
     InstanceTypeForDataNode:
       Type: String
       Default: m3.medium.elasticsearch
       Description: The instance type for your data nodes.
     NumberOfDataNodes:
       Type: String
       Default: 1
       Description: The number of data nodes (instances) to use in the OpenSearch Service domain.
   Resources:
     ElasticSearchDomain:
       Type: AWS::Elasticsearch::Domain
       UpdatePolicy:
          EnableVersionUpgrade: true   ### In-place Upgrade
       Properties:
         ElasticsearchClusterConfig:
           InstanceCount: !Ref NumberOfDataNodes
           InstanceType: !Ref InstanceTypeForDataNode
         ElasticsearchVersion: !Ref ElasticsearchVersion

3. To update the stack for an in-place or replacement upgrade, use either the CloudFormation console or the AWS Command Line Interface (AWS CLI).

Related information

Upgrading Amazon OpenSearch Service domains