docs: Docker SSL/TLS getting started by dliappis · Pull Request #27281 · elastic/elasticsearch

dliappis · 2017-11-06T16:18:33Z

Commit docs for a getting started example for https and TLS/SSL enabled transport with the Docker Elasticsearch image.

joshbressers

This is solid. Well done.

michaelbaamonde · 2017-11-07T14:19:47Z

docs/reference/setup/install/getting-started-tls-docker.asciidoc

+services:
+  create_certs:
+    container_name: create_certs
+    image: docker.elastic.co/elasticsearch/elasticsearch-platinum:6.0.0-rc2


Should we parameterize the version here and everywhere else that 6.0.0-rc2 is used? It's possible that I've got the workflow wrong, but it seems like you'll otherwise need to hard-code the version for each branch that this document will live on (master, 6.0, 6.x) in separate backport commits.

Thanks @michaelbaamonde addressed in 03d040d already, almost missed that!

Adding also // NOTCONSOLE for curl example

And display a warning message for versions that haven't been released yet.

dliappis · 2017-11-07T15:59:52Z

jenkins, test it

ghost

Even works on Windows (after installing Curl). Very nice!

ghost · 2017-11-08T04:48:10Z

docs/reference/setup/install/getting-started-tls-docker.asciidoc

+[[getting-started-tls-docker]]
+=== Getting started with TLS and Elasticsearch
+
+Starting with version 6.0.0, x-pack licensed for security (gold, platinum or enterprise subscriptions) https://www.elastic.co/guide/en/elasticsearch/reference/6.0/breaking-6.0.0-xes.html[requires SSL/TLS] encryption for the transport networking layer.


X-Pack, Security, Gold, Platinum, and Enterprise are all proper nouns in this context, so they need capitals.

Addressed in d258de6

ghost · 2017-11-08T04:49:37Z

docs/reference/setup/install/getting-started-tls-docker.asciidoc

+
+Starting with version 6.0.0, x-pack licensed for security (gold, platinum or enterprise subscriptions) https://www.elastic.co/guide/en/elasticsearch/reference/6.0/breaking-6.0.0-xes.html[requires SSL/TLS] encryption for the transport networking layer.
+
+This section demonstrates an easy path to get started with SSL/TLS for both http and transport using the elasticsearch-platinum docker image.


"HTTP" should be capped.

Consider backticks for elasticsearch-platinum.

"Docker" is a proper noun.

Addressed in d258de6

ghost · 2017-11-08T04:55:54Z

docs/reference/setup/install/getting-started-tls-docker.asciidoc

+    ip:
+      - 127.0.0.1
+
+<1> Allow use of embedded Docker DNS server names.


Rather than "allowing" DNS, isn't this line an imperative that we will create a DNS entry? Like:

"Create a record for this node in Docker's internal DNS"

Actually this is done by Docker itself and its embedded DNS server. Here we just add the localhost IP address to the SAN records of the certificate, so that https calls, used in our examples, will work without issues.

ghost · 2017-11-08T04:59:22Z

docs/reference/setup/install/getting-started-tls-docker.asciidoc

+volumes: {"esdata_01": {"driver": "local"}, "esdata_02": {"driver": "local"}}
+----
+
+<1> Bootstrap `elastic` with the password defined in `.env`. See {xpack-ref}/setting-up-authentication.html#bootstrap-elastic-passwords[the Elastic Boostrap Password].


"Boostrap" is missing a "t".

Addressed in d258de6

ghost · 2017-11-08T05:01:02Z

docs/reference/setup/install/getting-started-tls-docker.asciidoc

+CERTS_DIR=/usr/share/elasticsearch/config/x-pack/certificates <1>
+ELASTIC_PASSWORD=PleaseChangeMe <2>
+
+<1> The path, inside the docker image, where certificates are expected to be found.


"Docker" proper noun.

Addressed in d258de6

ghost · 2017-11-08T05:07:23Z

docs/reference/setup/install/getting-started-tls-docker.asciidoc

+      fi;
+      chgrp -R 0 config/x-pack/certificates/certs
+      '
+    user: ${UID:-1000}


AsciiDoc is trying to expand this as an attribute and failing:

asciidoc: WARNING: getting-started-tls-docker.asciidoc: line 71: illegal system attribute name: UID

Standard escaping seems to work:

$\{UID:-1000\}

Great catch! Addressed in d258de6

ghost · 2017-11-08T05:10:08Z

docs/reference/setup/install/getting-started-tls-docker.asciidoc

+    image: docker.elastic.co/elasticsearch/elasticsearch-platinum:{version}
+    command: >
+      bash -c '
+      if [[ ! -d config/x-pack/certificates/certs ]]; then


Can we:

