fix: update quick start documentation #956

NotAwar · 2025-02-23T20:02:04Z

Fix update quick start documentation

Description

Updated documentation according to issue #782 , also added more links and split documentation into two paths development and operations. Not sure if this is what @dwelsch-esi is looking for, but hopefully it's at least close!

Related Issue

#782

Preview

https://deploy-preview-956--etcd.netlify.app/docs/v3.5/quickstart/

Contrast with:

https://etcd.io/docs/v3.5/quickstart/

k8s-ci-robot · 2025-02-23T20:02:09Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: NotAwar
Once this PR has been reviewed and has the lgtm label, please assign jmhbnz 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-02-23T20:02:14Z

Hi @NotAwar. 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.

NotAwar · 2025-02-23T20:10:39Z

/assign @jmhbnz

NotAwar · 2025-02-26T20:09:53Z

need okay from owners so:
/unassign @jmhbnz

requesting review from the only people who have committed to this file previously:
/cc @nate-double-u
/cc @chalin

nate-double-u

Hi @NotAwar,

Thanks for this. I've gone through and made some line-by-line comments , which I'll leave here for reference because some of the comments are generally applicable, but the more significant issue is that I'm not sure we need this change.

The main shift in this PR is breaking out the developer workflow from the operator workflow. I don't think this page needs that complexity, and the operator workflow would be so similar (at least as presented here) that it shouldn't be required for someone looking to set up etcd quickly for an evaluation (this page's audience is a decision maker who wouldn't necessarily need to know all the ins and outs of an etcd installation for production).

nate-double-u · 2025-02-27T00:01:40Z

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

