Add Prereq section and rewrite Quickstart for local etcd setup #981

ronaldngounou · 2025-04-14T02:47:10Z

Approach

This PR contributes to the step (2) of the issue #782.

Improves the Quickstart instructions to be clearer, more beginner-friendly, and platform-specific. Add installation commands, port and data path explanations, endpoint flags, and cleanup steps.

Key Improvements:
- Requirements section added.
- Specifies supported OS and architecture
- Provides explicit commands for installing etcd via pre-built binaries
- Includes --endpoints flag for etcdctl to avoid implicit configuration issues
- Adds shutdown instructions
- Maintains fast-start approach while being easier to grasp for new users

As a result, this make the starter page more beginner friendly.

Testing

npm run serve

k8s-ci-robot · 2025-04-14T02:47:15Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: ronaldngounou
Once this PR has been reviewed and has the lgtm label, please assign spzala for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot · 2025-04-14T02:47:21Z

Hi @ronaldngounou. Thanks for your PR.

I'm waiting for a etcd-io member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

spzala · 2025-04-15T15:28:36Z

/ok-to-test

ronaldngounou · 2025-04-15T15:39:59Z

@spzala
I see that most of my testcases failed because of markdown normalization.
Is there a way to run the tests locally before raising a PR?
That would be helpful.
Thank you

ronaldngounou · 2025-04-16T03:46:53Z

I'm taking a look at this merged PR to fix the remaining markdown lint.

ronaldngounou · 2025-04-16T04:11:40Z

The commit ID 0ae2c81 aims to fix the issue #980
Thanks, cc @spzala

spzala

