[DOCS] Fix keystore creation instructions for Docker by stefnestor · Pull Request #77155 · elastic/elasticsearch

stefnestor · 2021-09-01T21:48:19Z

Currently, our Docker install docs instruct users to directly bind-mount the elasticsearch.keystore file. This can lead to errors:

If the keystore file doesn't already exist, Docker's -v flag will create elasticsearch.keystore as a directory. This will block the creation of the keystore file.
To add or update secure settings, the container needs access to other files in the config directory, such as keystore.tmp.

This updates the Docker install docs to instruct users to bind-mount the config directory rather than elasticsearch.keystore. It also adds troubleshooting tips for errors related to the keystore.

Relates to this Elastic Discuss.

Previews

Create an encrypted keystore: https://elasticsearch_77155.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/docker.html#docker-keystore-bind-mount
Troubleshoot Docker errors for Elasticsearch: https://elasticsearch_77155.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/docker.html#troubleshoot-docker-errors

From feedback from ES Devs summarized in [^1], I believe this needs to reflect a directory mount rather than file mount to not error. Also adding in the two common mounting errors, but not sure if this is the right place for them. [^1] https://discuss.elastic.co/t/persist-elasticsearch-kibana-keystores-with-docker/283099

elasticmachine · 2021-09-01T21:48:21Z

Pinging @elastic/es-docs (Team:Docs)

