URL option for BaseRunAsSuperuserCommand

[jkakavas]

Add a --url option for elasticsearch-reset-password and
elasticsearch-create-enrollment-token CLI Tools ( and any tools
that would extend BaseRunAsSuperuserCommand ).
The tools use CommandLineHttpClient internally, which tries its
best to deduce the URL of the local node based on the configuration
but there are certain cases where it either fails or returns an
unwanted result. Concretely:

• CommandLineHttpClient#getDefaultURL will always return a URL with
  the port set to 9200, unless otherwise explicitly set in the
  configuration. When running multiple nodes on the same host,
  subsequent nodes get sequential port numbers after 9200 by default
  and this means that the CLI tool will always connect the first of
  n nodes in a given host. Since these tools depend on a file realm
  local user, requests to other nodes would fail
• When an ES node binds and listens to many addresses, there can
  be the case that not all of the IP addresses are added as SANs in
  the certificate that is used for TLS on the HTTP layer.
  CommandLineHttpClient#getDefaultURL will pick an address based on
  a preference order but that address might not be in the SANs and
  thus all requests to the node would fail due to failed hostname
  verification.

Manually setting --url to an appropriate value allows users to
overcome these edge cases.

Resolves: #80481

[elasticmachine]

Pinging @elastic/es-security (Team:Security)

[albertzaharovits]

Do you think it would be preferable that we drop the "If xpack.security.http.ssl.enabled is set to true,
you must specify an HTTPS URL" scheme condition, by having the tool check for that itself (like it does for the "default URL")?

Moreover, a URL is more than the scheme and the host and port pair, and using DNS names to refer to the node might not be ideal, as it might not be included in the SAN of the cert.
Do you think it would be preferable that this option be more focused on the ip and port that the local node can be reached at?

[jkakavas]

Do you think it would be preferable that this option be more focused on the ip and port that the local node can be reached at?

I contemplated the same but in the end settled to a single option as a simpler thing, happy to discuss.

a URL is more than the scheme and the host and port pair

true but what we should be aiming for here is not naming strictness for the sake of it but a name for the option that’s understandable by (or at least explainable for ) the majority of users. I think that url fits the bill.

and using DNS names to refer to the node might not be ideal, as it might not be included in the SAN of the cert.

the idea is that if you ever need to use this parameter you do so because you know that you want to talk to the node at an ip or hostname that is in the SANs but CommandLineHttpClient picks another. So you know what should be in the url (either a hostname or an IP address )

Do you think it would be preferable that we drop the "If xpack.security.http.ssl.enabled is set to true,
you must specify an HTTPS URL" scheme condition, by having the tool check for that itself (like it does for the "default URL")?

If we change this to two parameters then yes it makes sense , we shouldn’t be asking the users for a third parameter (scheme) but I’m not 100% that ee should change.

Do we introduce an ip and a port parameter? Do we mandate both if one is passed or have default values for the port ?

[albertzaharovits]

Do we introduce an ip and a port parameter? Do we mandate both if one is passed or have default values for the port ?

I don't have a preference. Having to specify both the ip and the port simultaneously (as is the case with this url parameter), as a single option is OK.

[albertzaharovits]

I think it would be an improvement if we convey that the new cmd line argument takes the ip address and port of the local node. LGTM otherwise.

FWIW I am also OK with documenting your workaround of specifying the -Enode.host and -Enode.port as arguments.

[jkakavas]

I think it would be an improvement if we convey that the new cmd line argument takes the ip address and port of the local node.

You mean in the docs ? Something like :

`--url`:: Specifies the base URL (hostname and port of the local node) that
 the tool uses to submit API requests to {es}. The default value is determined 
from the settings in your `elasticsearch.yml` file. 
If `xpack.security.http.ssl.enabled` is set to `true`, you must specify an HTTPS URL.

?

[lockewritesdocs]

Added a few suggestions, but overall LGTM.

[lockewritesdocs]

