Refine ECE SUSE host configuration page#6598
Conversation
Rewrite the SUSE host configuration page to address GitHub issue docs-content-internal#24: drop the unsupported Docker 24.0.7 examples, flag SLES 12 SP5 EOL, and label commands as examples that should be cross-checked against the Support matrix. Extract the Docker version into a shared ece-docker-version substitution so the Ubuntu and SUSE pages stay in sync. Reword the intros on all three sibling pages (RHEL, SUSE, Ubuntu) so they diverge enough to be indexed independently by search engines. Replace the deprecated `service network restart` with `systemctl restart NetworkManager`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Elastic Docs AI PR menuCheck the box to run an AI review for this pull request.
Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team. |
This comment was marked as outdated.
This comment was marked as outdated.
Follow-up to the SUSE refinement: SLES 12 SP5 is EOL, so the page now targets SLES 15 only with a note pointing migrators at the last SUSE- shipped Docker for SLES 12 SP5. Also drop `sudo systemctl restart NetworkManager` from the sysctl apply step — that's the wrong command for SUSE (default network manager is wicked, not NetworkManager), and the network restart isn't actually needed after `sysctl -p` for the parameters being set here. Link the SUSE Docker installation doc instead of half-documenting the SUSEConnect command. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…mand
Three small follow-ups from a fresh-eyes pass:
- SUSE: remove stray `s` after the closing fence on the Containers Module tip.
- Ubuntu: add the missing period at the end of the Docker example sentence.
- Ubuntu: add `subs=true` to the `docker-ce` install code block so
`{{ece-docker-version}}` resolves like it does in the SUSE block.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Docs review summary
Focus areas
- Style and clarity: Good overall. Two issues flagged inline: "workflow" jargon + non-standard "ready" verb in the Ubuntu intro; stacked tip+note admonitions in the SUSE Docker install step.
- Jargon:
ECEis used in the RHEL intro without expansion, but{{ece}}in the same sentence renders to "Elastic Cloud Enterprise" — acceptable. Other terms are fine. - Frontmatter and applies_to: Unchanged; no issues.
- Content type fit: All three pages are how-to guides. The reorganization of OS-group setup into step 4 of the "Install Docker on SLES" section is a mild structural mismatch (the H2 heading doesn't cover OS groups), but it simplifies the flow and is not harmful enough to block the PR.
- Parent issue satisfaction: Satisfied. The PR addresses all items in the linked issue: drops deprecated Docker 24.0.7 examples, flags SLES 12 SP5 EOL, extracts a shared
ece-docker-versionsubstitution, rewrites the three sibling page intros for SEO, removes the deprecatedservice network restartcall, and drops the "minimalist/cover your bases" framing.
Nits
configure-host-suse.mdline 49: The step text repeats the variable name twice ("example of installing Docker {{ece-docker-version}}. To install a different Docker version, replace {{ece-docker-version}}..."). A tighter phrasing: "Install Docker {{ece-docker-version}} and other required packages on SLES 15. To use a different version, check the Support matrix."configure-host-suse.mdline 17: Contraction "you've" — Elastic style prefers contractions in a friendly tone so this is fine, but if editors prefer no contractions, "the versions you have identified" works.
Notes
- The pre-fetched Vale output was empty (0 eligible files reported by the workflow data), but there are clearly eligible changed markdown files in this PR. The review was performed from the diff directly.
- The PR is marked as a draft pending SME validation of the SLES 15 commands; the review findings here are independent of that validation.
Generated by Docs review agent for issue #6598 · ● 325.8K
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Elastic Docs Style Checker (Vale)Summary: 1 suggestion found 💡 Suggestions (1): Optional style improvements. Apply when helpful.
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. |
eedugon
left a comment
eedugon
left a comment
There was a problem hiding this comment.
I've reviewed RHEL and Ubuntu small changes.
I'll test all SuSE commands and the new content in a lab environment and get back to you next week!
Thanks a lot for working on this issue!
There was a problem hiding this comment.
Installation works fine with SLES15-SP4 and Docker 25, but not with newer SPs where Docker 25 is not available, and for some reason ECE install doesn't work in SuSE with Docker 27.
Also SP4 is close to EOL and it's difficult to find images, and newer SPs (SP7) don't include Docker 25 anymore in the package repositories. This has been raised to cloud team for their consideration. Ideally we should support newer SPs and Docker versions soon.
|
thanks for all the detailed comments, @eedugon! I think I've addressed everything except for the one I left open. Take a look when you get a chance. |
eedugon
left a comment
eedugon
left a comment
There was a problem hiding this comment.
Things are looking much better, thanks a lot!
Sharing some extra comments for small movements and refinement. Afterwards I'll do a new set of testing and I might suggest small changes on the order of the directories and mount point configuration steps.
My plan is to finish with this PR very soon, and then align the other install guides to this one at a later stage. |
eedugon
left a comment
eedugon
left a comment
There was a problem hiding this comment.
Approving to remove the lock, then I'll set new reviewers
|
@kunisen, I've added significant changes to the PR, please let me know your thoughts. I've updated a lot the structure to ensure the steps are separated in clear and differentiated areas. In the near future I'll check with PMs and devs to see if we can align the 3 OSs documents so they have similar structure. |
| sudo useradd -m -g elastic -G docker elastic | ||
| ``` | ||
|
|
||
| The user that prepares the host must be able to run commands with `sudo`. Configure sudo access according to your organization's policies. For example, to allow the `elastic` user to run the commands in this guide without entering a password: |
There was a problem hiding this comment.
I have some questions on this:
- Should we mention this earlier like under the first
Prepare the user account for ECEblock? - Do we have to write it in such a detailed way? (I guess no because I saw you removed this by looking at the latest status - https://github.com/elastic/docs-content/pull/6598/changes)
There was a problem hiding this comment.
I've removed all that part if I'm not mistaken. And I agreed, that level of detail shouldn't be needed. Our doc's main focus should be ECE preparations and requirements, not general knowledge like how to configure sudo.
kunisen
left a comment
kunisen
left a comment
There was a problem hiding this comment.
@eedugon thank you!
[1]
I see some order change made in 545cd4d and 48ffa2f.
I think I am not in the position of reviewing the order change is good enough and won't impact on installation or not.
My personal feeling is I can see they generally look good, but if you want to get 100% sign-off, I would recommend you reach out to ECE dev for a 2nd look.
[2]
Other than that, the changes look good in general.
There are some detailed places that I have questions, but no thing big.
For the next, if you are confident enough with the reordering per above [1], then I am fine with we merge the PR to have a much clearer OS prep docs :)
Thanks again mate!
ordering is fine, the steps were unrelated and I've tried to give better sense to the steps and their order, although in some cases the order of certain actions is completely irrelevant. Also I've tested everything step by step, and we'll be waiting for control-plane review and ack on this. |
shainaraskas
left a comment
shainaraskas
left a comment
There was a problem hiding this comment.
I don't know enough about suse to validate this from a technical perspective, but this doc is looking really nice from a content/style perspective.
I dropped some style comments throughout for you to look at, and some questions that I got stuck on that might not be super relevant to a seasoned user.
since I'm out for the next bit, don't worry about waiting on me for another loop of reviews - it's basically good to go as is.
| SLES 12 SP5 reached general support end of life on **October 31, 2024**. Use SLES 15 or later for new {{ece}} installations, and migrate existing SLES 12 SP5 hosts. | ||
| :::: | ||
|
|
||
| * [Prerequisites](#ece-configure-host-suse-prerequisites) |
There was a problem hiding this comment.
this page nav duplicates the right hand nav. do we expect people will be jumping around this guide much? if we expect people to have to do all of these steps, I would skip putting this full list in
if the steps are order-sensitive (or partially order-sensitive) we should make sure that the steps get numbered or dependencies are called out in the prose (the latter for the 'only sometimes the order matters' case)
There was a problem hiding this comment.
I've added a little extra prose to the relevant sections, the majority of them are independent.
Page nav removed. I agree it's better like this.
| sudo usermod -g <elastic_group_gid> $USER | ||
| ``` | ||
|
|
||
| ## Install Docker on SLES [ece-install-docker-sles12] |
There was a problem hiding this comment.
need an intro sentence after the heading
| * `net.ipv4.tcp_keepalive_probes` | ||
| ::: | ||
|
|
||
| ## Configure the Docker daemon [ece-configure-docker-daemon-sles12] |
There was a problem hiding this comment.
haven't been commenting on this, but pref a little tl;dr of what is being done / the role of the thing you're configuring below each heading
There was a problem hiding this comment.
included, together with the statement about data directories preparation and docker install steps should have been already performed.
| ``` | ||
|
|
||
| 4. Recommended: Tune your network settings. | ||
| Then log in again as your ECE user. |
There was a problem hiding this comment.
is this process obvious to the user?
There was a problem hiding this comment.
Yes, how to log in as a certain user or become a certain user in the OS should be obvious to the reader.
Do you prefer to put that directly in the step?
- Reboot your system and log in again as your ECE user to ensure that all configuration changes take effect:
There was a problem hiding this comment.
no preference, just wondering :)
There was a problem hiding this comment.
updated, hoping it's better now :)
Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>
Frannie-Ludmilla
left a comment
Frannie-Ludmilla
left a comment
There was a problem hiding this comment.
LGTM, maybe just a nit about a (possibly) duplicate action if the user did not exist.
Thank you for the env to test this 💻 !
|
|
||
| ```sh | ||
| sudo zypper install -y curl device-mapper lvm2 net-tools docker=24.0.7_ce-150000.198.2 net-tools | ||
| sudo usermod -aG elastic,docker $USER |
There was a problem hiding this comment.
If the user decide to create elastic as $USER then the previous
sudo useradd -m -g elastic -G docker elasticalready sets the elastic user to have elastic,docker as groups.
What I am trying to say is that if the user takes the optional step, then this step could be skipped as these groups are already assigned.
This step is important if they decide to use an already existent user and we need to add (by appending) the needed groups.
There was a problem hiding this comment.
Yeah, that step is only needed if the user didn't create a user in the previous step, good point. I'll fix it.
|
|
||
| ```sh | ||
| /dev/xvdg1 /mnt/data xfs defaults,pquota,prjquota,x-systemd.automount 0 0 | ||
| sudo install -o $USER -g elastic -d -m 700 /mnt/data |
There was a problem hiding this comment.
TBH, since I didn't know for sure whether it actually did anything (apart from returning a 0 exit code), we may suggest to check that the newly created folder has elastic (owner) and elastic (group) as well as drwx------ (700)
francescapesci@francesca-ece-suse:~> ls -ld /mnt/data
drwx------ 2 elastic elastic 6 Jul 14 16:13 /mnt/data
There was a problem hiding this comment.
I see that https://github.com/elastic/docs-content/pull/6598/changes#diff-b13773bd6f750767482d21362e706bb0570cf173593672a4afcdfe7f1b3a8e0cR471 afterwards we test it as well, so this becomes a small nit 👍🏽
There was a problem hiding this comment.
yeah, the verification is at the end of the doc. But it's a good point, I'll check this a bit further.
|
Thank you all! |
5 participants
Summary
Created by Claude
Fixes https://github.com/elastic/docs-content-internal/issues/24
Preview of main changes to review: Configure a SuSE host
🚨 SME validation needed before merge
All commands have been tested in SLES 15 SP4 by @eedugon
Tools and models used: Claude Code CLI default