@ronaldngounou thanks for working on it. It will help if you break down the changes in separate PRs or commits (per task- e.g., pre-req as one change) to help with review.
In the PR description you have mentioned that this PR is for pre-req section for the other issue comment(s) from @chalin but I don't see any pre-req section in your changes. Also, I didn't understand why you have removed link for install (i.e. https://etcd.io/docs/v3.5/install/) and added install instructions. If you provide a small section wide PRs/commits with reasons for making changes, it will help review better. Thanks again!

ronaldngounou · 2025-04-16T20:53:11Z

Thanks for the feedback. @spzala

In the PR description you have mentioned that this PR is for pre-req section for the other issue comment(s) from @chalin but I don't see any pre-req section in your changes.

I replaced the prerequisites section with requirements for a better wording. Would that be okay if I rename Requirements to prerequisites?

As @dwelsch-esi mentioned in this post,

The goal of the quick start is to get a working instance of the software running as quickly as possible. Usually this is a pared-down version: a local installation, a single-node instance of cluster software, that sort of thing. Other characteristics of a quick-start installation:

Often this installation is suitable for a demo or for development, but rarely is it suitable for production.
There might be some assumptions, such as a particular OS or installation method (a container image, for example, or a package-managed install). It's never built from code.
It's a one-size-fits-all install. If the user has an unusual platform or needs a feature not found in the quick-start version, they have to use a different install.
The quick start guide is short and contains simplified instructions.

I think having a short quickstart page would help the user get up to speed faster. In addition, after this is closed, I will restructure the installation page as @dwelsch-esi suggested.

If you provide a small section wide PRs/commits with reasons for making changes, it will help review better.

What can I do now in order to help review better? I will take note of this for my next PR.
Are there any other best practices you recommend I follow moving forward? Should I squash my commits?

dwelsch-esi · 2025-04-16T20:59:42Z

I replaced the prerequisites section with requirements for a better wording. Would that be okay if I rename Requirements to prerequisites?

@ronaldngounou I prefer "Prerequisites" because it cues the reader that it's something they need to do before the procedure. I think either will work. Most importantly, I'd advise being consistent throughout the documentation. That is, all the procedures in the documentation should use the same term.

ronaldngounou · 2025-04-16T21:49:47Z

Alright. I will change that and submit a PR.

ronaldngounou · 2025-04-19T01:24:55Z

I reworded "Requirements" into Prerequisities.
In all, the prerequisites section is added and the Quickstart section for local etcd set up is made. ✅

@spzala: After your approval, I will revise the installation guide. ref issue

spzala

Thanks @ronaldngounou Please see my inline comments.

spzala · 2025-04-21T14:22:37Z

content/en/docs/v3.5/quickstart.md

+Make sure you're on a supported platform before getting started:

- 2. Launch `etcd`:
+- Operating System: Ubuntu 22.04+ or macOS 11+. Windows users can use WSL2.


Where did you get these operating systems? This is what we have as supported platform, https://etcd.io/docs/v3.5/op-guide/supported-platform/ I would suggest to provide a link here. Keeping one page for for supported platforms will avoid need for dual maintenance as well.

@spzala I agree that normally maintaining duplicate information isn't worth it. However, the Quick Start guide is a special case. The prereqs here should be only the OSes that can be installed using the quick start procedure. The regular installation guide should be a detailed guide to all installations.

@dwelsch-esi thanks for your thoughts here and other places! I agree and I also like as much as information on the same page (vs links). It's just that if we run into two set of instructions (due to dual maintenance when we forgot to make changes at both places when something change) that doesn't match that will be bad.

spzala · 2025-04-21T14:22:41Z

content/en/docs/v3.5/quickstart.md

+- [Supported platforms architecture](/docs/v3.5/op-guide/)
+- Tools installed:
+  - `curl` and `tar`
+  - Internet connection to download the latest etcd [release](https://github.com/etcd-io/etcd/releases/).


I don't think we want to put 'internet connection' as a pre-req. It's implied usually with every tools that need download.

@spzala I agree. Internet is pretty much assumed these days.

spzala · 2025-04-21T14:24:51Z

content/en/docs/v3.5/quickstart.md

-    {{% alert color="info" %}}**Note**: The output produced by `etcd` are
-    [logs](../op-guide/configuration/#logging) &mdash; info-level logs can
-    be ignored. {{% /alert %}}
+### 1. Installation


We have this dedicated page for install - https://etcd.io/docs/v3.5/install/ We should try to avoid dual maintenance. I would suggest to make the install page better and provide a link to it from here. That way if anything change with installation steps, we just need to make change to one place.

ronaldngounou · 2025-04-22T03:25:05Z

The check regarding the deployment failed. After investigation:

Logs

8:14:48 PM: docs/v3.5/quickstart/index.html
8:14:48 PM:   target does not exist --- docs/v3.5/quickstart/index.html --> docs/v3.5/install/
8:14:51 PM: Failed during stage 'building site': Build script returned non-zero exit code: 2 (https://ntl.fyi/exit-code-2)
8:14:51 PM: ========================================================================
8:14:51 PM: ✘✘✘ failed in 13.176224914s
8:14:51 PM: 1 errors in 515 documents
8:14:51 PM: make: *** [Makefile:14: check-links] Error 1
8:14:51 PM: 
8:14:51 PM: "build.command" failed                                        
8:14:51 PM: ────────────────────────────────────────────────────────────────

On my side, npm run serve is not building the website. It worked fine the last time I ran it.
I had to build it using hugo serve

spzala

@ronaldngounou good progress but please see few inline comments. Thanks!

spzala · 2025-04-23T19:16:51Z

content/en/docs/v3.5/install.md


- [Supported platforms][]
- [Hardware recommendations][]
+- [Supported platforms](/docs/v3.5/op-guide/supported-platform)


Here and other places where you are adding links in bracket. I believe you don't need to that and you can leave what was in the original file. The links at the bottom of the fule takes care of it.

spzala · 2025-04-23T19:18:02Z

content/en/docs/v3.5/install.md

 ## Install pre-built binaries

-The easiest way to install etcd is from pre-built binaries:
+Install `etcd` from pre-built binaries using cURL.


I would remove using cURL explicitly as other tools can be used. I like the steps you provided below.

spzala · 2025-04-23T19:19:08Z

content/en/docs/v3.5/install.md

-    directory created by the previous step to your path.
- 4. From a shell, test that `etcd` is in your path:
+   ```bash
+   # Download and extract the latest release using cURL


Here, good idea to add in the comment v3.5.21 as an example as it will not be the latest release always. So something like, "# Download and extract the latest release using cURL. For example, download v3.5.21 as below."

spzala · 2025-04-23T19:24:14Z

content/en/docs/v3.5/quickstart.md

-[security]: /docs/{{< param version >}}/op-guide/security
-[tuning]: /docs/{{< param version >}}/tuning
-[Install]: ../install/
+- If you are a developer:


Please keep these consistent.
i.e. "- If you are a developer:" vs "If you are an operator or admin:".

ronaldngounou · 2025-05-02T04:05:49Z

/retest

jberkus · 2025-06-03T17:50:40Z

@ronaldngounou can you rebase this now that your other PR is merged?

Also, remember to drop .gitignore and package.json from the commit. Thanks.

Signed-off-by: Ronald Ngounou <[email protected]>

…single new line character Signed-off-by: Ronald Ngounou <[email protected]>

It breaks when a Hugo parameter is in the linked URL. Refer to issue DavidAnson/markdownlint#1619 Signed-off-by: Ivan Valdes <[email protected]>

Signed-off-by: Ronald Ngounou <[email protected]>

k8s-ci-robot added the needs-ok-to-test label Apr 14, 2025

k8s-ci-robot added the size/L label Apr 14, 2025

ronaldngounou mentioned this pull request Apr 15, 2025

Revise the installation guide #770

Open

k8s-ci-robot added ok-to-test and removed needs-ok-to-test labels Apr 15, 2025

ronaldngounou force-pushed the issue872-prereq branch 4 times, most recently from c838332 to 0ae2c81 Compare April 16, 2025 04:09

ronaldngounou mentioned this pull request Apr 16, 2025

Revise the "What's next" section to focus on two separate paths #980

Closed

spzala reviewed Apr 16, 2025

View reviewed changes

spzala reviewed Apr 21, 2025

View reviewed changes

spzala reviewed Apr 23, 2025

View reviewed changes

ronaldngounou added 4 commits June 3, 2025 20:20

rewrite Quickstart for local etcd setup

2b64717

Signed-off-by: Ronald Ngounou <[email protected]>

Fix quickstart page to respect markdownlint normalization rules

0b8501e

Signed-off-by: Ronald Ngounou <[email protected]>

Fix lint error related to website references

6f836b4

Signed-off-by: Ronald Ngounou <[email protected]>

Fix lint error: files should end with a single line character

6e149d5

Signed-off-by: Ronald Ngounou <[email protected]>

ronaldngounou and others added 10 commits June 3, 2025 20:21

issue980 Revise the Whats next section to focus on two separate paths

4599aed

Signed-off-by: Ronald Ngounou <[email protected]>

Reword Requirements into Prerequisites

f4a4ae5

Signed-off-by: Ronald Ngounou <[email protected]>

Relocate section steps to install from binaries to installation page

bcee763

Signed-off-by: Ronald Ngounou <[email protected]>

Fixing markdown lint errors

a282e42

Signed-off-by: Ronald Ngounou <[email protected]>

Remove links in brackets to conform with original file

7de068f

Signed-off-by: Ronald Ngounou <[email protected]>

Maintain consistency in links and Next Steps in Quickstart section

963af96

Signed-off-by: Ronald Ngounou <[email protected]>

Fix lint error MD047/single-trailing-newline Files should end with a …

5026a85

…single new line character Signed-off-by: Ronald Ngounou <[email protected]>

Disable markdownlint MD052 rule

1413368

It breaks when a Hugo parameter is in the linked URL. Refer to issue DavidAnson/markdownlint#1619 Signed-off-by: Ivan Valdes <[email protected]>

Revise what's next section to focus on two separate paths.

2b65eae

Signed-off-by: Ronald Ngounou <[email protected]>

Fix lint errors indentation

4cffd5d

Signed-off-by: Ronald Ngounou <[email protected]>

ronaldngounou force-pushed the issue872-prereq branch from 2b532fc to 4cffd5d Compare June 4, 2025 03:23

ronaldngounou closed this Oct 1, 2025

Add Prereq section and rewrite Quickstart for local etcd setup #981

Add Prereq section and rewrite Quickstart for local etcd setup #981

Uh oh!

Conversation

ronaldngounou commented Apr 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Approach

Testing

Uh oh!

k8s-ci-robot commented Apr 14, 2025

Uh oh!

k8s-ci-robot commented Apr 14, 2025

Uh oh!

spzala commented Apr 15, 2025

Uh oh!

ronaldngounou commented Apr 15, 2025

Uh oh!

ronaldngounou commented Apr 16, 2025

Uh oh!

ronaldngounou commented Apr 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

spzala left a comment

Choose a reason for hiding this comment

Uh oh!

ronaldngounou commented Apr 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dwelsch-esi commented Apr 16, 2025

Uh oh!

ronaldngounou commented Apr 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ronaldngounou commented Apr 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

spzala left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ronaldngounou commented Apr 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

spzala left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ronaldngounou commented May 2, 2025

Uh oh!

jberkus commented Jun 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

ronaldngounou commented Apr 14, 2025 •

edited

Loading

ronaldngounou commented Apr 16, 2025 •

edited

Loading

ronaldngounou commented Apr 16, 2025 •

edited

Loading

ronaldngounou commented Apr 16, 2025 •

edited

Loading

ronaldngounou commented Apr 19, 2025 •

edited

Loading

ronaldngounou commented Apr 22, 2025 •

edited

Loading

jberkus commented Jun 3, 2025 •

edited

Loading