Suggested change

	requests to {es}. The default value is determined from the settings in your
	`elasticsearch.yml` file. If `xpack.security.http.ssl.enabled` is set to `true`,
	requests to {es}. The combination of values for `network.host` and `http.port` in your
	`elasticsearch.yml` file determine the default URL. If `xpack.security.http.ssl.enabled` is set to `true`,

[lockewritesdocs]

@jkakavas, I think it's worth indicating which settings determine the default value. What do you think?

This change would also apply to the --url description for the create-enrolllment-token tool.

[jkakavas]

It's not that simple actually. It can be network.host or http.host , with http.port, let alone advanced options or talking about _site_, _local_, _global_ etc. I don't think this is the place to go through all these in detail :/

[lockewritesdocs]

Of course it's not that simple 😆 , which is probably why you opted for simplicity in your original description. I'm 👍 with keeping your original text -- thank you for the explanation!

[lockewritesdocs]

Suggested change

	The following example resets the password of a native user with username `user2` to an auto-generated value
	prints the new password in the console, while overriding the url where the local elasticsearch node is reachable:
	The following example resets the password of a native user named `user2` to an auto-generated value,
	prints the new password in the console, and overrides the URL where the local {es} node is reachable:

[lockewritesdocs]

Suggested change

	The following command creates an enrollment token for enrolling a kibana instance into a cluster,
	while overriding the url where the local elasticsearch node is reachable:
	The following command creates an enrollment token for enrolling a {kib} instance into a cluster,
	and overrides the URL where the local {es} node is reachable:

[jkakavas]

and feels off here ( and I mean "feels", I can't actually argue about it being wrong :). To me your suggestion reads as if the example command invocation does two things:

1. It creates an enrollment token
2. It overrides the URL where the local elasticsearch node is reachable

which is not accurate.
It does only 1. but 2 is something that temporarily happens - and only for the context of this command's execution - so that 1. can succeed.

WDYT @lockewritesdocs ?

[lockewritesdocs]

Ooooo, I see! In that case, let's explore options. Choose whichever one you like better, or let me know neither hits the mark.

This rendition is similar to your original text, but adds "temporarily" to distinguish the time constraint:

The following command creates an enrollment token for enrolling a {kib} instance into a cluster, while temporarily overriding the URL where the local {es} node is reachable:

Another option dismisses the notion of the interaction between 1 and 2 entirely, and instead focuses on what the URL denotes:

The following command creates an enrollment token for enrolling a {kib} instance into a cluster. The specified URL indicates where the local {es} node is reachable:

[jkakavas]

Thanks for the discussion Adam. It actually makes me think that the original "is reachable" is misleading. Setting this option doesn't change at all where elasticsearch is reachable or listens to, but only where the CLI tool will talk to.
In my original version, there was a "while overriding the url where the CLI tool thinks that the local elasticsearch node is reachable" implied there.

With that context, do you have any suggestions on how to frame this ?

[lockewritesdocs]

Given that context, I think something like the following statement works:

The following command creates an enrollment token for enrolling a {kib} instance into a cluster. The specified URL indicates where the elasticsearch-create-enrollment-token tool attempts to reach the local {es} node:

If we want to indicate more about "where the CLI tool thinks that the local ES node is reachable," then we might need further clarification of what happens if the tool doesn't find the node at the specified URL:

The following command creates an enrollment token for enrolling a {kib} instance into a cluster. The specified URL indicates where the elasticsearch-create-enrollment-token tool attempts to reach the local {es} node. If the tool can't reach {es} at the specified port, it iterates through port numbers sequentially on the indicated host:

Caveat: I'm not certain that the last sentence here ☝️ is true.

[jkakavas]

Caveat: I'm not certain that the last sentence here point_up is true.

It doesn't work like this actually,

The following command creates an enrollment token for enrolling a {kib} instance into a cluster. The specified URL indicates where the elasticsearch-create-enrollment-token tool attempts to reach the local {es} node:

sounds good to me, let's keep this simple