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

Last updated: 2020-04-23

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

Short Description

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

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

  • Amazon Elasticsearch Service (Amazon ES) supports in-place Elasticsearch upgrades for domains that are running version 5.1 or later.
  • If you change the value of the EngineVersion property during a stack update, then AWS CloudFormation performs a replacement update for an Elasticsearch domain and 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 Managing Amazon Elasticsearch Service Domains.

Resolution

1.    In your AWS CloudFormation stack template, add the EnableVersionUpgrade UpdatePolicy.

2.    To allow AWS 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 Elasticsearch 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 Elasticsearch 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 Amazon ES 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 complete the in-place upgrade or replacement upgrade process, update your stack using either the AWS CloudFormation console or AWS Command Line Interface (AWS CLI).


Did this article help you?

Anything we could improve?


Need more help?