Skip to content

Commit 4a03723

Browse files
pickypgpickypg
authored
Installation and Upgrade Documentation (elastic#1)
* Installation and Upgrade Documentation This provides the cross-stack documentation for the Elastic Stack, by linking to the other repos and providing the required order for a low-impact upgrade.
1 parent cbb1207 commit 4a03723

3 files changed

Lines changed: 239 additions & 0 deletions

File tree

‎docs/index.asciidoc‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
[[elastic-stack]]
2+
= Elastic Stack
3+
4+
:version: 5.0.0
5+
:major-version: 5.x
6+
:branch: 5.0
7+
:beatsref: https://www.elastic.co/guide/en/beats/libbeat/5.0
8+
:cloudref: https://www.elastic.co/guide/en/cloud/current
9+
:esref: https://www.elastic.co/guide/en/elasticsearch/reference/5.0
10+
:hadoopref: https://www.elastic.co/guide/en/elasticsearch/hadoop/5.0
11+
:kibanaref: https://www.elastic.co/guide/en/kibana/5.0
12+
:logstashref: https://www.elastic.co/guide/en/logstash/5.0
13+
:xpackref: https://www.elastic.co/guide/en/x-pack/5.0
14+
15+
include::installing-stack.asciidoc[]
16+
17+
include::upgrading-stack.asciidoc[]
18+
19+
The Elastic Stack is made up of multiple components developed by Elastic. In no particular
20+
order, these are:
21+
22+
* {beatsref}/index.html[Beats {branch}]
23+
* {esref}/index.html[Elasticsearch {branch}]
24+
* {hadoopref}/index.html[Elasticsearch Hadoop {branch}]
25+
* {kibanaref}/index.html[Kibana {branch}]
26+
* {logstashref}/index.html[Logstash {branch}]
27+
* {xpackref}/index.html[X-Pack {branch}]
28+

‎docs/installing-stack.asciidoc‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
[[installing-elastic-stack]]
2+
== Installing the Elastic Stack
3+
4+
This guide is intended for users seeking to install all or part of the Elastic Stack as part of
5+
clean or fresh installation. If you are upgrading, then please refer to <<upgrading-elastic-stack>>.
6+
7+
Beginning with 5.0, installing the Elastic Stack and understanding the compatibility between products
8+
has been dramatically simplified. All products are now part of a unified release process, so when
9+
any product is released, then all products are released with it. This helps to guarantee compatibility as
10+
well as avoid confusion surrounding version numbers.
11+
12+
As a result, when performing any Elastic Stack installation, you should always start with the same
13+
version across the entire stack. For example, if you select Elasticsearch 5.1.2, then you should also
14+
select Kibana 5.1.2, Logstash 5.1.2, and Beats 5.1.2.
15+
16+
[cols="2", options="header"]
17+
|===
18+
|Component |Version
19+
|Beats
20+
|{branch}
21+
|Elasticsearch
22+
|{branch}
23+
|Elasticsearch Hadoop
24+
|{branch}
25+
|Kibana
26+
|{branch}
27+
|Logstash
28+
|{branch}
29+
|X-Pack
30+
|{branch}
31+
|===
32+
33+
[[install-order-elastic-stack]]
34+
=== Installation Order
35+
36+
We recommend that you install the Elastic Stack in the following order.
37+
38+
1. Elasticsearch
39+
* X-Pack for Elasticsearch
40+
2. Kibana
41+
* X-Pack for Kibana
42+
3. Logstash
43+
4. Beats
44+
5. Elasticsearch Hadoop
45+
46+
This helps to ensure that the right parts of your infrastructure are running before other parts
47+
attempt to use them (e.g., Logstash sending data to Elasticsearch).
48+
49+
The table below lists the installation instructions, per component:
50+
51+
[cols="2", options="header"]
52+
|===
53+
|Product |Installation
54+
|Elasticsearch
55+
|{esref}/install-elasticsearch.html[Installing Elasticsearch 5.0]
56+
|X-Pack
57+
|{xpackref}/installing-xpack[Installing X-Pack 5.0]
58+
|Kibana
59+
|{kibanaref}/setup.html[Installing Kibana 5.0]
60+
|Logstash
61+
|{logstashref}/installing-logstash.html[Installing Logstash 5.0]
62+
|Beats
63+
|{beatsref}/installing-beats.html[Installing Beats 5.0]
64+
|Elasticsearch Hadoop
65+
|{hadoopref}/float.html[Installing Elasticsearch Hadoop 5.0]
66+
|===
67+
68+
[[install-elastic-stack-for-elastic-cloud]]
69+
=== Installing on the Elastic Cloud
70+
71+
The Elastic Cloud supports installing Elasticsearch 5.0, Kibana 5.0, and X-Pack 5.0. Unlike the
72+
above instructions, the Elastic Cloud handles the actual installation process as part of its
73+
managed service.
74+
75+
If you would like to trial Elasticsearch 5.0 using a fresh installation, then you can easily
76+
do so by {cloudref}/getting-started.html[running Elasticsearch in the Elastic Cloud].

‎docs/upgrading-stack.asciidoc‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
[[upgrading-elastic-stack]]
2+
== Upgrading the Elastic Stack
3+
4+
Before upgrading any component of the Elastic Stack, you should read through this guide to ensure
5+
that you upgrade in the right order and in the right way. When upgrading any component of the
6+
Elastic Stack, such as Beats, you should refer to the instructions for that component, including
7+
the breaking changes section.
8+
9+
Each component serves a particular role in the Elastic Stack. For some use cases, it is normal to
10+
not use every component in the Elastic Stack, for instance only using Elasticsearch, Logstash, and
11+
Kibana; Elasticsearch and Kibana; Elasticsearch and Beats; or just Elasticsearch.
12+
13+
[[upgrading-elastic-stack-audience]]
14+
=== Intended Audience
15+
16+
This guide is intended for existing users of the Elastic Stack, running specific version ranges of
17+
each component:
18+
19+
[cols="2", options="header"]
20+
|===
21+
|Component |Version
22+
|Beats
23+
|1.0 or later
24+
|Elasticsearch
25+
|2.0 or later
26+
|Kibana
27+
|4.2 or later
28+
|Logstash
29+
|2.0 or later
30+
|Hadoop
31+
|2.2 or later
32+
|Marvel, Shield, Watcher, Graph, Reporting <1>
33+
|2.0 or later
34+
|===
35+
1. Marvel, Shield, Watcher, Graph, and Reporting have all been combined into a new, unified plugin called
36+
X-Pack. Unlike before, the same X-Pack distribution works for both Elasticsearch and Kibana.
37+
38+
NOTE: Kibana 4.2 and Elasticsearch Hadoop 2.2 were the first versions that were compatible with
39+
Elasticsearch 2.x!
40+
41+
The spread of version numbers in the above table is the reason that the Elastic Stack is moving to
42+
a unified release number: 5.0. Beginning with 5.0, all of the components above will be released at the
43+
same time with the same version number. As such, you can choose a version with confidence across the
44+
entire stack.
45+
46+
It is critical to note that you cannot upgrade data that was written using Elasticsearch 1.x to
47+
Elasticsearch 2.x, then upgrade directly to Elasticsearch 5.x. Elasticsearch uses Lucene to store its
48+
data and Lucene is only compatible with the current version of Lucene, and one major release behind
49+
it. The Elasticsearch upgrade instructions do cover that path.
50+
51+
WARNING: This includes system indices, such as the `.kibana` index that is created by Kibana, and
52+
{esref}/modules-snapshots.html#modules-snapshots[snapshots of indices from Elasticsearch 1.x]!
53+
54+
[cols="3", options="header"]
55+
|===
56+
|Elasticsearch Version |Lucene Version| Path
57+
|5.x |6.x | {esref}/rolling-upgrades.html[Rolling Upgrade]
58+
|2.x |5.x | {esref}/restart-upgrade.html[Full Cluster Restart Upgrade] <1>
59+
|1.x |4.x | {esref}/reindex-upgrade.html[Reindexing Required]
60+
|===
61+
1. Some features require reindexing to take advantage of them, such as Lucene's new Block KD tree support.
62+
63+
When upgrading from two major releases ago, it is important to read the breaking changes from
64+
1.x to 2.x, as well as from 2.x to 5.x!
65+
66+
[[upgrade-order-elastic-stack]]
67+
=== Upgrade Order
68+
69+
As noted above, this only applies for users of Beats 1.x, Elasticsearch 2.x, Logstash 2.x, and
70+
Kibana 4.2+. For Elasticsearch in particular, it is critical to run the
71+
https://github.com/elastic/elasticsearch-migration/[Elasticsearch Migration Plugin] prior to
72+
any upgrade to verify upgrade compatibility!
73+
74+
To maintain the most compatibility, you must upgrade the stack in the recommended order. You
75+
may skip any components that you do not use in your own system. The upgrade requires a full
76+
cluster shutdown for both Elasicsearch and Kibana because neither Elasticsearch 5.0, nor Kibana 5.0,
77+
can communicate with earlier versions of Elasticsearch.
78+
79+
1. Elasticsearch Hadoop (can talk to Elasticsearch 5.0 and 2.x)
80+
2. Elasticsearch
81+
* X-Pack for Elasticsearch (combines Marvel Agent, Shield, Watcher, and Graph)
82+
3. Kibana (now includes Timelion and Console, formerly known as Sense)
83+
* X-Pack for Kibana (combines Marvel, Shield, Graph, and Reporting)
84+
4. Logstash
85+
5. Beats
86+
87+
Elasticsearch Hadoop versions prior to 5.0 are not compatible with Elasticsearch 5.0, but Elasticsearch
88+
Hadoop 5.0 is compatible with Elasticsearch 2.0 and Elasticsearch 5.0.
89+
90+
Logstash 2.0+ and Beats 1.0+ are compatible with both Elasticsearch 2.0+ and Elasticsearch 5.0. This
91+
provides flexibility in when you schedule the upgrades for each Logstash instance and Beats agent.
92+
93+
By following the above order, you should upgrade Elasticsearch Hadoop first; then Elasticsearch
94+
by performing a full cluster restart and upgrade; then install X-Pack; then upgrade Kibana immediately
95+
afterward by restarting and upgrading all instances of Kibana; then installing X-Pack there as well.
96+
Afterward, you can choose when it makes the most sense to upgrade Logstash and Beats for your architecture. It is worth
97+
upgrading Logstash and Beats as soon as possible to take advantage of performance improvements
98+
and other enhancements.
99+
100+
The following table lists the upgrade instructions and breaking changes for each component. Before
101+
upgrading, make sure you read through the upgrade guide and breaking changes list for every component
102+
that you are upgrading.
103+
104+
[cols="3", options="header"]
105+
|===
106+
|component |Breaking Changes |Upgrade
107+
|Elasticsearch
108+
|{esref}/breaking-changes.html[Breaking Changes from 2.x]
109+
|{esref}/setup-upgrade.html[Upgrading to Elasticsearch 5.0]
110+
|X-Pack
111+
|{xpackref}/breaking-changes.html[Breaking Changes from 2.x]
112+
|{xpackref}/setup-upgrade.html[Upgrading to X-Pack 5.0]
113+
|Kibana
114+
|{kibanaref}/breaking-changes.html[Breaking Changes from 4.x]
115+
|{kibanaref}/upgrading-kibana.html[Upgrading to Kibana 5.0]
116+
|Logstash
117+
|{logstashref}/breaking-changes.html[Breaking Changes from 2.x]
118+
|{logstashref}/upgrading-logstash.html[Upgrading to Logstash 5.0]
119+
|Beats
120+
|{beatsref}/breaking-changes.html[Breaking Changes from 1.x]
121+
|{beatsref}/upgrading.html[Upgrading to Beats 5.0]
122+
|Elasticsearch Hadoop
123+
|{hadoopref}/breaking-changes.html[Breaking Changes from 2.x]
124+
|{hadoopref}/install.html[Upgrading to Elasticsearch Hadoop 5.0]
125+
|===
126+
127+
[[upgrade-elastic-stack-for-elastic-cloud]]
128+
=== Upgrading on the Elastic Cloud
129+
130+
The Elastic Cloud supports upgrading to Elasticsearch 5.0, Kibana 5.0, and X-Pack 5.0. Unlike the above
131+
instructions, the Elastic Cloud handles the actual upgrade process as part of its managed service,
132+
which means that you only need to be worried about breaking changes.
133+
134+
You can read more about the
135+
{cloudref}/_upgrading_to_elasticsearch_5_0.html[Elastic Cloud upgrade process here].

0 commit comments

Comments
 (0)