- Elasticsearch Guide: other versions:
- Elasticsearch introduction
- Getting started with Elasticsearch
- Set up Elasticsearch
- Installing Elasticsearch
- Configuring Elasticsearch
- Important Elasticsearch configuration
- Important System Configuration
- Bootstrap Checks
- Heap size check
- File descriptor check
- Memory lock check
- Maximum number of threads check
- Max file size check
- Maximum size virtual memory check
- Maximum map count check
- Client JVM check
- Use serial collector check
- System call filter check
- OnError and OnOutOfMemoryError checks
- Early-access check
- G1GC check
- All permission check
- Discovery configuration check
- Starting Elasticsearch
- Stopping Elasticsearch
- Adding nodes to your cluster
- Set up X-Pack
- Configuring X-Pack Java Clients
- Bootstrap Checks for X-Pack
- Upgrade Elasticsearch
- API conventions
- Document APIs
- Search APIs
- Aggregations
- Metrics Aggregations
- Avg Aggregation
- Weighted Avg Aggregation
- Cardinality Aggregation
- Extended Stats Aggregation
- Geo Bounds Aggregation
- Geo Centroid Aggregation
- Max Aggregation
- Min Aggregation
- Percentiles Aggregation
- Percentile Ranks Aggregation
- Scripted Metric Aggregation
- Stats Aggregation
- Sum Aggregation
- Top Hits Aggregation
- Value Count Aggregation
- Median Absolute Deviation Aggregation
- Bucket Aggregations
- Adjacency Matrix Aggregation
- Auto-interval Date Histogram Aggregation
- Children Aggregation
- Composite Aggregation
- Date Histogram Aggregation
- Date Range Aggregation
- Diversified Sampler Aggregation
- Filter Aggregation
- Filters Aggregation
- Geo Distance Aggregation
- GeoHash grid Aggregation
- GeoTile Grid Aggregation
- Global Aggregation
- Histogram Aggregation
- IP Range Aggregation
- Missing Aggregation
- Nested Aggregation
- Parent Aggregation
- Range Aggregation
- Reverse nested Aggregation
- Sampler Aggregation
- Significant Terms Aggregation
- Significant Text Aggregation
- Terms Aggregation
- Pipeline Aggregations
- Avg Bucket Aggregation
- Derivative Aggregation
- Max Bucket Aggregation
- Min Bucket Aggregation
- Sum Bucket Aggregation
- Stats Bucket Aggregation
- Extended Stats Bucket Aggregation
- Percentiles Bucket Aggregation
- Moving Average Aggregation
- Moving Function Aggregation
- Cumulative Sum Aggregation
- Bucket Script Aggregation
- Bucket Selector Aggregation
- Bucket Sort Aggregation
- Serial Differencing Aggregation
- Matrix Aggregations
- Caching heavy aggregations
- Returning only aggregation results
- Aggregation Metadata
- Returning the type of the aggregation
- Metrics Aggregations
- Indices APIs
- Create Index
- Delete Index
- Get Index
- Indices Exists
- Open / Close Index API
- Shrink Index
- Split Index
- Rollover Index
- Put Mapping
- Get Mapping
- Get Field Mapping
- Types Exists
- Index Aliases
- Update Indices Settings
- Get Settings
- Analyze
- Index Templates
- Indices Stats
- Indices Segments
- Indices Recovery
- Indices Shard Stores
- Clear Cache
- Flush
- Refresh
- Force Merge
- cat APIs
- Cluster APIs
- Query DSL
- Scripting
- Mapping
- Analysis
- Anatomy of an analyzer
- Testing analyzers
- Analyzers
- Normalizers
- Tokenizers
- Standard Tokenizer
- Letter Tokenizer
- Lowercase Tokenizer
- Whitespace Tokenizer
- UAX URL Email Tokenizer
- Classic Tokenizer
- Thai Tokenizer
- NGram Tokenizer
- Edge NGram Tokenizer
- Keyword Tokenizer
- Pattern Tokenizer
- Char Group Tokenizer
- Simple Pattern Tokenizer
- Simple Pattern Split Tokenizer
- Path Hierarchy Tokenizer
- Path Hierarchy Tokenizer Examples
- Token Filters
- ASCII Folding Token Filter
- Flatten Graph Token Filter
- Length Token Filter
- Lowercase Token Filter
- Uppercase Token Filter
- NGram Token Filter
- Edge NGram Token Filter
- Porter Stem Token Filter
- Shingle Token Filter
- Stop Token Filter
- Word Delimiter Token Filter
- Word Delimiter Graph Token Filter
- Multiplexer Token Filter
- Conditional Token Filter
- Predicate Token Filter Script
- Stemmer Token Filter
- Stemmer Override Token Filter
- Keyword Marker Token Filter
- Keyword Repeat Token Filter
- KStem Token Filter
- Snowball Token Filter
- Phonetic Token Filter
- Synonym Token Filter
- Parsing synonym files
- Synonym Graph Token Filter
- Compound Word Token Filters
- Reverse Token Filter
- Elision Token Filter
- Truncate Token Filter
- Unique Token Filter
- Pattern Capture Token Filter
- Pattern Replace Token Filter
- Trim Token Filter
- Limit Token Count Token Filter
- Hunspell Token Filter
- Common Grams Token Filter
- Normalization Token Filter
- CJK Width Token Filter
- CJK Bigram Token Filter
- Delimited Payload Token Filter
- Keep Words Token Filter
- Keep Types Token Filter
- Exclude mode settings example
- Classic Token Filter
- Apostrophe Token Filter
- Decimal Digit Token Filter
- Fingerprint Token Filter
- MinHash Token Filter
- Remove Duplicates Token Filter
- Character Filters
- Modules
- Index modules
- Ingest node
- Pipeline Definition
- Ingest APIs
- Accessing Data in Pipelines
- Conditional Execution in Pipelines
- Handling Failures in Pipelines
- Processors
- Append Processor
- Bytes Processor
- Convert Processor
- Date Processor
- Date Index Name Processor
- Dissect Processor
- Dot Expander Processor
- Drop Processor
- Fail Processor
- Foreach Processor
- GeoIP Processor
- Grok Processor
- Gsub Processor
- HTML Strip Processor
- Join Processor
- JSON Processor
- KV Processor
- Lowercase Processor
- Pipeline Processor
- Remove Processor
- Rename Processor
- Script Processor
- Set Processor
- Set Security User Processor
- Split Processor
- Sort Processor
- Trim Processor
- Uppercase Processor
- URL Decode Processor
- User Agent processor
- Managing the index lifecycle
- Getting started with index lifecycle management
- Policy phases and actions
- Set up index lifecycle management policy
- Using policies to manage index rollover
- Update policy
- Index lifecycle error handling
- Restoring snapshots of managed indices
- Start and stop index lifecycle management
- Using ILM with existing indices
- SQL access
- Overview
- Getting Started with SQL
- Conventions and Terminology
- Security
- SQL REST API
- SQL Translate API
- SQL CLI
- SQL JDBC
- SQL ODBC
- SQL Client Applications
- SQL Language
- Functions and Operators
- Comparison Operators
- Logical Operators
- Math Operators
- Cast Operators
- LIKE and RLIKE Operators
- Aggregate Functions
- Grouping Functions
- Date/Time and Interval Functions and Operators
- Full-Text Search Functions
- Mathematical Functions
- String Functions
- Type Conversion Functions
- Geo Functions
- Conditional Functions And Expressions
- System Functions
- Reserved keywords
- SQL Limitations
- Monitor a cluster
- Frozen indices
- Set up a cluster for high availability
- Roll up or transform your data
- X-Pack APIs
- Info API
- Cross-cluster replication APIs
- Explore API
- Freeze index
- Index lifecycle management API
- Licensing APIs
- Machine learning APIs
- Add events to calendar
- Add jobs to calendar
- Close jobs
- Create jobs
- Create calendar
- Create datafeeds
- Create filter
- Delete calendar
- Delete datafeeds
- Delete events from calendar
- Delete filter
- Delete forecast
- Delete jobs
- Delete jobs from calendar
- Delete model snapshots
- Delete expired data
- Find file structure
- Flush jobs
- Forecast jobs
- Get calendars
- Get buckets
- Get overall buckets
- Get categories
- Get datafeeds
- Get datafeed statistics
- Get influencers
- Get jobs
- Get job statistics
- Get machine learning info
- Get model snapshots
- Get scheduled events
- Get filters
- Get records
- Open jobs
- Post data to jobs
- Preview datafeeds
- Revert model snapshots
- Set upgrade mode
- Start datafeeds
- Stop datafeeds
- Update datafeeds
- Update filter
- Update jobs
- Update model snapshots
- Migration APIs
- Rollup APIs
- Security APIs
- Authenticate
- Change passwords
- Clear cache
- Clear roles cache
- Create API keys
- Create or update application privileges
- Create or update role mappings
- Create or update roles
- Create or update users
- Delete application privileges
- Delete role mappings
- Delete roles
- Delete users
- Disable users
- Enable users
- Get API key information
- Get application privileges
- Get role mappings
- Get roles
- Get token
- Get users
- Has privileges
- Invalidate API key
- Invalidate token
- OpenID Connect Prepare Authentication API
- OpenID Connect Authenticate API
- OpenID Connect Logout API
- SSL certificate
- Transform APIs
- Unfreeze index
- Watcher APIs
- Definitions
- Secure a cluster
- Overview
- Configuring security
- Encrypting communications in Elasticsearch
- Encrypting communications in an Elasticsearch Docker Container
- Enabling cipher suites for stronger encryption
- Separating node-to-node and client traffic
- Configuring an Active Directory realm
- Configuring a file realm
- Configuring an LDAP realm
- Configuring a native realm
- Configuring a PKI realm
- Configuring a SAML realm
- Configuring a Kerberos realm
- Security files
- FIPS 140-2
- How security works
- User authentication
- Built-in users
- Internal users
- Token-based authentication services
- Realms
- Realm chains
- Active Directory user authentication
- File-based user authentication
- LDAP user authentication
- Native user authentication
- OpenID Connect authentication
- PKI user authentication
- SAML authentication
- Kerberos authentication
- Integrating with other authentication systems
- Enabling anonymous access
- Controlling the user cache
- Configuring SAML single-sign-on on the Elastic Stack
- Configuring single sign-on to the Elastic Stack using OpenID Connect
- User authorization
- Auditing security events
- Encrypting communications
- Restricting connections with IP filtering
- Cross cluster search, clients, and integrations
- Tutorial: Getting started with security
- Tutorial: Encrypting communications
- Troubleshooting
- Some settings are not returned via the nodes settings API
- Authorization exceptions
- Users command fails due to extra arguments
- Users are frequently locked out of Active Directory
- Certificate verification fails for curl on Mac
- SSLHandshakeException causes connections to fail
- Common SSL/TLS exceptions
- Common Kerberos exceptions
- Common SAML issues
- Internal Server Error in Kibana
- Setup-passwords command fails due to connection failure
- Failures due to relocation of the configuration files
- Limitations
- Alerting on cluster and index events
- Command line tools
- How To
- Testing
- Glossary of terms
- Release highlights
- Breaking changes
- Release notes
- Elasticsearch version 7.2.1
- Elasticsearch version 7.2.0
- Elasticsearch version 7.1.1
- Elasticsearch version 7.1.0
- Elasticsearch version 7.0.0
- Elasticsearch version 7.0.0-rc2
- Elasticsearch version 7.0.0-rc1
- Elasticsearch version 7.0.0-beta1
- Elasticsearch version 7.0.0-alpha2
- Elasticsearch version 7.0.0-alpha1
Rolling upgrades
editRolling upgrades
editA rolling upgrade allows an Elasticsearch cluster to be upgraded one node at a time so upgrading does not interrupt service. Running multiple versions of Elasticsearch in the same cluster beyond the duration of an upgrade is not supported, as shards cannot be replicated from upgraded nodes to nodes running the older version.
It is best to upgrade the master-eligible nodes in your cluster after all of the other nodes. Once you have started to upgrade the master-eligible nodes they may form a cluster that nodes of older versions cannot join. If you upgrade the master-eligible nodes last then all the other nodes will not be running an older version and so they will be able to join the cluster.
Rolling upgrades are supported:
- Between minor versions
- From 5.6 to 6.8
- From 6.8 to 7.2.1
Upgrading directly to 7.2.1 from 6.7 or earlier requires a full cluster restart.
Preparing to upgrade
editIt is important to prepare carefully before starting an upgrade. Once you have started to upgrade your cluster to version 7.2.1 you must complete the upgrade. As soon as the cluster contains nodes of version 7.2.1 it may make changes to its internal state that cannot be reverted. If you cannot complete the upgrade then you should discard the partially-upgraded cluster, deploy an empty cluster of the version before the upgrade, and restore its contents from a snapshot.
Before you start to upgrade your cluster to version 7.2.1 you should do the following.
- Check the deprecation log to see if you are using any deprecated features and update your code accordingly.
- Review the breaking changes and make any necessary changes to your code and configuration for version 7.2.1.
- If you use any plugins, make sure there is a version of each plugin that is compatible with Elasticsearch version 7.2.1.
- Test the upgrade in an isolated environment before upgrading your production cluster.
- Back up your data by taking a snapshot!
Upgrading your cluster
editTo perform a rolling upgrade to 7.2.1:
-
Disable shard allocation.
When you shut down a node, the allocation process waits for
index.unassigned.node_left.delayed_timeout
(by default, one minute) before starting to replicate the shards on that node to other nodes in the cluster, which can involve a lot of I/O. Since the node is shortly going to be restarted, this I/O is unnecessary. You can avoid racing the clock by disabling allocation of replicas before shutting down the node:PUT _cluster/settings { "persistent": { "cluster.routing.allocation.enable": "primaries" } }
-
Stop non-essential indexing and perform a synced flush. (Optional)
While you can continue indexing during the upgrade, shard recovery is much faster if you temporarily stop non-essential indexing and perform a synced-flush.
POST _flush/synced
When you perform a synced flush, check the response to make sure there are no failures. Synced flush operations that fail due to pending indexing operations are listed in the response body, although the request itself still returns a 200 OK status. If there are failures, reissue the request.
-
Temporarily stop the tasks associated with active machine learning jobs and datafeeds. (Optional)
If your machine learning indices were created before 6.x, you must reindex the indices.
If your machine learning indices were created in 6.x, you can:
- Leave your machine learning jobs running during the upgrade. When you shut down a machine learning node, its jobs automatically move to another node and restore the model states. This option enables your jobs to continue running during the upgrade but it puts increased load on the cluster.
-
Temporarily halt the tasks associated with your machine learning jobs and datafeeds and prevent new jobs from opening by using the set upgrade mode API:
POST _ml/set_upgrade_mode?enabled=true
When you disable upgrade mode, the jobs resume using the last model state that was automatically saved. This option avoids the overhead of managing active jobs during the upgrade and is faster than explicitly stopping datafeeds and closing jobs.
- Stop all datafeeds and close all jobs. This option saves the model state at the time of closure. When you reopen the jobs after the upgrade, they use the exact same model. However, saving the latest model state takes longer than using upgrade mode, especially if you have a lot of jobs or jobs with large model states.
-
-
If you are running Elasticsearch with
systemd
:sudo systemctl stop elasticsearch.service
-
If you are running Elasticsearch with SysV
init
:sudo -i service elasticsearch stop
-
If you are running Elasticsearch as a daemon:
kill $(cat pid)
-
-
Upgrade the node you shut down.
To upgrade using a Debian or RPM package:
-
Use
rpm
ordpkg
to install the new package. All files are installed in the appropriate location for the operating system and Elasticsearch config files are not overwritten.
To upgrade using a zip or compressed tarball:
-
Extract the zip or tarball to a new directory. This is critical if you
are not using external
config
anddata
directories. -
Set the
ES_PATH_CONF
environment variable to specify the location of your externalconfig
directory andjvm.options
file. If you are not using an externalconfig
directory, copy your old configuration over to the new installation. -
Set
path.data
inconfig/elasticsearch.yml
to point to your external data directory. If you are not using an externaldata
directory, copy your old data directory over to the new installation.If you use monitoring features, re-use the data directory when you upgrade Elasticsearch. Monitoring identifies unique Elasticsearch nodes by using the persistent UUID, which is stored in the data directory.
-
Set
path.logs
inconfig/elasticsearch.yml
to point to the location where you want to store your logs. If you do not specify this setting, logs are stored in the directory you extracted the archive to.
When you extract the zip or tarball packages, the
elasticsearch-n.n.n
directory contains the Elasticsearchconfig
,data
,logs
andplugins
directories.We recommend moving these directories out of the Elasticsearch directory so that there is no chance of deleting them when you upgrade Elasticsearch. To specify the new locations, use the
ES_PATH_CONF
environment variable and thepath.data
andpath.logs
settings. For more information, see Important Elasticsearch configuration.The Debian and RPM packages place these directories in the appropriate place for each operating system. In production, we recommend installing using the deb or rpm package.
You should leave
cluster.initial_master_nodes
unset while performing a rolling upgrade. Each upgraded node is joining an existing cluster so there is no need for cluster bootstrapping. You must configure eitherdiscovery.seed_hosts
ordiscovery.seed_providers
on every node. -
Use
-
Upgrade any plugins.
Use the
elasticsearch-plugin
script to install the upgraded version of each installed Elasticsearch plugin. All plugins must be upgraded when you upgrade a node. - If you use Elasticsearch security features to define realms, verify that your realm settings are up-to-date. The format of realm settings changed in version 7.0, in particular, the placement of the realm type changed. See Realm settings.
-
Start the upgraded node.
Start the newly-upgraded node and confirm that it joins the cluster by checking the log file or by submitting a
_cat/nodes
request:GET _cat/nodes
-
Reenable shard allocation.
Once the node has joined the cluster, remove the
cluster.routing.allocation.enable
setting to enable shard allocation and start using the node:PUT _cluster/settings { "persistent": { "cluster.routing.allocation.enable": null } }
-
Wait for the node to recover.
Before upgrading the next node, wait for the cluster to finish shard allocation. You can check progress by submitting a
_cat/health
request:GET _cat/health?v
Wait for the
status
column to switch fromyellow
togreen
. Once the node isgreen
, all primary and replica shards have been allocated.During a rolling upgrade, primary shards assigned to a node running the new version cannot have their replicas assigned to a node with the old version. The new version might have a different data format that is not understood by the old version.
If it is not possible to assign the replica shards to another node (there is only one upgraded node in the cluster), the replica shards remain unassigned and status stays
yellow
.In this case, you can proceed once there are no initializing or relocating shards (check the
init
andrelo
columns).As soon as another node is upgraded, the replicas can be assigned and the status will change to
green
.Shards that were not sync-flushed might take longer to recover. You can monitor the recovery status of individual shards by submitting a
_cat/recovery
request:GET _cat/recovery
If you stopped indexing, it is safe to resume indexing as soon as recovery completes.
-
Repeat
When the node has recovered and the cluster is stable, repeat these steps for each node that needs to be updated.
-
Restart machine learning jobs.
If you temporarily halted the tasks associated with your machine learning jobs, use the set upgrade mode API to return them to active states:
POST _ml/set_upgrade_mode?enabled=false
If you closed all machine learning jobs before the upgrade, open the jobs and start the datafeeds from Kibana or with the open jobs and start datafeed APIs.
During a rolling upgrade, the cluster continues to operate normally. However, any new functionality is disabled or operates in a backward compatible mode until all nodes in the cluster are upgraded. New functionality becomes operational once the upgrade is complete and all nodes are running the new version. Once that has happened, there’s no way to return to operating in a backward compatible mode. Nodes running the previous major version will not be allowed to join the fully-updated cluster.
In the unlikely case of a network malfunction during the upgrade process that isolates all remaining old nodes from the cluster, you must take the old nodes offline and upgrade them to enable them to join the cluster.
If you stop half or more of the master-eligible nodes all at once during the upgrade then the cluster will become unavailable, meaning that the upgrade is no longer a rolling upgrade. If this happens, you should upgrade and restart all of the stopped master-eligible nodes to allow the cluster to form again, as if performing a full-cluster restart upgrade. It may also be necessary to upgrade all of the remaining old nodes before they can join the cluster after it re-forms.
On this page