+      ```
+
+   3. **Configure and Secure etcd**  
+      Check out the Operator Guide for steps on clustering, securing with TLS, and performance tuning.


Is there a link we could provide here?

I added some links checkout the latest changes to this section

nate-double-u · 2025-02-27T00:02:44Z

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

+   1. **etcd Installed**  
+      Build or download etcd from [Install][] and verify that the `etcd` binary is in your system’s PATH.
+      {{% alert color="warning" %}}**Important**: Ensure that you perform the last
+      step of the installation instructions to verify that `etcd` is in your path.
+      {{% /alert %}}


do we also need to prompt folks to install etcdctl separately? (I needed to on my test setup)

I'm not sure we need an alert here referring to the content of another page. We can trust that folks will follow the instructions there.

do we also need to prompt folks to install etcdctl separately? (I needed to on my test setup)

I think this depends on your install method, if you build from the binaries you might have to prompt for etcdctl separately. I did a clean "brew install etcd", after which both "etcd" and "etcdctl" were added to my path and were viable commands.

For command "etcd --version":

etcd Version: 3.5.18 Git SHA: 5bca08ec1 Go Version: go1.23.5 Go OS/Arch: darwin/arm64

For command "etcdctl version":

etcdctl version: 3.5.18 API version: 3.5

removed the alert, diff

OK, let's leave it as is then (no need for an extra prompt), we can leave the details of various ways of installing to the installation page.

nate-double-u · 2025-02-27T00:04:24Z

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

+      ```console
+      $ etcd
+      {"level":"info","ts":"2021-09-17T09:19:32.783-0400","caller":"etcdmain/etcd.go:72","msg":... }
+      ⋮
+      ```
+
+      {{% alert color="info" %}}**Note**: The output produced by `etcd` are
+      [logs](../op-guide/configuration/#logging) &mdash; info-level logs can
+      be ignored. {{% /alert %}}
+
+   2. **Interact with etcd**  
+      In a separate terminal, run the following commands to set and retrieve a key:
+
+      ```console
+      $ etcdctl put greeting "Hello, etcd"
+      OK
+      ```
+
+      ```console
+      $ etcdctl get greeting
+      greeting
+      Hello, etcd
+      ```


I tested this locally using lima with an ubuntu image, these instructions work.

Ty for confirmation! 😄

nate-double-u · 2025-02-27T00:08:15Z

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

+Continue with the [Developer guide][], which includes the [Set up a local cluster][] page, [API][] references, and integration examples.
+
+- #### Explore the gRPC [API][]
+
+- #### Find [language bindings and tools][integrations]
+
+- ### **Operations:**
+
+Proceed to the [Operations guide][] for advanced configuration, clustering, security, and performance tuning.
+
+- #### Set up a [multi-machine cluster][clustering]
+
+- #### Use TLS to [secure an etcd cluster][security]
+
+- #### [Tune etcd][tuning]
+
+- #### Learn how to [configure][] etcd


This section feels incomplete and doesn't seem to render correctly. Please take a look a the deploy preview.

Also, i recommend against using links in headings. See https://kubernetes.io/docs/contribute/style/style-guide/#headings.

I was kind of unsure as to how this would render and also how the content should be displayed, I changed it, though as has been mentioned in #782 I believe this section should probably just point to "Getting Started" for the dev-guide and op-guide

nate-double-u · 2025-02-27T05:48:03Z

I've struck some of my initial comments based on the issue that this PR is based on.

dwelsch-esi · 2025-02-27T17:10:11Z

Hi @NotAwar,

Thanks for this. I've gone through and made some line-by-line comments , which I'll leave here for reference because some of the comments are generally applicable, but the more significant issue is that I'm not sure we need this change.

The main shift in this PR is breaking out the developer workflow from the operator workflow. I don't think this page needs that complexity, and the operator workflow would be so similar (at least as presented here) that it shouldn't be required for someone looking to set up etcd quickly for an evaluation (this page's audience is a decision maker who wouldn't necessarily need to know all the ins and outs of an etcd installation for production).

@NotAwar ,

The single-node install is suitable for development/test/evaluation only. This change makes that clear, but I think @nate-double-u 's point (correct me if I'm wrong, Nate) is that a Quick Start page might not be the best place to describe the production server install.

An alternative that might satisfy all the concerns here: make it clear on the Quick Start page that the one-node quick install is appropriate for dev/test/eval, and instead of including the "full" install in the Quick Start, point admin/production users to the full install page.

Again, the point of my suggestion is to clearly explain that these are two different install procedures with two vastly different use cases. This might be understood by most non-novice users, but it's not spelled out in the documentation. It doesn't take much effort to avoid confusion and guide users to the appropriate procedure for their use case.

chalin

Thanks @NotAwar.

@dwelsch-esi and @nate-double-u - I think that we need to clarify the guidance / suggestions of #782 first before making progress here. See #782 (comment).

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

NotAwar

GH quickstart template also uses one word.

https://docs.github.com/en/contributing/writing-for-github-docs/templates#quickstart-article-template

chalin · 2025-02-27T18:06:42Z

@NotAwar - also please sign all commits in this PR per DCO requirements.

nate-double-u · 2025-02-27T21:50:51Z

@NotAwar, in the checks box you can find the DCO check -- it doesn't look like one, but it's a link that goes to a page that will show you how to solve the DCO issue.

Signed-off-by: Awar Abdulkarim <[email protected]>

Bumps [hugo-extended](https://github.com/jakejarvis/hugo-extended) from 0.143.1 to 0.144.2. - [Commits](jakejarvis/hugo-extended@v0.143.1...v0.144.2) --- updated-dependencies: - dependency-name: hugo-extended dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: Awar Abdulkarim <[email protected]>

Bumps [netlify-cli](https://github.com/netlify/cli) from 18.1.0 to 19.0.0. - [Release notes](https://github.com/netlify/cli/releases) - [Changelog](https://github.com/netlify/cli/blob/main/CHANGELOG.md) - [Commits](netlify/cli@v18.1.0...v19.0.0) --- updated-dependencies: - dependency-name: netlify-cli dependency-type: direct:development update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: Awar Abdulkarim <[email protected]>

NotAwar · 2025-02-27T22:47:28Z

Could have probably done this more cleanly, but ty very much @nate-double-u and @chalin
All commits will be signed off and verified from now thanks to you two ❤️

Signed-off-by: Awar Abdulkarim <[email protected]>

jberkus

The updates to versions need to go in a separate PR.

Overall: I can see what you're doing with reorganizing quickstart, and it makes sense. However, this needs to go on a development branch, because we can't merge it into main until all supporting documents are written. Would you like me to create a dev branch?

jberkus · 2025-03-13T18:07:36Z

package.json

@@ -19,9 +19,9 @@
  "devDependencies": {
    "autoprefixer": "^10.4.20",
    "docsy": "github:google/docsy#semver:0.11.0",
-    "hugo-extended": "0.143.1",
+    "hugo-extended": "0.144.2",


Please do not roll version upgrades together with content changes. This should be a separate PR.

jberkus · 2025-03-13T18:07:45Z

package.json

    "mkdirp": "^3.0.1",
-    "netlify-cli": "^18.0.1",
+    "netlify-cli": "^19.0.0",


Please do not roll version upgrades together with content changes. This should be a separate PR.

chalin · 2025-03-13T19:08:26Z

@dwelsch-esi and @nate-double-u - I think that we need to clarify the guidance / suggestions of #782 first before making progress here. See #782 (comment).

@dwelsch-esi @nate-double-u and now @jberkus - my concerns still stand: IMHO we need to discuss the issue guidance before trying to resolve it. It is counter productive to do while working through a proposal in this PR.

How about we meet during the next "CNCF Tech Writers Office Hours" time slot (Wed. March 26 11 am ET)?

nate-double-u · 2025-03-13T19:12:07Z

How about we meet during the next "CNCF Tech Writers Office Hours" time slot (Wed. March 26 11 am ET)?

+1, I'll be there :)

NotAwar · 2025-03-14T12:00:34Z

Would you like me to create a dev branch?

Yes please! Will revert version bumps in this branch.

k8s-ci-robot added the needs-ok-to-test label Feb 23, 2025

k8s-ci-robot added the size/L label Feb 23, 2025

k8s-ci-robot assigned jmhbnz Feb 23, 2025

k8s-ci-robot unassigned jmhbnz Feb 26, 2025

k8s-ci-robot requested review from chalin and nate-double-u February 26, 2025 20:09

nate-double-u reviewed Feb 27, 2025

View reviewed changes

chalin requested changes Feb 27, 2025

View reviewed changes

content/en/docs/v3.5/quickstart.md Outdated Show resolved Hide resolved

NotAwar commented Feb 27, 2025

View reviewed changes

NotAwar and others added 5 commits February 27, 2025 23:43

fix: Update quickstart.md

48726f2

Signed-off-by: Awar Abdulkarim <[email protected]>

fix: update quickstart.md

cbe135e

Signed-off-by: Awar Abdulkarim <[email protected]>

fix: Update quickstart.md based on feedback

eb99def

Signed-off-by: Awar Abdulkarim <[email protected]>

NotAwar force-pushed the patch-1 branch from 343762c to 383a9ab Compare February 27, 2025 22:44

fix: change title to Quickstart

6213632

Signed-off-by: Awar Abdulkarim <[email protected]>

NotAwar requested a review from chalin March 1, 2025 11:39

jberkus requested changes Mar 13, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: update quick start documentation #956

fix: update quick start documentation #956

NotAwar commented Feb 23, 2025 •

edited by chalin

Loading

k8s-ci-robot commented Feb 23, 2025

k8s-ci-robot commented Feb 23, 2025

NotAwar commented Feb 23, 2025

NotAwar commented Feb 26, 2025

nate-double-u left a comment •

edited

Loading

nate-double-u Feb 27, 2025

NotAwar Feb 27, 2025

nate-double-u Feb 27, 2025

nate-double-u Feb 27, 2025

NotAwar Feb 27, 2025

NotAwar Feb 27, 2025

nate-double-u Feb 28, 2025

nate-double-u Feb 27, 2025

NotAwar Feb 27, 2025

nate-double-u Feb 27, 2025

NotAwar Feb 27, 2025

nate-double-u commented Feb 27, 2025

dwelsch-esi commented Feb 27, 2025

chalin left a comment

NotAwar left a comment

chalin commented Feb 27, 2025

nate-double-u commented Feb 27, 2025 •

edited

Loading

NotAwar commented Feb 27, 2025

jberkus left a comment

jberkus Mar 13, 2025

jberkus Mar 13, 2025

chalin commented Mar 13, 2025

nate-double-u commented Mar 13, 2025

NotAwar commented Mar 14, 2025

fix: update quick start documentation #956

Are you sure you want to change the base?

fix: update quick start documentation #956

Conversation

NotAwar commented Feb 23, 2025 • edited by chalin Loading

Fix update quick start documentation

Description

Related Issue

Preview

k8s-ci-robot commented Feb 23, 2025

k8s-ci-robot commented Feb 23, 2025

NotAwar commented Feb 23, 2025

NotAwar commented Feb 26, 2025

nate-double-u left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nate-double-u commented Feb 27, 2025

dwelsch-esi commented Feb 27, 2025

chalin left a comment

Choose a reason for hiding this comment

NotAwar left a comment

Choose a reason for hiding this comment

chalin commented Feb 27, 2025

nate-double-u commented Feb 27, 2025 • edited Loading

NotAwar commented Feb 27, 2025

jberkus left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chalin commented Mar 13, 2025

nate-double-u commented Mar 13, 2025

NotAwar commented Mar 14, 2025

NotAwar commented Feb 23, 2025 •

edited by chalin

Loading

nate-double-u left a comment •

edited

Loading

nate-double-u commented Feb 27, 2025 •

edited

Loading