From feedback from ES Devs summarized in [this Elastic Discuss](https://discuss.elastic.co/t/persist-elasticsearch-kibana-keystores-with-docker/283099), Adding to [this doc section](https://www.elastic.co/guide/en/kibana/7.14/docker.html#bind-mount-config) information on persisting keystores. [ES related PR](elastic/elasticsearch#77155)

pugnascotia · 2021-09-02T08:32:09Z

docs/reference/setup/install/docker.asciidoc

+docker run -it --rm -v /amex/elasticsearch/config:/usr/share/elasticsearch/config dockerproxy.aexp.com/elasticsearch:6.8.3 bin/elasticsearch-keystore create
+docker run -it --rm -v /amex/elasticsearch/config:/usr/share/elasticsearch/config dockerproxy.aexp.com/elasticsearch:6.8.3 bin/elasticsearch-keystore add xpack.ssl.key_passphrase


I don't think we want references to amex here.

Man, I'm so not cool. I'd thought I'd removed those. Let me update.

Ok, should be resolved, thanks for catching ❤️

pugnascotia · 2021-09-06T19:32:37Z

docs/reference/setup/install/docker.asciidoc

 -E KEYSTORE_PASSWORD=mypassword
 --------------------------------------------

+If the keystore is mounted incorrectly, it will induce example Docker errors from attempting to


@jrodewig I'm not sure about this sentence, can you take a look?

Thanks for the ping @pugnascotia! I'll take a look and push some changes with edits.

Thanks for putting this together @stefnestor.

elasticmachine · 2021-09-09T13:19:36Z

Pinging @elastic/es-delivery (Team:Delivery)

jrodewig · 2021-09-09T13:22:58Z

Thanks again @stefnestor. I pushed d32eefd to reorganize these changes, make the snippets version-friendly, and create a separate troubleshooting section. I also updated some text around the snippets.

@williamrandolph @pugnascotia Let me know if these changes looks okay to you. If so, I'll get this merged in.

docs/reference/setup/install/docker.asciidoc

pugnascotia

Is it work a note somewhere to say that you can safely bind-mount only the keystore, provided it already exists and you won't be changing it i.e. it's read-only?

jrodewig · 2021-09-10T14:28:01Z

Thanks for your review and catching my error, @pugnascotia.

Is it work a note somewhere to say that you can safely bind-mount only the keystore, provided it already exists and you won't be changing it i.e. it's read-only?

Good point. I added a related docker compose example with 21708a4.

Currently, our Docker install docs instruct users to directly bind-mount the `elasticsearch.keystore` file. This can lead to errors: * If the keystore file doesn't already exist, Docker's `-v` flag will create `elasticsearch.keystore` as a directory. This will block the creation of the keystore file. * To add or update secure settings, the container needs access to other files in the `config` directory, such as `keystore.tmp`. This updates the Docker install docs to instruct users to bind-mount the `config` directory rather than `elasticsearch.keystore`. It also adds troubleshooting tips for errors related to the keystore. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com> Co-authored-by: Stef Nestor <steffanie.nestor@gmail.com>

) PR #77155 updated the keystore instructions for Docker. However, it removed an example that included the `KEYSTORE_PASSWORD` env variable. This replaces a docker compose example with the original example from PR #51123.

) (#77592) PR #77155 updated the keystore instructions for Docker. However, it removed an example that included the `KEYSTORE_PASSWORD` env variable. This replaces a docker compose example with the original example from PR #51123.

) (#77591) PR #77155 updated the keystore instructions for Docker. However, it removed an example that included the `KEYSTORE_PASSWORD` env variable. This replaces a docker compose example with the original example from PR #51123. Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>

) (#77590) PR #77155 updated the keystore instructions for Docker. However, it removed an example that included the `KEYSTORE_PASSWORD` env variable. This replaces a docker compose example with the original example from PR #51123. Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>

From feedback from ES Devs summarized in [this Elastic Discuss](https://discuss.elastic.co/t/persist-elasticsearch-kibana-keystores-with-docker/283099), Adding to [this doc section](https://www.elastic.co/guide/en/kibana/7.14/docker.html#bind-mount-config) information on persisting keystores. [ES related PR](elastic/elasticsearch#77155) Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

From feedback from ES Devs summarized in [this Elastic Discuss](https://discuss.elastic.co/t/persist-elasticsearch-kibana-keystores-with-docker/283099), Adding to [this doc section](https://www.elastic.co/guide/en/kibana/7.14/docker.html#bind-mount-config) information on persisting keystores. [ES related PR](elastic/elasticsearch#77155) Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: Stef Nestor <steffanie.nestor@gmail.com> Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

stefnestor added >docs General docs changes Team:Docs Meta label for docs team labels Sep 1, 2021

stefnestor requested review from jrodewig and pugnascotia September 1, 2021 21:48

elasticsearchmachine added v8.0.0 external-contributor Pull request authored by a developer outside the Elasticsearch team labels Sep 1, 2021

stefnestor mentioned this pull request Sep 1, 2021

[DOC] Update Persist Keystore via Docker elastic/kibana#110917

Merged

1 task

pugnascotia reviewed Sep 2, 2021

View reviewed changes

feedback

5035b08

pugnascotia reviewed Sep 6, 2021

View reviewed changes

Reorganize

d32eefd

jrodewig added the :Delivery/Packaging RPM and deb packaging, tar and zip archives, shell and batch scripts label Sep 9, 2021

elasticmachine added the Team:Delivery Meta label for Delivery team label Sep 9, 2021

jrodewig added v7.14.2 v7.15.1 v7.16.0 labels Sep 9, 2021

reword

fe5f967

jrodewig requested a review from williamrandolph September 9, 2021 13:24

jrodewig changed the title ~~[DOC] Update Persist Keystore via Docker~~ [DOC] Fix keystore creation instructions for Docker Sep 9, 2021

jrodewig requested a review from pugnascotia September 9, 2021 13:32

fix formatting

26d80cc

jrodewig self-assigned this Sep 9, 2021

jrodewig changed the title ~~[DOC] Fix keystore creation instructions for Docker~~ [DOCS] Fix keystore creation instructions for Docker Sep 9, 2021

jrodewig approved these changes Sep 9, 2021

View reviewed changes

pugnascotia reviewed Sep 10, 2021

View reviewed changes

docs/reference/setup/install/docker.asciidoc Outdated Show resolved Hide resolved

pugnascotia reviewed Sep 10, 2021

View reviewed changes

docs/reference/setup/install/docker.asciidoc Outdated Show resolved Hide resolved

pugnascotia approved these changes Sep 10, 2021

View reviewed changes

address review feedback

21708a4

remove extra whitespace

00517f4

jrodewig added auto-backport-and-merge auto-merge-without-approval Automatically merge pull request when CI checks pass (NB doesn't wait for reviews!) labels Sep 10, 2021

elasticsearchmachine merged commit 5bc2917 into master Sep 10, 2021

elasticsearchmachine deleted the stefnestor-patch-1 branch September 10, 2021 14:42

This was referenced Sep 10, 2021

[7.x] [DOCS] Fix keystore creation instructions for Docker (#77155) #77559

Merged

[7.15] [DOCS] Fix keystore creation instructions for Docker (#77155) #77560

Merged

[7.14] [DOCS] Fix keystore creation instructions for Docker (#77155) #77561

Merged

jrodewig mentioned this pull request Sep 10, 2021

[DOCS] Re-add KEYSTORE_PASSWORD example to Docker install docs #77588

Merged

jakelandis added v8.0.0-alpha2 and removed v8.0.0 labels Sep 15, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOCS] Fix keystore creation instructions for Docker#77155

[DOCS] Fix keystore creation instructions for Docker#77155
elasticsearchmachine merged 7 commits intomasterfrom
stefnestor-patch-1

stefnestor commented Sep 1, 2021 •

edited by jrodewig

Loading

Uh oh!

elasticmachine commented Sep 1, 2021

Uh oh!

pugnascotia Sep 2, 2021

Uh oh!

stefnestor Sep 6, 2021

Uh oh!

stefnestor Sep 6, 2021

Uh oh!

pugnascotia Sep 6, 2021

Uh oh!

jrodewig Sep 8, 2021 •

edited

Loading

Uh oh!

elasticmachine commented Sep 9, 2021

Uh oh!

jrodewig commented Sep 9, 2021

Uh oh!

Uh oh!

Uh oh!

pugnascotia left a comment

Uh oh!

jrodewig commented Sep 10, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

		docker run -it --rm -v /amex/elasticsearch/config:/usr/share/elasticsearch/config dockerproxy.aexp.com/elasticsearch:6.8.3 bin/elasticsearch-keystore create
		docker run -it --rm -v /amex/elasticsearch/config:/usr/share/elasticsearch/config dockerproxy.aexp.com/elasticsearch:6.8.3 bin/elasticsearch-keystore add xpack.ssl.key_passphrase

Conversation

stefnestor commented Sep 1, 2021 • edited by jrodewig Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Previews

Uh oh!

elasticmachine commented Sep 1, 2021

Uh oh!

pugnascotia Sep 2, 2021

Choose a reason for hiding this comment

Uh oh!

stefnestor Sep 6, 2021

Choose a reason for hiding this comment

Uh oh!

stefnestor Sep 6, 2021

Choose a reason for hiding this comment

Uh oh!

pugnascotia Sep 6, 2021

Choose a reason for hiding this comment

Uh oh!

jrodewig Sep 8, 2021 • 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!

elasticmachine commented Sep 9, 2021

Uh oh!

jrodewig commented Sep 9, 2021

Uh oh!

Uh oh!

Uh oh!

pugnascotia left a comment

Choose a reason for hiding this comment

Uh oh!

jrodewig commented Sep 10, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

stefnestor commented Sep 1, 2021 •

edited by jrodewig

Loading

jrodewig Sep 8, 2021 •

edited

Loading