Add section Embedding etcd in a Go application.

Signed-off-by: Ronald Ngounou <74538524+ronaldngounou@users.noreply.github.com>

Author: ronaldngounou

code-of-conduct.md

@@ -0,0 +1,3 @@
+# etcd Community Code of Conduct
+
+Please refer to [etcd Community Code of Conduct](https://github.com/etcd-io/etcd/blob/main/code-of-conduct.md).

content/en/blog/2025/upgrade_from_3.5_to_3.6_issue.md

@@ -0,0 +1,74 @@
+---
+title: How to Prevent a Common Failure when Upgrading etcd v3.5 to v3.6
+author:  "[Benjamin Wang](https://github.com/ahrtr), VMware by Broadcom"
+date: 2025-03-27
+draft: false
+---
+
+There is a common issue [19557][] in the etcd v3.5 to v3.6 upgrade that may cause the upgrade
+process to fail. You can find detailed information and related discussions in the issue.
+
+## TL; DR
+
+Users are required to first upgrade to etcd v3.5.20 (or a higher patch version) before upgrading
+to etcd v3.6.0. Failure to do so may result in an unsuccessful upgrade.
+
+## What's the symptom?
+
+When upgrading a multi-member etcd cluster from a version between v3.5.1 and v3.5.19 to v3.6.0,
+the upgrade may fail due to the error "`membership: too many learner member in cluster`".
+
+## What's the root cause?
+
+By default, etcd allows at most one learner member; the bootstrap process will fail if there are
+two or more learners. Due to the issue [19557][], some voting members may revert to learners when
+upgrading to v3.6.0, which may cause the upgrade to fail.
+
+The root cause is that when promoting a learner, the related change is persistently stored in
+v2store only, not in v3store. As a result, the membership data becomes inconsistent between
+the v2store and v3store.
+
+In etcd v3.5, the v2store is the source of truth for the membership data, whereas in etcd v3.6,
+the v3store is the source of truth. It's exactly the reason why the issue only occurs when
+upgrading from v3.5 to v3.6.
+
+## Which versions are impacted?
+
+The issue was introduced in etcd v3.5.1 via [13348][]. All etcd patch versions from v3.5.1 to
+v3.5.19 are affected.
+
+## Which versions contain the fix for this issue?
+
+The issue was fixed in etcd v3.5.20 via [19563][]. **Therefore, users are required to first upgrade to
+etcd v3.5.20 (or a higher patch version) before upgrading to etcd v3.6.0; otherwise, the
+upgrade may fail.**
+
+## What if users do not follow the guide?
+
+What happens if users still upgrade directly from etcd v3.5.1-v3.5.19 to v3.6.0?
+
+If the etcd cluster isn't affected by the issue, no members will revert to learners
+during the upgrade. In this case, the upgrade will succeed without any problems.
+
+If the etcd cluster has already been affected by the issue, there are two possible outcomes:
+
+- If two or more members revert to learners during the upgrade, the upgrade will fail. In that
+  case, users will have to roll back and first upgrade to etcd v3.5.20 (or a higher version)
+  before attempting to upgrade to v3.6.0 again.
+- If only one member reverts to a learner during the upgrade, the upgrade will still succeed.
+  However, the issue is that a voting member reverts to a learner, which may confuse users and
+  also affect the cluster's quorum. We addressed this issue in etcd v3.6.0-rc.3 via [19636][]
+  by automatically promoting the learner to a voting member during bootstrap.
+
+## How did we prevent this from happening again?
+
+etcd has some end-to-end (e2e) upgrade test cases, but did not detect this issue. Instead,
+it was discovered in Kubernetes' workflow test. To address this gap, we added a similar e2e
+test via [19634][], which was also backported to release-3.6 via [19662][].
+
+[19557]: https://github.com/etcd-io/etcd/issues/19557
+[13348]: https://github.com/etcd-io/etcd/pull/13348
+[19563]: https://github.com/etcd-io/etcd/pull/19563
+[19636]: https://github.com/etcd-io/etcd/pull/19636
+[19634]: https://github.com/etcd-io/etcd/pull/19634
+[19662]: https://github.com/etcd-io/etcd/pull/19662

content/en/docs/v3.4/_index.md

@@ -2,7 +2,7 @@
 title: v3.4 docs
 cascade:
   version: &vers v3.4
-  git_version_tag: v3.4.35
+  git_version_tag: v3.4.36
   is_deprecated: false
   exclude_search: true
 linkTitle: *vers

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

@@ -3,7 +3,7 @@ title: v3.5 docs
 cascade:
   version: v3.5
   versName: &name v3.5
-  git_version_tag: v3.5.17
+  git_version_tag: v3.5.21
   exclude_search: false
 linkTitle: *name
 simple_list: true

content/en/docs/v3.5/dev-guide/golang_embed_pkg.md

@@ -0,0 +1,9 @@
+---
+title: Embedding etcd in a Go Application
+weight: 3562
+description: Use etcd `embed` go package to run an etcd server within your application
+---
+
+The etcd `embed` go package provides a simple way to embed an etcd server directly into your application. 
+
+For more details, see the [embed package documentation](https://pkg.go.dev/go.etcd.io/etcd/server/v3/embed).

content/en/docs/v3.5/downgrades/downgrade_3_5.md

@@ -5,8 +5,9 @@ description: Processes, checklists, and notes on downgrading etcd from 3.5 to 3.
 ---
 
 In the general case, downgrading from etcd 3.5 to 3.4 can be a zero-downtime, rolling downgrade:
- - one by one, stop the etcd 3.5 processes and replace them with etcd 3.4 processes
- - after starting any 3.4 processes, new features in 3.5 are not longer available to the cluster
+
+- one by one, stop the etcd 3.5 processes and replace them with etcd 3.4 processes
+- after starting any 3.4 processes, new features in 3.5 are not longer available to the cluster
 
 Before [starting a downgrade](#downgrade-procedure), read through the rest of this guide to prepare.
 
@@ -163,7 +164,9 @@ etcdctl --endpoints=localhost:2379,localhost:22379,localhost:32379 endpoint stat
 +-----------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
 COMMENT
 ```
+
 If the server to be stopped is the leader, you can avoid some downtime by `move-leader` to another server before stopping this server.
+
 ```bash
 etcdctl --endpoints=localhost:2379,localhost:22379,localhost:32379 move-leader 91bc3c398fb3c146
 
@@ -199,8 +202,8 @@ When each etcd process is stopped, expected errors will be logged by other clust
 Restart the etcd server with same configuration but with the new etcd binary and `--next-cluster-version-compatible`.
 
 ```diff
--etcd-old --name s1 \
-+etcd-new --name s1 \
+-etcd-3.5/bin --name s1 \
++etcd-3.4/bin --name s1 \
   --data-dir /tmp/etcd/s1 \
   --listen-client-urls http://localhost:2379 \
   --advertise-client-urls http://localhost:2379 \
@@ -214,6 +217,7 @@ Restart the etcd server with same configuration but with the new etcd binary and
 
 The new 3.4 etcd will publish its information to the cluster. At this point, cluster will start to operate as 3.4 protocol, which is the lowest common version.
 
+```bash
 > `{"level":"info","ts":"2024-05-13T21:05:43.981445Z","caller":"membership/cluster.go:561","msg":"set initial cluster version","cluster-id":"ef37ad9dc622a7c4","local-member-id":"8211f1d0f64f3269","cluster-version":"3.0"}`
 
 > `{"level":"info","ts":"2024-05-13T21:05:43.982188Z","caller":"api/capability.go:77","msg":"enabled capabilities for version","cluster-version":"3.0"}`
@@ -225,6 +229,7 @@ The new 3.4 etcd will publish its information to the cluster. At this point, clu
 > `{"level":"info","ts":"2024-05-13T21:05:44.000672Z","caller":"etcdserver/server.go:2152","msg":"published local member to cluster through raft","local-member-id":"8211f1d0f64f3269","local-member-attributes":"{Name:infra1 ClientURLs:[http://127.0.0.1:2379]}","request-path":"/0/members/8211f1d0f64f3269/attributes","cluster-id":"ef37ad9dc622a7c4","publish-timeout":"7s"}`
 
 > `{"level":"info","ts":"2024-05-13T21:05:46.452631Z","caller":"membership/cluster.go:549","msg":"updated cluster version","cluster-id":"ef37ad9dc622a7c4","local-member-id":"8211f1d0f64f3269","from":"3.5","from":"3.4"}`
+```
 
 Verify that each member, and then the entire cluster, becomes healthy with the new 3.4 etcd binary:
 
@@ -239,7 +244,7 @@ COMMENT
 
 Un-downgraded members will log info like the following
 
-```
+```bash
 {"level":"info","ts":"2024-05-13T21:05:46.450764Z","caller":"etcdserver/server.go:2633","msg":"updating cluster version using v2 API","from":"3.5","to":"3.4"}
 {"level":"info","ts":"2024-05-13T21:05:46.452419Z","caller":"membership/cluster.go:576","msg":"updated cluster version","cluster-id":"ef37ad9dc622a7c4","local-member-id":"91bc3c398fb3c146","from":"3.5","to":"3.4"}
 {"level":"info","ts":"2024-05-13T21:05:46.452547Z","caller":"etcdserver/server.go:2652","msg":"cluster version is updated","cluster-version":"3.4"}
@@ -273,4 +278,4 @@ curl http://localhost:32379/version
 COMMENT
 ```
 
-[etcd-contact]: https://groups.google.com/g/etcd-dev
+[etcd-contact]: https://groups.google.com/g/etcd-dev

content/en/docs/v3.5/downgrades/downgrading-etcd.md

@@ -7,6 +7,5 @@ description: Documentation list for downgrading etcd clusters and applications
 This section contains documents specific to downgrading etcd clusters and applications.
 
 ## Downgrading an etcd v3.x cluster
-* [Downgrade etcd from 3.5 to 3.4](../downgrade_3_5/)
 
-[migrate-apps]: ../../op-guide/v2-migration/
+* [Downgrade etcd from 3.5 to 3.4](../downgrade_3_5/)

content/en/docs/v3.6/dev-guide/api_concurrency_reference_v3.md

@@ -13,42 +13,32 @@ The lock service exposes client-side locking facilities as a gRPC interface.
 | Lock | LockRequest | LockResponse | Lock acquires a distributed shared lock on a given named lock. On success, it will return a unique key that exists so long as the lock is held by the caller. This key can be used in conjunction with transactions to safely ensure updates to etcd only occur while holding lock ownership. The lock is held until Unlock is called on the key or the lease associate with the owner expires. |
 | Unlock | UnlockRequest | UnlockResponse | Unlock takes a key returned by Lock and releases the hold on lock. The next Lock caller waiting for the lock will then be woken up and given ownership of the lock. |
 
-
-
 ##### message `LockRequest` (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)
 
 | Field | Description | Type |
 | ----- | ----------- | ---- |
 | name | name is the identifier for the distributed shared lock to be acquired. | bytes |
 | lease | lease is the ID of the lease that will be attached to ownership of the lock. If the lease expires or is revoked and currently holds the lock, the lock is automatically released. Calls to Lock with the same lease will be treated as a single acquisition; locking twice with the same lease is a no-op. | int64 |
 
-
-
 ##### message `LockResponse` (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)
 
 | Field | Description | Type |
 | ----- | ----------- | ---- |
 | header |  | etcdserverpb.ResponseHeader |
 | key | key is a key that will exist on etcd for the duration that the Lock caller owns the lock. Users should not modify this key or the lock may exhibit undefined behavior. | bytes |
 
-
-
 ##### message `UnlockRequest` (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)
 
 | Field | Description | Type |
 | ----- | ----------- | ---- |
 | key | key is the lock ownership key granted by Lock. | bytes |
 
-
-
 ##### message `UnlockResponse` (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)
 
 | Field | Description | Type |
 | ----- | ----------- | ---- |
 | header |  | etcdserverpb.ResponseHeader |
 
-
-
 ##### service `Election` (server/etcdserver/api/v3election/v3electionpb/v3election.proto)
 
 The election service exposes client-side election facilities as a gRPC interface.
@@ -61,8 +51,6 @@ The election service exposes client-side election facilities as a gRPC interface
 | Observe | LeaderRequest | LeaderResponse | Observe streams election proclamations in-order as made by the election's elected leaders. |
 | Resign | ResignRequest | ResignResponse | Resign releases election leadership so other campaigners may acquire leadership on the election. |
 
-
-
 ##### message `CampaignRequest` (server/etcdserver/api/v3election/v3electionpb/v3election.proto)
 
 | Field | Description | Type |
@@ -71,17 +59,13 @@ The election service exposes client-side election facilities as a gRPC interface
 | lease | lease is the ID of the lease attached to leadership of the election. If the lease expires or is revoked before resigning leadership, then the leadership is transferred to the next campaigner, if any. | int64 |
 | value | value is the initial proclaimed value set when the campaigner wins the election. | bytes |
 
-
-
 ##### message `CampaignResponse` (server/etcdserver/api/v3election/v3electionpb/v3election.proto)
 
 | Field | Description | Type |
 | ----- | ----------- | ---- |
 | header |  | etcdserverpb.ResponseHeader |
 | leader | leader describes the resources used for holding leadereship of the election. | LeaderKey |
 
-
-
 ##### message `LeaderKey` (server/etcdserver/api/v3election/v3electionpb/v3election.proto)
 
 | Field | Description | Type |
@@ -91,58 +75,44 @@ The election service exposes client-side election facilities as a gRPC interface
 | rev | rev is the creation revision of the key. It can be used to test for ownership of an election during transactions by testing the key's creation revision matches rev. | int64 |
 | lease | lease is the lease ID of the election leader. | int64 |
 
-
-
 ##### message `LeaderRequest` (server/etcdserver/api/v3election/v3electionpb/v3election.proto)
 
 | Field | Description | Type |
 | ----- | ----------- | ---- |
 | name | name is the election identifier for the leadership information. | bytes |
 
-
-
 ##### message `LeaderResponse` (server/etcdserver/api/v3election/v3electionpb/v3election.proto)
 
 | Field | Description | Type |
 | ----- | ----------- | ---- |
 | header |  | etcdserverpb.ResponseHeader |
 | kv | kv is the key-value pair representing the latest leader update. | mvccpb.KeyValue |
 
-
-
 ##### message `ProclaimRequest` (server/etcdserver/api/v3election/v3electionpb/v3election.proto)
 
 | Field | Description | Type |
 | ----- | ----------- | ---- |
 | leader | leader is the leadership hold on the election. | LeaderKey |
 | value | value is an update meant to overwrite the leader's current value. | bytes |
 
-
-
 ##### message `ProclaimResponse` (server/etcdserver/api/v3election/v3electionpb/v3election.proto)
 
 | Field | Description | Type |
 | ----- | ----------- | ---- |
 | header |  | etcdserverpb.ResponseHeader |
 
-
-
 ##### message `ResignRequest` (server/etcdserver/api/v3election/v3electionpb/v3election.proto)
 
 | Field | Description | Type |
 | ----- | ----------- | ---- |
 | leader | leader is the leadership to relinquish by resignation. | LeaderKey |
 
-
-
 ##### message `ResignResponse` (server/etcdserver/api/v3election/v3electionpb/v3election.proto)
 
 | Field | Description | Type |
 | ----- | ----------- | ---- |
 | header |  | etcdserverpb.ResponseHeader |
 
-
-
 ##### message `Event` (api/mvccpb/kv.proto)
 
 | Field | Description | Type |
@@ -151,8 +121,6 @@ The election service exposes client-side election facilities as a gRPC interface
 | kv | kv holds the KeyValue for the event. A PUT event contains current kv pair. A PUT event with kv.Version=1 indicates the creation of a key. A DELETE/EXPIRE event contains the deleted key with its modification revision set to the revision of deletion. | KeyValue |
 | prev_kv | prev_kv holds the key-value pair before the event happens. | KeyValue |
 
-
-
 ##### message `KeyValue` (api/mvccpb/kv.proto)
 
 | Field | Description | Type |
@@ -164,5 +132,3 @@ The election service exposes client-side election facilities as a gRPC interface
 | value | value is the value held by the key, in bytes. | bytes |
 | lease | lease is the ID of the lease that attached to key. When the attached lease expires, the key will be deleted. If lease is 0, then no lease is attached to the key. | int64 |
 
-
-