diff --git a/content/en/docs/v3.4/how-to-migrate.md b/content/en/docs/v3.4/how-to-migrate.md
index a29a19ae8..b0eaea396 100644
--- a/content/en/docs/v3.4/how-to-migrate.md
+++ b/content/en/docs/v3.4/how-to-migrate.md
@@ -13,11 +13,13 @@ etcd v2.Y releases store data in the v2store, which supports the legacy API v2.
This document focus on how to migrate existing data from the v2store to the v3store. For a detailed guideline of migrating from API v2 to API v3, please refer to [Migrate applications from using API v2 to API v3](https://etcd.io/docs/v3.4/op-guide/v2-migration/).
{{% alert color="warning" %}}
+
⚠️ **Deprecated functionality:**
The `etcdctl migrate` command was removed in etcd v3.5.0 ([pull/12971](https://github.com/etcd-io/etcd/pull/12971)). If your etcd cluster is already running v3.5 or higher, you can no longer migrate v2store to v3store using this method.
You **must use etcdctl v3.4 or earlier** to perform the migration (View note from [CHANGELOG-3.5](https://github.com/ahrtr/etcd/blob/main/CHANGELOG/CHANGELOG-3.5.md#etcdctl-v3-3)). However please take appropriate precautions when using it, as it is no longer officially supported or tested in recent releases.
+
{{% /alert %}}
## Pre-requisites
diff --git a/content/en/docs/v3.4/op-guide/v2-migration.md b/content/en/docs/v3.4/op-guide/v2-migration.md
index c21d2c35f..cc48ed10d 100644
--- a/content/en/docs/v3.4/op-guide/v2-migration.md
+++ b/content/en/docs/v3.4/op-guide/v2-migration.md
@@ -41,9 +41,11 @@ First, all members in the etcd cluster must converge to the same state. This can
Second, migrate the v2 keys into v3 with the [migrate][migrate_command] (`ETCDCTL_API=3 etcdctl migrate`) command. The migrate command writes keys in the v2 store to a user-provided transformer program and reads back transformed keys. It then writes transformed keys into the mvcc store. This usually takes at most tens of seconds.
{{% alert title="known issue" color="warning" %}}
+
The migrate command has a known issue that new members added after the migration do not receive existing data if no .snap file exists.
The workaround is to perform a snapshot restore after the migration.
For more information see [GitHub issue](https://github.com/etcd-io/etcd/issues/8804).
+
{{% /alert %}}
Restart the etcd members and everything should just work.
diff --git a/content/en/docs/v3.5/op-guide/configuration.md b/content/en/docs/v3.5/op-guide/configuration.md
index f99ae08a2..0b4546f3e 100644
--- a/content/en/docs/v3.5/op-guide/configuration.md
+++ b/content/en/docs/v3.5/op-guide/configuration.md
@@ -13,11 +13,13 @@ You can configure etcd through the following:
- **[Configuration file](#configuration-file)**
{{% alert color="warning" %}}
+
**Caution**: If you mix-and-match configuration options, then the following
rules apply.
- Command-line flags take precedence over environment variables.
- If you provide a _configuration file_ all command-line flags and environment variables are **ignored**.
+
{{% /alert %}}
## Command-line flags
@@ -27,10 +29,12 @@ Flags are presented below using the format `--flag-name DEFAULT_VALUE`.
The list of flags provided below may not be up-to-date due to ongoing development changes. For the latest available flags, run `etcd --help` or refer to the [etcd help][].
{{% alert color="info" %}}
+
**Note**: For details concerning new, updated, and deprecated {{< param version >}} flags,
see [CHANGELOG-{{< psubstr version 1 >}}.md][changelog].
[changelog]: https://github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-{{< psubstr version 1 >}}.md
+
{{% /alert %}}
### Member
@@ -227,7 +231,9 @@ The list of flags provided below may not be up-to-date due to ongoing developmen
### v2 Proxy
{{% alert color="warning" %}}
+
** Note**: flags will be deprecated in v3.6.
+
{{% /alert %}}
@@ -272,7 +278,9 @@ The list of flags provided below may not be up-to-date due to ongoing developmen
### Unsafe features
{{% alert color="warning" %}}
+
** Warning**: using unsafe features may break the guarantees given by the consensus protocol!
+
{{% /alert %}}
```nocode
diff --git a/content/en/docs/v3.5/op-guide/monitoring.md b/content/en/docs/v3.5/op-guide/monitoring.md
index 39109b82a..c8f8864b7 100644
--- a/content/en/docs/v3.5/op-guide/monitoring.md
+++ b/content/en/docs/v3.5/op-guide/monitoring.md
@@ -139,7 +139,9 @@ Now Prometheus will scrape etcd metrics every 10 seconds.
There is a set of [default alerts](https://github.com/etcd-io/etcd/tree/master/contrib/mixin) for etcd v3 clusters for Prometheus.
{{% alert title="Note" color="info" %}}
+
Note that `job` labels may need to be adjusted to fit a particular need. The rules were written to apply to a single cluster so it is recommended to choose labels unique to a cluster.
+
{{% /alert %}}
### Grafana
@@ -164,7 +166,9 @@ Sample dashboard:
In v3.5 etcd has added support for distributed tracing using [OpenTelemetry](https://github.com/open-telemetry).
{{% alert title="Note" color="info" %}}
+
This feature is still experimental and can change at any time.
+
{{% /alert %}}
To enable this experimental feature, pass the `--experimental-enable-distributed-tracing=true` to the etcd server, along with the `--experimental-distributed-tracing-sampling-rate=` flag to choose how many samples to collect per million spans, the default sampling rate is `0`.
@@ -180,7 +184,9 @@ Configure the distributed tracing by starting etcd server with the following opt
Before enabling the distributed tracing, make sure to have the OpenTelemetry endpoint, if that address differs to the default one, override with the `--experimental-distributed-tracing-address` flag. Due to OpenTelemetry having different ways of running, refer to the [collector documentation](https://opentelemetry.io/docs/collector/getting-started/) to learn more.
{{% alert title="Note" color="info" %}}
+
There is a resource overhead, as with any observability signal, according to our initial measurements that overhead could be between 2% - 4% CPU overhead.
+
{{% /alert %}}
[grafana]: http://grafana.org/
diff --git a/content/en/docs/v3.5/op-guide/supported-platform.md b/content/en/docs/v3.5/op-guide/supported-platform.md
index ff4107f2d..982e4d592 100644
--- a/content/en/docs/v3.5/op-guide/supported-platform.md
+++ b/content/en/docs/v3.5/op-guide/supported-platform.md
@@ -56,12 +56,14 @@ prints a warning message and exits immediately unless the environment variable
`ETCD_UNSUPPORTED_ARCH` is set to the target architecture.
{{% alert title="32-bit systems" color="warning" %}}
+
etcd has **known issues** on 32-bit systems due to a bug in the Go runtime.
For more information see the [Go issue #599][go-issue] and the [atomic package
bug note][go-atomic].
[go-atomic]: https://golang.org/pkg/sync/atomic/#pkg-note-BUG
[go-issue]: https://github.com/golang/go/issues/599
+
{{% /alert %}}
[etcd maintainers]: https://github.com/etcd-io/etcd/blob/main/OWNERS
diff --git a/content/en/docs/v3.6/benchmarks/etcd-3-watch-memory-benchmark.md b/content/en/docs/v3.6/benchmarks/etcd-3-watch-memory-benchmark.md
index ab73f0f1c..ba7401a6b 100644
--- a/content/en/docs/v3.6/benchmarks/etcd-3-watch-memory-benchmark.md
+++ b/content/en/docs/v3.6/benchmarks/etcd-3-watch-memory-benchmark.md
@@ -5,7 +5,9 @@ description: Performance measures for etcd watchers
---
{{% alert title="Note" color="info" %}}
+
The watch features are under active development, and their memory usage may change as that development progresses. We do not expect it to significantly increase beyond the figures stated below.
+
{{% /alert %}}
A primary goal of etcd is supporting a very large number of watchers doing a massively large amount of watching. etcd aims to support O(10k) clients, O(100K) watch streams (O(10) streams per client) and O(10M) total watchings (O(100) watching per stream). The memory consumed by each individual watching accounts for the largest portion of etcd's overall usage, and is therefore the focus of current and future optimizations.
diff --git a/content/en/docs/v3.6/downgrades/downgrade_3_5.md b/content/en/docs/v3.6/downgrades/downgrade_3_5.md
index 7dceb6485..4a16f4549 100644
--- a/content/en/docs/v3.6/downgrades/downgrade_3_5.md
+++ b/content/en/docs/v3.6/downgrades/downgrade_3_5.md
@@ -16,7 +16,9 @@ Before [starting a downgrade](#downgrade-procedure), read through the rest of th
content/en/docs/v3.5/op-guide/authentication/rbac.md
{{% alert title="Note" color="info" %}}
+
If your cluster enables auth, rolling downgrade from 3.5 isn't supported because 3.5 [changes a format of WAL entries related to auth](https://github.com/etcd-io/etcd/pull/11943). You can follow the [authentification instructions](../../op-guide/authentication/rbac/) to disable auth, and delete all users first.
+
{{% /alert %}}
Highlighted breaking changes from 3.5 to 3.4:
@@ -26,7 +28,9 @@ Highlighted breaking changes from 3.5 to 3.4:
If you are using any of the following flags in your 3.5 configurations, make sure to remove, rename, or change the default value when downgrading to 3.4.
{{% alert title="Note" color="info" %}}
+
The diff is based on version 3.5.14 and v.3.4.33. The actual diff would be dependent on your patch version, check with `diff <(etcd-3.5/bin/etcd -h | grep \\-\\-) <(etcd-3.4/bin/etcd -h | grep \\-\\-)` first.
+
{{% /alert %}}
```diff
diff --git a/content/en/docs/v3.6/downgrades/downgrade_3_6.md b/content/en/docs/v3.6/downgrades/downgrade_3_6.md
index f79c97209..e12f87a13 100644
--- a/content/en/docs/v3.6/downgrades/downgrade_3_6.md
+++ b/content/en/docs/v3.6/downgrades/downgrade_3_6.md
@@ -20,7 +20,9 @@ Highlighted breaking changes from v3.6 to v3.5:
If you are using any of the following flags in your v3.6 configurations, make sure to remove, rename, or change the default value when downgrading to v3.5.
{{% alert title="Note" color="info" %}}
+
The diff is based on version v3.6.0 and v.3.5.18. The actual diff would be dependent on your patch version, check with `diff <(etcd-3.6/bin/etcd -h | grep \\-\\-) <(etcd-3.5/bin/etcd -h | grep \\-\\-)` first.
+
{{% /alert %}}
```diff
@@ -223,7 +225,9 @@ COMMENT
```
{{% alert title="Note" color="info" %}}
+
Once downgrade is enabled, the cluster will remain operating with v3.5 protocol even if all the servers are still running the v3.6 binary, unless the downgrade is canceled with `etcdctl downgrade cancel`
+
{{% /alert %}}
#### Step 5: stop one existing etcd server
@@ -309,7 +313,9 @@ COMMENT
```
{{% alert title="Note" color="info" %}}
+
You will see the `DOWNGRADE ENABLED` is false for the v3.5 server, because the downgrade info is not implemented in v3.5 status endpoint, downgrade is still enabled for the cluster at this point.
+
{{% /alert %}}
#### Step 7: repeat *step 5* and *step 6* for rest of the members
diff --git a/content/en/docs/v3.6/feature-gates/index.md b/content/en/docs/v3.6/feature-gates/index.md
index 102615442..3c86a77df 100644
--- a/content/en/docs/v3.6/feature-gates/index.md
+++ b/content/en/docs/v3.6/feature-gates/index.md
@@ -103,8 +103,10 @@ A *Beta* feature means:
discovering new hard-to-spot bugs through wider adoption.
{{% alert title="Note" color="info" %}}
+
Please do try *Beta* features and give feedback on them!
After they exit beta, it may not be practical for us to make more changes.
+
{{% /alert %}}
A *General Availability* (GA) feature is also referred to as a *stable* feature. It means:
diff --git a/content/en/docs/v3.6/install.md b/content/en/docs/v3.6/install.md
index 5699a0da0..365f97478 100644
--- a/content/en/docs/v3.6/install.md
+++ b/content/en/docs/v3.6/install.md
@@ -72,7 +72,9 @@ source by following these steps:
## Installation via OS packages
{{% alert title="Warning" color="warning" %}}
+
etcd installations through OS package managers can deliver outdated versions since they are not being automatically maintained nor officially supported by etcd project. Therefore use OS packages with caution.*
+
{{% /alert %}}
There are various ways of installing etcd on different operating systems and these are just some examples how it can be done.
@@ -97,7 +99,9 @@ $ etcd --version
## Linux
{{% alert title="Warning" color="warning" %}}
+
Although installing etcd through many major Linux distributions' official repositories and package managers is possible, the published versions can be significantly outdated. So, installing this way is strongly discouraged.
+
{{% /alert %}}
The recommended way to install etcd on Linux is either through [pre-built binaries](#install-pre-built-binaries) or by using Homebrew.
diff --git a/content/en/docs/v3.6/metrics/_index.md b/content/en/docs/v3.6/metrics/_index.md
index 60319ad65..189ddce65 100644
--- a/content/en/docs/v3.6/metrics/_index.md
+++ b/content/en/docs/v3.6/metrics/_index.md
@@ -111,7 +111,9 @@ The Prometheus client library provides a number of metrics under the `go` and `p
| process_max_fds | Maximum number of open file descriptors. | Gauge |
{{% alert title="Note" color="info" %}}
+
The process metrics, such as `process_open_fds` and `process_max_fds`, are not supported on Darwin (macOS) systems at this time.
+
{{% /alert %}}
Heavy file descriptor (`process_open_fds`) usage (i.e., near the process's file descriptor limit, `process_max_fds`) indicates a potential file descriptor exhaustion issue. If the file descriptors are exhausted, etcd may panic because it cannot create new WAL files.
diff --git a/content/en/docs/v3.6/op-guide/clustering.md b/content/en/docs/v3.6/op-guide/clustering.md
index 438681a19..1970c6be3 100644
--- a/content/en/docs/v3.6/op-guide/clustering.md
+++ b/content/en/docs/v3.6/op-guide/clustering.md
@@ -239,7 +239,9 @@ By setting the size key to the URL, a discovery URL is created with an expected
The URL to use in this case will be `https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83` and the etcd members will use the `https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83` directory for registration as they start.
{{% alert title="Important" %}}
+
Each member must have a different name flag specified. `Hostname` or `machine-id` can be a good choice. Or discovery will fail due to duplicated name.
+
{{% /alert %}}
Now we start etcd with those relevant flags for each member:
@@ -288,7 +290,9 @@ ETCD_DISCOVERY=https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573d
```
{{% alert title="Important" %}}
+
Each member must have a different name flag specified or else discovery will fail due to duplicated names. `Hostname` or `machine-id` can be a good choice.
+
{{% /alert %}}
Now we start etcd with those relevant flags for each member:
diff --git a/content/en/docs/v3.6/op-guide/configuration.md b/content/en/docs/v3.6/op-guide/configuration.md
index b2f1b5416..bc788358c 100644
--- a/content/en/docs/v3.6/op-guide/configuration.md
+++ b/content/en/docs/v3.6/op-guide/configuration.md
@@ -13,11 +13,13 @@ You can configure etcd through the following:
- **[Configuration file](#configuration-file)**
{{% alert color="warning" %}}
+
**Caution**: If you mix-and-match configuration options, then the following
rules apply.
- Command-line flags take precedence over environment variables.
- If you provide a _configuration file_ all command-line flags and environment variables are **ignored**.
+
{{% /alert %}}
## Command-line flags
@@ -27,10 +29,12 @@ Flags are presented below using the format `--flag-name DEFAULT_VALUE`.
The list of flags provided below may not be up-to-date due to ongoing development changes. For the latest available flags, run `etcd --help` or refer to the [etcd help][].
{{% alert color="info" %}}
+
**Note**: For details concerning new, updated, and deprecated {{< param version >}} flags,
see [CHANGELOG-{{< psubstr version 1 >}}.md][changelog].
[changelog]: https://github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-{{< psubstr version 1 >}}.md
+
{{% /alert %}}
### Member
@@ -219,7 +223,9 @@ The list of flags provided below may not be up-to-date due to ongoing developmen
```
{{% alert color="info" %}}
+
**Note**: Several `--experimental-*` flags have been deprecated in v3.6 and are planned to be removed in v3.7. Be sure to refer to their `--feature-gates=*` replacements when upgrading.
+
{{% /alert %}}
### Experimental distributed tracing
@@ -240,7 +246,9 @@ The list of flags provided below may not be up-to-date due to ongoing developmen
### v2 Proxy
{{% alert color="warning" %}}
+
** Note**: flags will be deprecated in v3.6.
+
{{% /alert %}}
```nocode
@@ -288,7 +296,9 @@ The list of flags provided below may not be up-to-date due to ongoing developmen
### Unsafe features
{{% alert color="warning" %}}
+
** Warning**: using unsafe features may break the guarantees given by the consensus protocol!
+
{{% /alert %}}
```nocode
diff --git a/content/en/docs/v3.6/op-guide/maintenance.md b/content/en/docs/v3.6/op-guide/maintenance.md
index ee7b4c19d..38e54db5d 100644
--- a/content/en/docs/v3.6/op-guide/maintenance.md
+++ b/content/en/docs/v3.6/op-guide/maintenance.md
@@ -86,11 +86,15 @@ Finished defragmenting etcd member[127.0.0.1:2379]
```
{{% alert title="Note" color="info" %}}
+
Defragmentation to a live member blocks the system from reading and writing data while rebuilding its states.
+
{{% /alert %}}
{{% alert title="Note" color="info" %}}
+
Defragmentation request does not get replicated over cluster. That is, the request is only applied to the local node. Specify all members in `--endpoints` flag or `--cluster` flag to automatically find all cluster members.
+
{{% /alert %}}
Run defragment operations for all endpoints in the cluster associated with the default endpoint:
@@ -162,7 +166,9 @@ The metric `etcd_mvcc_db_total_size_in_use_in_bytes` indicates the actual databa
`etcd_debugging_mvcc_db_total_size_in_bytes` is renamed to `etcd_mvcc_db_total_size_in_bytes` from v3.4.
{{% alert title="Note" color="info" %}}
+
It is possible to get an `ErrGRPCNoSpace` error for a Put/Txn/LeaseGrant request, and still have the write request succeed in the backend, because etcd checks space quota at the API layer and the internal Apply layer, and the Apply layer will only raise the `NOSPACE` alarm without blocking the transaction from proceeding.
+
{{% /alert %}}
## Snapshot backup
diff --git a/content/en/docs/v3.6/op-guide/monitoring.md b/content/en/docs/v3.6/op-guide/monitoring.md
index cde0f24d9..0d33e1f45 100644
--- a/content/en/docs/v3.6/op-guide/monitoring.md
+++ b/content/en/docs/v3.6/op-guide/monitoring.md
@@ -139,7 +139,9 @@ Now Prometheus will scrape etcd metrics every 10 seconds.
There is a set of [default alerts](https://github.com/etcd-io/etcd/tree/main/contrib/mixin) for etcd v3 clusters for Prometheus.
{{% alert title="Note" color="info" %}}
+
Note that `job` labels may need to be adjusted to fit a particular need. The rules were written to apply to a single cluster so it is recommended to choose labels unique to a cluster.
+
{{% /alert %}}
### Grafana
@@ -164,7 +166,9 @@ Sample dashboard:
In v3.5 etcd has added support for distributed tracing using [OpenTelemetry](https://github.com/open-telemetry).
{{% alert title="Note" color="info" %}}
+
This feature is still experimental and can change at any time.
+
{{% /alert %}}
To enable this experimental feature, pass the `--experimental-enable-distributed-tracing=true` to the etcd server, along with the `--experimental-distributed-tracing-sampling-rate=` flag to choose how many samples to collect per million spans, the default sampling rate is `0`.
@@ -180,7 +184,9 @@ Configure the distributed tracing by starting etcd server with the following opt
Before enabling the distributed tracing, make sure to have the OpenTelemetry endpoint, if that address differs to the default one, override with the `--experimental-distributed-tracing-address` flag. Due to OpenTelemetry having different ways of running, refer to the [collector documentation](https://opentelemetry.io/docs/collector/getting-started/) to learn more.
{{% alert title="Note" color="info" %}}
+
There is a resource overhead, as with any observability signal, according to our initial measurements that overhead could be between 2% - 4% CPU overhead.
+
{{% /alert %}}
[grafana]: http://grafana.org/
diff --git a/content/en/docs/v3.6/op-guide/security.md b/content/en/docs/v3.6/op-guide/security.md
index 2fab58050..ce361c17c 100644
--- a/content/en/docs/v3.6/op-guide/security.md
+++ b/content/en/docs/v3.6/op-guide/security.md
@@ -7,7 +7,9 @@ description: Securing data in transit
etcd supports automatic TLS as well as authentication through client certificates for both clients to server as well as peer (server to server / cluster) communication.
{{% alert title="Warning" color="warning" %}}
+
etcd doesn't enable [RBAC based authentication](../authentication) or the authentication feature in the transport layer by default to reduce friction for users getting started with the database. Further, changing this default would be a breaking change for the project which was established since 2013. An etcd cluster which doesn't enable security features can expose its data to any clients.
+
{{% /alert %}}
To get up and running, first have a CA certificate and a signed key pair for one member. It is recommended to create and sign a new key pair for every member in a cluster.
@@ -207,7 +209,9 @@ The etcd members will form a cluster and all communication between members in th
## Example 4: Automatic self-signed transport security
{{% alert title="Note" color="info" %}}
+
When you specify ClientAutoTLS and PeerAutoTLS, the validity period of the client certificate and peer certificate automatically generated by etcd is only 1 year. You can specify the --self-signed-cert-validity flag to set the validity period of the certificate in years.
+
{{% /alert %}}
For cases where communication encryption, but not authentication, is needed, etcd supports encrypting its messages with automatically generated self-signed certificates. This simplifies deployment because there is no need for managing certificates and keys outside of etcd.
@@ -246,10 +250,14 @@ $ curl -k https://127.0.0.1:2379/v2/keys/foo -Xput -d value=bar -v
Previously, we described that etcd supports two types of communication: **client-to-server** and **server-to-server (peer communication)**. In this section, we will prepare configuration steps to migrate both communication types to TLS in your existing etcd cluster.
{{% alert title="Important"%}}
+
Before starting work on converting the cluster to TLS, please make a backup of the etcd database.
+
{{% /alert %}}
{{% alert title="Important"%}}
+
Before restarting any etcd members, you must first add the TLS certificates and configuration to each etcd node.
+
{{% /alert %}}
---
diff --git a/content/en/docs/v3.6/op-guide/supported-platform.md b/content/en/docs/v3.6/op-guide/supported-platform.md
index 8a6e24541..706009398 100644
--- a/content/en/docs/v3.6/op-guide/supported-platform.md
+++ b/content/en/docs/v3.6/op-guide/supported-platform.md
@@ -56,12 +56,14 @@ prints a warning message and exits immediately unless the environment variable
`ETCD_UNSUPPORTED_ARCH` is set to the target architecture.
{{% alert title="32-bit systems" color="warning" %}}
+
etcd has **known issues** on 32-bit systems due to a bug in the Go runtime.
For more information see the [Go issue #599][go-issue] and the [atomic package
bug note][go-atomic].
[go-atomic]: https://golang.org/pkg/sync/atomic/#pkg-note-BUG
[go-issue]: https://github.com/golang/go/issues/599
+
{{% /alert %}}
[etcd maintainers]: https://github.com/etcd-io/etcd/blob/main/OWNERS
diff --git a/content/en/docs/v3.6/upgrades/upgrade_3_0.md b/content/en/docs/v3.6/upgrades/upgrade_3_0.md
index 96ddc5bcf..2c9083f96 100644
--- a/content/en/docs/v3.6/upgrades/upgrade_3_0.md
+++ b/content/en/docs/v3.6/upgrades/upgrade_3_0.md
@@ -13,7 +13,9 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
### Upgrade checklists
{{% alert title="Note" color="info" %}}
+
When [migrating from v2 with no v3 data](https://github.com/etcd-io/etcd/issues/9480), etcd server v3.2+ panics when etcd restores from existing snapshots but no v3 `ETCD_DATA_DIR/member/snap/db` file. This happens when the server had migrated from v2 with no previous v3 data. This also prevents accidental v3 data loss (e.g. `db` file might have been moved). etcd requires that post v3 migration can only happen with v3 data. Do not upgrade to newer v3 versions until v3.0 server contains v3 data.
+
{{% /alert %}}
#### Upgrade requirements
diff --git a/content/en/docs/v3.6/upgrades/upgrade_3_1.md b/content/en/docs/v3.6/upgrades/upgrade_3_1.md
index 4adbc7a64..124f2afe4 100644
--- a/content/en/docs/v3.6/upgrades/upgrade_3_1.md
+++ b/content/en/docs/v3.6/upgrades/upgrade_3_1.md
@@ -13,7 +13,9 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
### Upgrade checklists
{{% alert title="Note" color="info" %}}
+
When [migrating from v2 with no v3 data](https://github.com/etcd-io/etcd/issues/9480), etcd server v3.2+ panics when etcd restores from existing snapshots but no v3 `ETCD_DATA_DIR/member/snap/db` file. This happens when the server had migrated from v2 with no previous v3 data. This also prevents accidental v3 data loss (e.g. `db` file might have been moved). etcd requires that post v3 migration can only happen with v3 data. Do not upgrade to newer v3 versions until v3.0 server contains v3 data.
+
{{% /alert %}}
#### Monitoring
diff --git a/content/en/docs/v3.6/upgrades/upgrade_3_2.md b/content/en/docs/v3.6/upgrades/upgrade_3_2.md
index acca4b566..002c17799 100644
--- a/content/en/docs/v3.6/upgrades/upgrade_3_2.md
+++ b/content/en/docs/v3.6/upgrades/upgrade_3_2.md
@@ -13,7 +13,9 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
### Upgrade checklists
{{% alert title="Note" color="info" %}}
+
When [migrating from v2 with no v3 data](https://github.com/etcd-io/etcd/issues/9480), etcd server v3.2+ panics when etcd restores from existing snapshots but no v3 `ETCD_DATA_DIR/member/snap/db` file. This happens when the server had migrated from v2 with no previous v3 data. This also prevents accidental v3 data loss (e.g. `db` file might have been moved). etcd requires that post v3 migration can only happen with v3 data. Do not upgrade to newer v3 versions until v3.0 server contains v3 data.
+
{{% /alert %}}
Highlighted breaking changes in 3.2.
diff --git a/content/en/docs/v3.6/upgrades/upgrade_3_3.md b/content/en/docs/v3.6/upgrades/upgrade_3_3.md
index 44310f287..765cf4d4b 100644
--- a/content/en/docs/v3.6/upgrades/upgrade_3_3.md
+++ b/content/en/docs/v3.6/upgrades/upgrade_3_3.md
@@ -13,11 +13,15 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
### Upgrade checklists
{{% alert title="Note" color="info" %}}
+
When [migrating from v2 with no v3 data](https://github.com/etcd-io/etcd/issues/9480), etcd server v3.2+ panics when etcd restores from existing snapshots but no v3 `ETCD_DATA_DIR/member/snap/db` file. This happens when the server had migrated from v2 with no previous v3 data. This also prevents accidental v3 data loss (e.g. `db` file might have been moved). etcd requires that post v3 migration can only happen with v3 data. Do not upgrade to newer v3 versions until v3.0 server contains v3 data.
+
{{% /alert %}}
{{% alert title="Note" color="info" %}}
+
if you enable auth and use lease(lease ttl is small), it has a high probability to encounter [issue](https://github.com/etcd-io/etcd/issues/11689) that will result in data inconsistency. It is strongly recommended upgrading to 3.2.31+ firstly to fix this problem, and then upgrade to 3.3. In addition, if the user without permission sends a `LeaseRevoke` request to the 3.3 node during the upgrade process, it may still cause data corruption, so it is best to ensure that your environment doesn't exist such abnormal calls before upgrading, see [#11691](https://github.com/etcd-io/etcd/pull/11691) for detail.
+
{{% /alert %}}
@@ -92,7 +96,9 @@ WARNING: 2017/11/02 11:35:51 grpc: addrConn.resetTransport failed to create clie
From v3.3, gRPC server logs are disabled by default.
{{% alert title="Note" color="info" %}}
+
`embed.Config.SetupLogging` method has been deprecated in v3.4. Please see [v3.4 upgrade guide](/docs/{{< param version >}}/upgrades/upgrade_3_4/) for more details.**
+
{{% /alert %}}
```go
diff --git a/content/en/docs/v3.6/upgrades/upgrade_3_4.md b/content/en/docs/v3.6/upgrades/upgrade_3_4.md
index ffa2dc68c..de2f18a6d 100644
--- a/content/en/docs/v3.6/upgrades/upgrade_3_4.md
+++ b/content/en/docs/v3.6/upgrades/upgrade_3_4.md
@@ -15,7 +15,9 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
### Upgrade checklists
{{% alert title="Note" color="info" %}}
+
When [migrating from v2 with no v3 data](https://github.com/etcd-io/etcd/issues/9480), etcd server v3.2+ panics when etcd restores from existing snapshots but no v3 `ETCD_DATA_DIR/member/snap/db` file. This happens when the server had migrated from v2 with no previous v3 data. This also prevents accidental v3 data loss (e.g. `db` file might have been moved). etcd requires that post v3 migration can only happen with v3 data. Do not upgrade to newer v3 versions until v3.0 server contains v3 data.
+
{{% /alert %}}
Highlighted breaking changes in 3.4.
diff --git a/content/en/docs/v3.6/upgrades/upgrade_3_5.md b/content/en/docs/v3.6/upgrades/upgrade_3_5.md
index da1894fad..3ce09b7fc 100644
--- a/content/en/docs/v3.6/upgrades/upgrade_3_5.md
+++ b/content/en/docs/v3.6/upgrades/upgrade_3_5.md
@@ -15,11 +15,15 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
### Upgrade checklists
{{% alert title="Note" color="info" %}}
+
When [migrating from v2 with no v3 data](https://github.com/etcd-io/etcd/issues/9480), etcd server v3.2+ panics when etcd restores from existing snapshots but no v3 `ETCD_DATA_DIR/member/snap/db` file. This happens when the server had migrated from v2 with no previous v3 data. This also prevents accidental v3 data loss (e.g. `db` file might have been moved). etcd requires that post v3 migration can only happen with v3 data. Do not upgrade to newer v3 versions until v3.0 server contains v3 data.
+
{{% /alert %}}
{{% alert title="Note" color="info" %}}
+
If your cluster enables auth, rolling upgrade from 3.4 or older version isn't supported because 3.5 [changes a format of WAL entries related to auth](https://github.com/etcd-io/etcd/pull/11943).
+
{{% /alert %}}
Highlighted breaking changes in 3.5.
diff --git a/content/en/docs/v3.6/upgrades/upgrade_3_6.md b/content/en/docs/v3.6/upgrades/upgrade_3_6.md
index d7bdf263f..35503de51 100644
--- a/content/en/docs/v3.6/upgrades/upgrade_3_6.md
+++ b/content/en/docs/v3.6/upgrades/upgrade_3_6.md
@@ -16,7 +16,9 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
#### Update 3.5
{{% alert title="Important" color="warning" %}}
+
Before upgrading to 3.6, make sure that [all of your 3.5 members are updated to 3.5.26 or later](https://etcd.io/blog/2025/zombie_members_upgrade). Patch releases 3.5.24 through 3.5.26 fix several potential upgrade blockers.
+
{{% /alert %}}
#### V2 Store
diff --git a/content/en/docs/v3.7/op-guide/configuration.md b/content/en/docs/v3.7/op-guide/configuration.md
index b03fa3f72..bf320f05e 100644
--- a/content/en/docs/v3.7/op-guide/configuration.md
+++ b/content/en/docs/v3.7/op-guide/configuration.md
@@ -13,11 +13,13 @@ You can configure etcd through the following:
- **[Configuration file](#configuration-file)**
{{% alert color="warning" %}}
+
**Caution**: If you mix-and-match configuration options, then the following
rules apply.
- Command-line flags take precedence over environment variables.
- If you provide a _configuration file_ all command-line flags and environment variables are **ignored**.
+
{{% /alert %}}
## Command-line flags
@@ -27,10 +29,12 @@ Flags are presented below using the format `--flag-name DEFAULT_VALUE`.
The list of flags provided below may not be up-to-date due to ongoing development changes. For the latest available flags, run `etcd --help` or refer to the [etcd help][].
{{% alert color="info" %}}
+
**Note**: For details concerning new, updated, and deprecated {{< param version >}} flags,
see [CHANGELOG-{{< psubstr version 1 >}}.md][changelog].
[changelog]: https://github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-{{< psubstr version 1 >}}.md
+
{{% /alert %}}
### Member
@@ -223,8 +227,10 @@ The list of flags provided below may not be up-to-date due to ongoing developmen
```
{{% alert color="info" %}}
+
**Note**: Several `--experimental-*` flags have been promoted or renamed in v3.7.
Be sure to replace deprecated flags with their stable counterparts listed below.
+
{{% /alert %}}
### Distributed tracing
@@ -245,7 +251,9 @@ Be sure to replace deprecated flags with their stable counterparts listed below.
### v2 Proxy
{{% alert color="warning" %}}
+
** Note**: flags will be deprecated in v3.6.
+
{{% /alert %}}
```nocode
@@ -322,7 +330,9 @@ Be sure to replace deprecated flags with their stable counterparts listed below.
### Unsafe features
{{% alert color="warning" %}}
+
** Warning**: using unsafe features may break the guarantees given by the consensus protocol!
+
{{% /alert %}}
```nocode
diff --git a/content/en/docs/v3.7/op-guide/monitoring.md b/content/en/docs/v3.7/op-guide/monitoring.md
index cde0f24d9..0d33e1f45 100644
--- a/content/en/docs/v3.7/op-guide/monitoring.md
+++ b/content/en/docs/v3.7/op-guide/monitoring.md
@@ -139,7 +139,9 @@ Now Prometheus will scrape etcd metrics every 10 seconds.
There is a set of [default alerts](https://github.com/etcd-io/etcd/tree/main/contrib/mixin) for etcd v3 clusters for Prometheus.
{{% alert title="Note" color="info" %}}
+
Note that `job` labels may need to be adjusted to fit a particular need. The rules were written to apply to a single cluster so it is recommended to choose labels unique to a cluster.
+
{{% /alert %}}
### Grafana
@@ -164,7 +166,9 @@ Sample dashboard:
In v3.5 etcd has added support for distributed tracing using [OpenTelemetry](https://github.com/open-telemetry).
{{% alert title="Note" color="info" %}}
+
This feature is still experimental and can change at any time.
+
{{% /alert %}}
To enable this experimental feature, pass the `--experimental-enable-distributed-tracing=true` to the etcd server, along with the `--experimental-distributed-tracing-sampling-rate=` flag to choose how many samples to collect per million spans, the default sampling rate is `0`.
@@ -180,7 +184,9 @@ Configure the distributed tracing by starting etcd server with the following opt
Before enabling the distributed tracing, make sure to have the OpenTelemetry endpoint, if that address differs to the default one, override with the `--experimental-distributed-tracing-address` flag. Due to OpenTelemetry having different ways of running, refer to the [collector documentation](https://opentelemetry.io/docs/collector/getting-started/) to learn more.
{{% alert title="Note" color="info" %}}
+
There is a resource overhead, as with any observability signal, according to our initial measurements that overhead could be between 2% - 4% CPU overhead.
+
{{% /alert %}}
[grafana]: http://grafana.org/
diff --git a/content/en/docs/v3.7/op-guide/supported-platform.md b/content/en/docs/v3.7/op-guide/supported-platform.md
index 8a6e24541..706009398 100644
--- a/content/en/docs/v3.7/op-guide/supported-platform.md
+++ b/content/en/docs/v3.7/op-guide/supported-platform.md
@@ -56,12 +56,14 @@ prints a warning message and exits immediately unless the environment variable
`ETCD_UNSUPPORTED_ARCH` is set to the target architecture.
{{% alert title="32-bit systems" color="warning" %}}
+
etcd has **known issues** on 32-bit systems due to a bug in the Go runtime.
For more information see the [Go issue #599][go-issue] and the [atomic package
bug note][go-atomic].
[go-atomic]: https://golang.org/pkg/sync/atomic/#pkg-note-BUG
[go-issue]: https://github.com/golang/go/issues/599
+
{{% /alert %}}
[etcd maintainers]: https://github.com/etcd-io/etcd/blob/main/OWNERS
diff --git a/content/en/docs/v3.7/upgrades/upgrade_3_6.md b/content/en/docs/v3.7/upgrades/upgrade_3_6.md
index 590c925f2..d1c1ba4d8 100644
--- a/content/en/docs/v3.7/upgrades/upgrade_3_6.md
+++ b/content/en/docs/v3.7/upgrades/upgrade_3_6.md
@@ -16,7 +16,9 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
#### Update 3.5
{{% alert title="Important" color="warning" %}}
+
Before upgrading to 3.6, make sure that [all of your 3.5 members are updated to 3.5.26 or later](https://etcd.io/blog/2025/zombie_members_upgrade). Patch releases 3.5.24 through 3.5.26 fix several potential upgrade blockers.
+
{{% /alert %}}
#### V2 Store