Elasticsearch and stack - self managed tutorial 1 complete refinement#5636
Elasticsearch and stack - self managed tutorial 1 complete refinement#5636
Conversation
🔍 Preview links for changed docs |
✅ Vale Linting ResultsNo issues found on modified lines! The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale. |
| * {{agent}} enrolls using that Quick Start flow, which requires the install command to include the `--insecure` flag. | ||
|
|
||
| If you plan to use certificates signed by your organization's certificate authority or by a public CA, complete this tutorial until {{kib}} is installed (Step 6), and then continue with [Tutorial 2: Customize certificates for a self-managed {{stack}}](tutorial-self-managed-secure.md) before installing {{fleet-server}} and {{agent}}. | ||
| If you plan to use certificates signed by your organization's certificate authority or by a public CA, complete this tutorial until {{kib}} is installed (Step 7), and then continue with [Tutorial 2: Customize certificates for a self-managed {{stack}}](tutorial-self-managed-secure.md) before installing {{fleet-server}} and {{agent}}. |
There was a problem hiding this comment.
Maybe this should be in a Tip or Important admonition so that it's more prominent
| * The transport interface is bound to the loopback interface (`localhost`), preventing other nodes from joining the cluster, while the HTTP interface listens on all network interfaces (`http.host: 0.0.0.0`). | ||
|
|
||
| 7. Copy the terminal output from the install command to a local file. In particular, you need the password for the built-in `elastic` superuser account. The output also contains the commands to enable {{es}} to run as a service, which you use in the next step. | ||
| 1. Copy the terminal output from the install command to a local file. In particular, you need the password for the built-in `elastic` superuser account. The output also contains the commands to enable {{es}} to run as a service, which you use in the next step. |
There was a problem hiding this comment.
| 1. Copy the terminal output from the install command to a local file. In particular, you need the password for the built-in `elastic` superuser account. The output also contains the commands to enable {{es}} to run as a service, which you use in the next step. | |
| 1. Copy the terminal output from the install command to a local file. In particular, you need the password for the built-in `elastic` user account. The output also contains the commands to enable {{es}} to run as a service, which you use in the next step. |
Not sure if this is correct, but pointing this out since you changed "super user" to "user" in the prereqs
There was a problem hiding this comment.
Same comment for other places on this page where "superuser" is mentioned
There was a problem hiding this comment.
Thanks! I'll review all occurrences, and I'll explain why I changed the first one but not the others :)
The pre-reqs talked about an operating system user, which with sudo privileges can become root (a.k.a the superuser OS account). That's why in the intro it's better to require a normal user account with sudo privileges (saying superuser account with sudo privileges feels redundant or unneeded, because if you are already a superuser you don't really need sudo :D ).
Here the sentence is about the Elasticsearch built-in user elastic, which has the superuser role and its known as a superuser (at Elasticsearch level).
Anyway elastic user or elastic superuser should both be fine. I was more worried about the prereqs, where superuser felt a bit out of place.
| Before moving ahead to configure additional {{es}} nodes, you need to update the {{es}} configuration on this first node so that other hosts are able to connect to it. This is done by updating the settings in the `elasticsearch.yml` file. For more details about {{es}} configuration and the most common settings, refer to [Configure {{es}}](/deploy-manage/deploy/self-managed/configure-elasticsearch.md) and [important settings configuration](/deploy-manage/deploy/self-managed/important-settings-configuration.md). | ||
|
|
||
| 1. In a terminal, run the `ifconfig` command and copy the value shown for the host IP address (for example, `10.128.0.84`). You need this value later. | ||
| 1. Obtain your host IP address (for example, by running `ifconfig`). You need this value later. |
There was a problem hiding this comment.
| 1. Obtain your host IP address (for example, by running `ifconfig`). You need this value later. | |
| 1. Obtain your host IP address (for example, by running `ifconfig`). You will need this value later. |
There was a problem hiding this comment.
I'm trying to remove all future tense occurrences in the tutorial on purpose (whenever is feasible), due to what I think our current guidance is.
Shouldn't this be the way to go @theletterf ?
IMO you need this value later feels also ok in a tutorial, without needing the will. Note that I have removed more than 30 future tense occurrences in these two tutorials already :-D
| 1. Answer the `Do you want to continue with the reconfiguration process` prompt with `yes` (`y`). The new {{es}} node is reconfigured. | ||
|
|
||
| 13. Open the second {{es}} instance configuration file in a text editor: | ||
| 1. Obtain your host IP address (for example, by running `ifconfig`). You need this value later. |
There was a problem hiding this comment.
| 1. Obtain your host IP address (for example, by running `ifconfig`). You need this value later. | |
| 1. Obtain your host IP address (for example, by running `ifconfig`). You will need this value later. |
deploy-manage/deploy/self-managed/tutorial-self-managed-install.md
Outdated
Show resolved
Hide resolved
| * {{agent}} enrolls using that Quick Start flow, which requires the install command to include the `--insecure` flag. | ||
|
|
||
| If you plan to use certificates signed by your organization's certificate authority or by a public CA, complete this tutorial until {{kib}} is installed (Step 6), and then continue with [Tutorial 2: Customize certificates for a self-managed {{stack}}](tutorial-self-managed-secure.md) before installing {{fleet-server}} and {{agent}}. | ||
| If you plan to use certificates signed by your organization's certificate authority or by a public CA, complete this tutorial until {{kib}} is installed (Step 7), and then continue with [Tutorial 2: Customize certificates for a self-managed {{stack}}](tutorial-self-managed-secure.md) before installing {{fleet-server}} and {{agent}}. |
There was a problem hiding this comment.
You could link to the admonition in step 7 to make it clear exactly where they should stop
There was a problem hiding this comment.
Yeah, I have a bit of mixed feelings with this paragraph and the huge admonition you are also referring.
The next big PR I'm working with is for the second tutorial, which needs to be almost completely rewritten, so my expectation is that after that tutorial-2 is changes we might be able to provide a better path and better links do the exact steps on the second tutorial to apply the needed actions.
deploy-manage/deploy/self-managed/tutorial-self-managed-install.md
Outdated
Show resolved
Hide resolved
| ``` | ||
|
|
||
| 4. In the terminal, run `ifconfig` and copy the value shown for the host IP address (for example, `10.128.0.84`). You need this value later. | ||
| 1. Obtain the host IP address for your {{fleet-server}} host (for example, by running `ifconfig`). You need this value later. |
There was a problem hiding this comment.
| 1. Obtain the host IP address for your {{fleet-server}} host (for example, by running `ifconfig`). You need this value later. | |
| 1. Obtain the host IP address for your {{fleet-server}} host (for example, by running `ifconfig`). You will need this value later. |
deploy-manage/deploy/self-managed/tutorial-self-managed-install.md
Outdated
Show resolved
Hide resolved
deploy-manage/deploy/self-managed/tutorial-self-managed-install.md
Outdated
Show resolved
Hide resolved
deploy-manage/deploy/self-managed/tutorial-self-managed-install.md
Outdated
Show resolved
Hide resolved
deploy-manage/deploy/self-managed/tutorial-self-managed-install.md
Outdated
Show resolved
Hide resolved
deploy-manage/deploy/self-managed/tutorial-self-managed-install.md
Outdated
Show resolved
Hide resolved
deploy-manage/deploy/self-managed/tutorial-self-managed-install.md
Outdated
Show resolved
Hide resolved
deploy-manage/deploy/self-managed/tutorial-self-managed-install.md
Outdated
Show resolved
Hide resolved
|
|
||
| * Do you have data ready to ingest? Learn how to [bring your data to Elastic](/manage-data/ingest.md). | ||
| * Use [Elastic {{observability}}](/solutions/observability.md) to unify your logs, infrastructure metrics, uptime, and application performance data. | ||
| * Want to protect your endpoints from security threats? Try [{{elastic-sec}}](/solutions/security.md). Adding endpoint protection is just another integration that you add to the agent policy! |
There was a problem hiding this comment.
| * Want to protect your endpoints from security threats? Try [{{elastic-sec}}](/solutions/security.md). Adding endpoint protection is just another integration that you add to the agent policy. |
@eedugon can you have a look at this last line? I don't know if "just another integration" is correct
wajihaparvez
left a comment
wajihaparvez
left a comment
There was a problem hiding this comment.
Looks great @eedugon! ⭐️ Just some minor suggestions
Co-authored-by: wajihaparvez <wajiha.parvez@elastic.co>
2 participants
Summary
Major and hopefully final refinement of tutorial 1.
Addressed issues:
Structure and navigation
Step 6: Consolidate {{es}} configurationto the table of contents.Elasticsearch setup and configuration
wgetdownloads withcurl -L -Oequivalents.curl(removedwgetdependency).transport.host, explainedhttp.hostfrom automatic setup, and aligned references to official networking settings docs.node.nameguidance and mirrored it in the second-node flow.Kibana setup and enrollment
xpack.encryptedSavedObjects.encryptionKeysetup inkibana.yml.kibana-encryption-keys generateusage with explicit guidance on which key to use.xpack.encryptedSavedObjects.encryptionKeyis needed for this tutorial path.Fleet Server and Elastic Agent flows
aarch64vsx64) in Fleet Server and Agent install steps.--insecureis required in this tutorial path.elasticusers)https://epr.elastic.co:443{{agent}}per host.Fleet Server hostsandOutputsURL validation).Data validation and closing section
{{observability}}Observability -> Infrastructure -> Hosts.Generative AI disclosure
Closes https://github.com/elastic/docs-content-internal/issues/929