|
|
@@ -204,205 +204,105 @@ the nodes in your cluster.
|
|
|
[[docker-compose-file]]
|
|
|
==== Start a multi-node cluster with Docker Compose
|
|
|
|
|
|
-When defining multiple nodes in a `docker-compose.yml` file, you'll need to
|
|
|
-explicitly enable and configure security so that {es} doesn't try to generate a
|
|
|
-password for the `elastic` user on every node.
|
|
|
+To get a multi-node {es} cluster and {kib} up and running in Docker with
|
|
|
+security enabled, you can use Docker Compose.
|
|
|
|
|
|
-===== Prepare the environment
|
|
|
+This configuration provides a simple method of starting a secured cluster that
|
|
|
+you can use for development before building a distributed deployment with
|
|
|
+multiple hosts.
|
|
|
|
|
|
-The following example uses Docker Compose to start a three-node {es} cluster.
|
|
|
-Create each of the following files inside of a new directory. Copy and paste the
|
|
|
-contents of each example into the appropriate file as described in the
|
|
|
-following sections:
|
|
|
+===== Prerequisites
|
|
|
|
|
|
-* <<docker-instances-yml,`instances.yml`>>
|
|
|
-* <<docker-env,`.env`>>
|
|
|
-* <<docker-create-certs,`create-certs.yml`>>
|
|
|
-* <<docker-docker-compose,`docker-compose.yml`>>
|
|
|
+Install the appropriate https://docs.docker.com/get-docker/[Docker application]
|
|
|
+for your operating system.
|
|
|
|
|
|
-[[docker-instances-yml]]
|
|
|
-[discrete]
|
|
|
-===== `instances.yml`
|
|
|
+If you're running on Linux, install https://docs.docker.com/compose/install/[Docker Compose].
|
|
|
|
|
|
-When you run the example, {es} uses this file to create a three-node cluster.
|
|
|
-The nodes are named `es01`, `es02`,and `es03`.
|
|
|
+[NOTE]
|
|
|
+====
|
|
|
+Make sure that Docker is allotted at least 4GB of memory. In Docker Desktop,
|
|
|
+you configure resource usage on the Advanced tab in Preferences (macOS) or
|
|
|
+Settings (Windows).
|
|
|
+====
|
|
|
|
|
|
-ifeval::["{release-state}"=="unreleased"]
|
|
|
---
|
|
|
-WARNING: Version {version} of {es} has not yet been released, so a
|
|
|
-`docker-compose.yml` is not available for this version.
|
|
|
+===== Prepare the environment
|
|
|
|
|
|
-endif::[]
|
|
|
+Create the following configuration files in a new, empty directory. These files
|
|
|
+are also available from the
|
|
|
+https://github.com/elastic/elasticsearch/tree/master/docs/reference/setup/install[elasticsearch]
|
|
|
+repository on GitHub.
|
|
|
|
|
|
-ifeval::["{release-state}"!="unreleased"]
|
|
|
-[source,yaml,subs="attributes"]
|
|
|
-----
|
|
|
-include::instances.yml[]
|
|
|
-----
|
|
|
-endif::[]
|
|
|
--
|
|
|
-
|
|
|
-[[docker-env]]
|
|
|
-[discrete]
|
|
|
-===== `.env`
|
|
|
-
|
|
|
-The `.env` file sets environment variables that are used when you run the
|
|
|
-example. Ensure that you specify a strong password for the `elastic` user with
|
|
|
-the `ELASTIC_PASSWORD` variable. This variable is referenced by the
|
|
|
-`docker-compose.yml` file.
|
|
|
-
|
|
|
ifeval::["{release-state}"=="unreleased"]
|
|
|
---
|
|
|
-WARNING: Version {version} of {es} has not yet been released, so a
|
|
|
-`docker-compose.yml` is not available for this version.
|
|
|
-
|
|
|
-endif::[]
|
|
|
-
|
|
|
-ifeval::["{release-state}"!="unreleased"]
|
|
|
-[source,yaml,subs="attributes"]
|
|
|
-----
|
|
|
-include::.env[]
|
|
|
-----
|
|
|
+NOTE: Version {version} of {es} has not been released,
|
|
|
+so the sample Docker Compose and configuration files are not yet available for
|
|
|
+this version. See the {stack-gs-current}/get-started-docker.html[current version]
|
|
|
+for the latest sample files.
|
|
|
endif::[]
|
|
|
--
|
|
|
|
|
|
-`COMPOSE_PROJECT_NAME`:: Adds an `es_` prefix for all volumes and networks
|
|
|
-created by `docker-compose`.
|
|
|
-
|
|
|
-`CERTS_DIR`:: Specifies the path inside the Docker image where {es} expects the
|
|
|
-security certificates.
|
|
|
-
|
|
|
-`ELASTIC_PASSWORD`:: Sets the initial password for the `elastic` user.
|
|
|
+--
|
|
|
+ifeval::["{release-state}"!="unreleased"]
|
|
|
|
|
|
[discrete]
|
|
|
-[[docker-create-certs]]
|
|
|
-===== `create-certs.yml`
|
|
|
-
|
|
|
-The `create-certs.yml` file includes a script that generates node certificates
|
|
|
-and a certificate authority (CA) certificate and key where {es} expects them.
|
|
|
-These certificates and key are placed in a Docker volume named `es_certs`.
|
|
|
-
|
|
|
-ifeval::["{release-state}"=="unreleased"]
|
|
|
---
|
|
|
-WARNING: Version {version} of {es} has not yet been released, so a
|
|
|
-`docker-compose.yml` is not available for this version.
|
|
|
+[[docker-env-file]]
|
|
|
+===== `.env`
|
|
|
|
|
|
-endif::[]
|
|
|
+The `.env` file sets environment variables that are used when you run the
|
|
|
+`docker-compose.yml` configuration file. Ensure that you specify a strong
|
|
|
+password for the `elastic` and `kibana_system` users with the
|
|
|
+`ELASTIC_PASSWORD` and `KIBANA_PASSWORD` variables. These variable are
|
|
|
+referenced by the `docker-compose.yml` file.
|
|
|
|
|
|
-ifeval::["{release-state}"!="unreleased"]
|
|
|
-[source,yaml,subs="attributes"]
|
|
|
+["source","txt",subs="attributes"]
|
|
|
----
|
|
|
-include::create-certs.yml[]
|
|
|
+include::.env[]
|
|
|
----
|
|
|
-endif::[]
|
|
|
---
|
|
|
|
|
|
-[[docker-docker-compose]]
|
|
|
[discrete]
|
|
|
+[[docker-file]]
|
|
|
===== `docker-compose.yml`
|
|
|
|
|
|
-The `docker-compose.yml` file defines configuration settings for each of your
|
|
|
-{es} nodes.
|
|
|
-
|
|
|
-NOTE: This sample `docker-compose.yml` file uses the `ES_JAVA_OPTS`
|
|
|
-environment variable to manually set the heap size to 512MB. We do not recommend
|
|
|
-using `ES_JAVA_OPTS` in production.
|
|
|
-See <<docker-set-heap-size,manually set the heap size>>.
|
|
|
-
|
|
|
-This configuration exposes port `9200` on all network interfaces. Given how
|
|
|
-Docker manipulates `iptables` on Linux, this means that your {es} cluster is
|
|
|
-publicly accessible, potentially ignoring any firewall settings. If you don't
|
|
|
-want to expose port `9200` and instead use a reverse proxy, replace `9200:9200`
|
|
|
-with `127.0.0.1:9200:9200` in the `docker-compose.yml` file. {es} will then only
|
|
|
-be accessible from the host machine itself.
|
|
|
+This `docker-compose.yml` file creates a three-node secure {es} cluster with authentication and network encryption enabled, and a {kib} instance securely connected to it.
|
|
|
|
|
|
-ifeval::["{release-state}"=="unreleased"]
|
|
|
---
|
|
|
-WARNING: Version {version} of {es} has not yet been released, so a
|
|
|
-`docker-compose.yml` is not available for this version.
|
|
|
-
|
|
|
-endif::[]
|
|
|
+.Exposing ports
|
|
|
+****
|
|
|
+This configuration exposes port `9200` on all network interfaces. Because
|
|
|
+of how Docker handles ports, a port that isn't bound to `localhost` leaves your
|
|
|
+{es} cluster publicly accessible, potentially ignoring any firewall settings.
|
|
|
+If you don't want to expose port `9200` to external hosts, set the value for
|
|
|
+`ES_PORT` in the `.env` file to something like `127.0.0.1:9200`. {es} will
|
|
|
+then only be accessible from the host machine itself.
|
|
|
+****
|
|
|
|
|
|
-ifeval::["{release-state}"!="unreleased"]
|
|
|
[source,yaml,subs="attributes"]
|
|
|
----
|
|
|
include::docker-compose.yml[]
|
|
|
----
|
|
|
+
|
|
|
endif::[]
|
|
|
--
|
|
|
|
|
|
===== Start your cluster with security enabled and configured
|
|
|
|
|
|
-This sample Docker Compose file starts a three-node {es} cluster.
|
|
|
-
|
|
|
-The https://docs.docker.com/storage/volumes[Docker named volumes]
|
|
|
-`data01`, `data02`, and `data03` store the node data directories so that the
|
|
|
-data persists across restarts. If they don't already exist, running
|
|
|
-`docker-compose` creates these volumes.
|
|
|
-
|
|
|
-[[docker-generate-certificates]]
|
|
|
-. Generate the certificates. You only need to run this command one time:
|
|
|
+. Modify the `.env` file and enter strong password values for both the
|
|
|
+`ELASTIC_PASSWORD` and `KIBANA_PASSWORD` variables.
|
|
|
+
|
|
|
-["source","sh"]
|
|
|
-----
|
|
|
-docker-compose -f create-certs.yml run --rm create_certs
|
|
|
-----
|
|
|
+NOTE: You must use the `ELASTIC_PASSWORD` value for further interactions with
|
|
|
+the cluster. The `KIBANA_PASSWORD` value is only used internally when
|
|
|
+configuring {kib}.
|
|
|
|
|
|
-. Start your {es} nodes with TLS configured on the transport layer:
|
|
|
+. Create and start the three-node {es} cluster and {kib} instance:
|
|
|
+
|
|
|
["source","sh"]
|
|
|
----
|
|
|
docker-compose up -d
|
|
|
----
|
|
|
-+
|
|
|
-Node `es01` listens on `localhost:9200` and `es02` and `es03` talk to `es01`
|
|
|
-over a Docker network.
|
|
|
-
|
|
|
-. Access the {es} API over TLS using the bootstrapped password for the `elastic`
|
|
|
-user that you specified in the `.env` file:
|
|
|
-+
|
|
|
-["source","sh",subs="attributes"]
|
|
|
-----
|
|
|
-docker run --rm -v es_certs:/certs --network=es_default {docker-image} curl --cacert /certs/ca/ca.crt -u elastic:<password> https://es01:9200
|
|
|
-----
|
|
|
-// NOTCONSOLE
|
|
|
-+
|
|
|
---
|
|
|
-`es_certs`:: The name of the volume that the script in `create-certs.yml`
|
|
|
-creates to hold your certificates.
|
|
|
|
|
|
-`<password>`:: The password for the `elastic` user, defined by the
|
|
|
-`ELASTIC_PASSWORD` variable in the `.env` file.
|
|
|
---
|
|
|
+. When the deployment has started, open a browser and navigate to http://localhost:5601[http://localhost:5601] to
|
|
|
+access {kib}, where you can load sample data and interact with your cluster.
|
|
|
|
|
|
-. Submit a `_cat/nodes` request to check that the nodes are up and running:
|
|
|
-+
|
|
|
-[source,sh]
|
|
|
-----
|
|
|
-curl -X GET "https://localhost:9200/_cat/nodes?v=true&pretty"
|
|
|
-----
|
|
|
-// NOTCONSOLE
|
|
|
-
|
|
|
-Log messages go to the console and are handled by the configured Docker logging
|
|
|
-driver. By default, you can access logs with `docker logs`. If you prefer that
|
|
|
-the {es} container write logs to disk, set the `ES_LOG_STYLE` environment
|
|
|
-variable to `file`. This causes {es} to use the same logging configuration as
|
|
|
-other {es} distribution formats.
|
|
|
-
|
|
|
-If you need to generate a new password for the `elastic` user or any of the
|
|
|
-built-in users, use the `elasticsearch-reset-password` tool:
|
|
|
-
|
|
|
-WARNING: Windows users not running PowerShell must remove all backslashes (`\`)
|
|
|
-and join lines in the following command.
|
|
|
-
|
|
|
-["source","sh"]
|
|
|
-----
|
|
|
-docker exec es01 /bin/bash -c "bin/elasticsearch-reset-password \
|
|
|
-auto --batch \
|
|
|
---url https://localhost:9200"
|
|
|
-----
|
|
|
-
|
|
|
-===== Stop the cluster
|
|
|
+===== Stop and remove the deployment
|
|
|
To stop the cluster, run `docker-compose down`. The data in the Docker volumes
|
|
|
is preserved and loaded when you restart the cluster with `docker-compose up`.
|
|
|
|
|
|
@@ -413,19 +313,14 @@ docker-compose down
|
|
|
----
|
|
|
--
|
|
|
|
|
|
-To **delete the data volumes** when you stop the cluster, specify the `-v`
|
|
|
-option:
|
|
|
+To **delete** the network, containers, and volumes when you stop the cluster,
|
|
|
+specify the `-v` option:
|
|
|
|
|
|
["source","sh"]
|
|
|
----
|
|
|
docker-compose down -v
|
|
|
----
|
|
|
|
|
|
-WARNING: Deleting data volumes will remove the generated security certificates
|
|
|
-for your nodes. You will need to run `docker-compose` and
|
|
|
-<<docker-generate-certificates,regenerate the security certificates>> before
|
|
|
-starting your cluster.
|
|
|
-
|
|
|
===== Next steps
|
|
|
|
|
|
You now have a test {es} environment set up. Before you start
|
Adam Locke