Clarify difference between public and secure client settings in discu… #31469
Conversation
…ssion of S3 client configuration. See Support Ticket 00231008 : https://elastic.my.salesforce.com/ui/support/servicedesk/ServiceDeskPage#/5006100000M5DFG and also https://github.com/elastic/support-dev-help-elasticsearch/issues/737. The original discussion of client settings was carried over from doc versions before there were sensitive client settings. The existing language in the documentation can make customers believe that any client setting can be added to elasticsearch.yml. The new wording that I am proposing above makes it clear from the beginning of the discussion that there are now 2 classes of client settings for S3 snapshots: public and secure, and that each class must be specified differently.
|
Pinging @elastic/es-docs |
|
I think someone from the docs team needs to review this (@lcawl?). I am apprehensive about introducing "public settings" terminology, as we have not used it anywhere else in our docs to differentiate from secure settings. This would also affect more than this file, as the pattern of noting settings that must be placed in the keystore is used elsewhere in the docs (eg x-pack secure settings documentation). |
|
It's true, we refer to secure settings in several places (e.g. https://www.elastic.co/guide/en/elasticsearch/reference/master/security-settings.html, https://www.elastic.co/guide/en/beats/winlogbeat/6.3/keystore.html, https://www.elastic.co/guide/en/kibana/6.3/secure-settings.html, https://www.elastic.co/guide/en/elasticsearch/reference/6.3/secure-settings.html) but we don't refer to all other settings as "public" or "unsecure" or anything like that at this point. |
docs/plugins/repository-s3.asciidoc
Outdated
| the form `s3.client.CLIENT_NAME.SETTING_NAME` and specified inside `elasticsearch.yml`. The | ||
| default client name looked up by a `s3` repository is called `default`, but can be customized | ||
| with the repository setting `client`. For example: | ||
| The client used to connect to S3 has a number of settings available. Settings are either "public" or "secure", Public client settings may be specified in the `elasticsearch.yml` file and are of the form `s3.client.CLIENT_NAME.SETTING_NAME`. The default client name looked up by a `s3` repository is called `default`, but can be customized with the repository setting `client`. For example: |
There was a problem hiding this comment.
Rather than introducing the idea of "public" settings, I'd suggest something like this:
"The client ... has a number of settings available. All of these settings can be added to the elasticsearch.yml configuration file, with the exception of the secure settings, which you add to the Elasticsearch keystore. The settings have the form..."
docs/plugins/repository-s3.asciidoc
Outdated
| @@ -63,7 +59,7 @@ bin/elasticsearch-keystore add s3.client.default.secret_key | |||
| ---- | |||
|
|
|||
| The following are the available client settings. Those that must be stored in the keystore | |||
| are marked as `Secure`. | |||
| are marked as `Secure`; all other settings are public and may be included in the `elasticsearch.yml` file. | |||
There was a problem hiding this comment.
Per above, I'd just say "...all other settings can be included in the elasticsearch.yml file".
docs/plugins/repository-s3.asciidoc
Outdated
| @@ -63,7 +59,7 @@ bin/elasticsearch-keystore add s3.client.default.secret_key | |||
| ---- | |||
|
|
|||
| The following are the available client settings. Those that must be stored in the keystore | |||
| are marked as `Secure`. | |||
| are marked as `Secure`; all other settings are public and may be included in the `elasticsearch.yml` file. | |||
|
|
|||
| `access_key`:: | |||
There was a problem hiding this comment.
In other docs (e.g. https://www.elastic.co/guide/en/elasticsearch/reference/master/security-settings.html), we put the "secure" identifier directly after the setting name (instead of after the description) and it's a link to the secure settings page. I suggest doing the same here.
|
Everyone - I appreciate that this documentation clarification request is
being discussed.
My major concern is that the current wording leaves customers to conclude
that *all *client parameters can be included in the elasticsearch.yml
file, and this is an incorrect conclusion. All that I am requesting is that
the wording of the initial paragraph be changed so that it will be clear
from the beginning of the discussion that only certain parameters may be
placed in the elasticsearch.yml file. There is no need to specifically
define "public" vs "secure" parameters if this potentially creates problems
elsewhere.
Thanks
…On Thu, Jun 21, 2018 at 9:09 PM, Lisa Cawley ***@***.***> wrote:
***@***.**** commented on this pull request.
------------------------------
In docs/plugins/repository-s3.asciidoc
<#31469 (comment)>
:
> @@ -63,7 +59,7 @@ bin/elasticsearch-keystore add s3.client.default.secret_key
----
The following are the available client settings. Those that must be stored in the keystore
-are marked as `Secure`.
+are marked as `Secure`; all other settings are public and may be included in the `elasticsearch.yml` file.
`access_key`::
In other docs (e.g. https://www.elastic.co/guide/
en/elasticsearch/reference/master/security-settings.html), we put the
"secure" identifier directly after the setting name (instead of after the
description) and it's a link to the secure settings page. I suggest doing
the same here.
—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
<#31469 (review)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AboDgL9EnFZII7Mkl-lcG8-Hw3uP0TqAks5t--E-gaJpZM4UvjIo>
.
--
*Morrie Schreibman *
|
|
hi @MorrieAtElastic do you have time to address comments or shall the docs team take this over? cc @lcawl |
|
@lcawl you want to take this one over? |
|
I've added a commit that implements my suggestions. |
docs/plugins/repository-s3.asciidoc
Outdated
| The following are the available client settings. Those that must be stored in the keystore | ||
| are marked as `Secure`. | ||
| The following list contains the available client settings. Those that must be | ||
| stored in the keystore are marked as "secure"; all other settings can be |
There was a problem hiding this comment.
"can" implies (to me) that this is optional. Yet the secure and non secure settings are disjoint; they cannot be present in the other location. I'm not sure what word would better relate that requirement, though...
There was a problem hiding this comment.
Thanks for the feedback! I changed it to "all other settings belong in ..."
colings86
added
:Distributed Coordination/Snapshot/Restore
|
Pinging @elastic/es-distributed |
…ssion of S3 client configuration.
The original discussion of client settings was carried over from earlier versions before TLS. The existing language in the documentation can make users believe that any client setting can be added to elasticsearch.yml, which is not the case. The wording I am proposing makes it clear from the beginning of the discussion that there are now 2 classes of client settings for S3 snapshots: public and secure, and that each class must be specified differently.