Indent the script under the opening qoute

Indent the conditional bodies within the script

?

Addressed in e73fb2a

ghost · 2017-11-08T05:11:33Z

docs/reference/setup/install/getting-started-tls-docker.asciidoc

+<1> Bootstrap `elastic` with the password defined in `.env`. See {xpack-ref}/setting-up-authentication.html#bootstrap-elastic-passwords[the Elastic Boostrap Password].
+<2> Disable verification of authenticity for inter-node communication. Allows creating self-signed certificates without having to pin specific internal IP addresses.
+endif::[]
+


Hard to explain, but explained well here. Nice.

ghost · 2017-11-08T05:13:06Z

docs/reference/setup/install/getting-started-tls-docker.asciidoc

+["source","sh"]
+----
+docker-compose -f create-certs.yml up
+----


Is it worth making the node containers "depend" on this one instead? Will that work? Is it too fiddly?

As discussed this is very tricky, because the create-certs docker container will eventually exit and it's hard to create a decent healthcheck in this case.

ghost · 2017-11-08T05:17:36Z

docs/reference/setup/install/getting-started-tls-docker.asciidoc

+[[getting-started-tls-docker]]
+=== Getting started with TLS and Elasticsearch
+
+Starting with version 6.0.0, x-pack licensed for security (gold, platinum or enterprise subscriptions) https://www.elastic.co/guide/en/elasticsearch/reference/6.0/breaking-6.0.0-xes.html[requires SSL/TLS] encryption for the transport networking layer.


Is "X-Pack Security" cleaner than "X-Pack licenced for Security"?

Addressed in d258de6

Since we are demo'ing a two node cluster, specify minimum_master_nodes as per: https://www.elastic.co/guide/en/elasticsearch/reference/current/important-settings.html#minimum_master_nodes

dliappis · 2017-11-08T13:17:25Z

Thanks for the thorough review @Jarpy , I have addressed the identified issues.

ghost · 2017-11-09T02:29:22Z

Oh no, thank you.

dliappis · 2017-11-10T18:36:26Z

Closed in lieu of #27333

cc @lcawl ^^

Dimitrios Liappis added 2 commits November 6, 2017 16:34

docs: Commit SSL/TLS getting started with Docker

67408a8

docs: Do not fail curl tests

1df722b

dliappis requested review from a user, drewr, joshbressers and skearns64 November 6, 2017 16:18

joshbressers approved these changes Nov 6, 2017

View reviewed changes

michaelbaamonde reviewed Nov 7, 2017

View reviewed changes

Dimitrios Liappis added 3 commits November 7, 2017 17:19

docs: Use code blocks for shell commands

384d216

Adding also // NOTCONSOLE for curl example

docs: adjust wording for reference to ssl/tls Docker guide

fe884c9

docs: do not hard code Docker image tag

03d040d

And display a warning message for versions that haven't been released yet.

docs: Use open blocks for snippets

c60d4e5

ghost suggested changes Nov 8, 2017

View reviewed changes

Dimitrios Liappis added 4 commits November 8, 2017 13:22

docs: Avoid split brain scenario in getting-started tls example

c36d270

Since we are demo'ing a two node cluster, specify minimum_master_nodes as per: https://www.elastic.co/guide/en/elasticsearch/reference/current/important-settings.html#minimum_master_nodes

docs: Use separators in code blocks

8efd104

docs: Fix typos

d258de6

docs: indent shell block for create-certs compose file

e73fb2a

ghost approved these changes Nov 9, 2017

View reviewed changes

dliappis closed this Nov 10, 2017


		Starting with version 6.0.0, x-pack licensed for security (gold, platinum or enterprise subscriptions) https://www.elastic.co/guide/en/elasticsearch/reference/6.0/breaking-6.0.0-xes.html[requires SSL/TLS] encryption for the transport networking layer.

		This section demonstrates an easy path to get started with SSL/TLS for both http and transport using the elasticsearch-platinum docker image.

Conversation

dliappis commented Nov 6, 2017

Uh oh!

joshbressers left a comment

Choose a reason for hiding this comment

Uh oh!

michaelbaamonde Nov 7, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dliappis Nov 8, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dliappis commented Nov 7, 2017

Uh oh!

ghost left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ghost Nov 8, 2017 • edited by ghost Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dliappis Nov 8, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dliappis commented Nov 8, 2017

Uh oh!

ghost commented Nov 9, 2017

Uh oh!

dliappis commented Nov 10, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

michaelbaamonde Nov 7, 2017 •

edited

Loading

dliappis Nov 8, 2017 •

edited

Loading

ghost Nov 8, 2017 •

edited by ghost

Loading

dliappis Nov 8, 2017 •

edited

Loading