From f41114cdd3a5e1b84e5b5036c78b64ab3e8f0d75 Mon Sep 17 00:00:00 2001 From: Gang Li Date: Mon, 6 Jan 2025 16:00:06 -0800 Subject: [PATCH 01/10] Add Feature gates docs for etcd Signed-off-by: Gang Li --- content/en/docs/v3.6/feature-gates/index.md | 94 +++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 content/en/docs/v3.6/feature-gates/index.md diff --git a/content/en/docs/v3.6/feature-gates/index.md b/content/en/docs/v3.6/feature-gates/index.md new file mode 100644 index 00000000..b3544d40 --- /dev/null +++ b/content/en/docs/v3.6/feature-gates/index.md @@ -0,0 +1,94 @@ +--- +title: Feature Gates +weight: 10 +content_type: concept +card: + name: reference + weight: 60 +--- + + +This page contains an overview of the various feature gates an administrator +can specify on ETCD. + +See [feature stages](#feature-stages) for an explanation of the stages for a feature. + + + +## Overview + +Feature gates are a set of key=value pairs that describe ETCD features. +You can turn these features on or off using the `--feature-gates` command line flag +on ETCD. + +ETCD lets you enable or disable a set of feature gates that +are relevant to that component. +Use `-h` flag to see a full set of feature gates for all components. +To set feature gates for a component, such as kubelet, use the `--feature-gates` +flag assigned to a list of feature pairs: + +```shell +--feature-gates=...,DistributedTracing=true +``` + +The following tables are a summary of the feature gates that you can set on +ETCD. + +### Feature gates for Alpha or Beta features + +| Feature | Default | Stage | +|----------------------------------|---------|-------| +| DistributedTracing | false | Alpha | +| StopGRPCServiceOnDefrag | false | Alpha | +| InitialCorruptCheck | false | Alpha | +| CompactHashCheck | false | Alpha | +| TxnModeWriteWithSharedBuffer | true | Beta | + +## Using a feature + +### Feature stages + +A feature can be in *Alpha*, *Beta* or *GA* stage. +An *Alpha* feature means: + +* Disabled by default. +* Might be buggy. Enabling the feature may expose bugs. +* Support for feature may be dropped at any time without notice. +* The API may change in incompatible ways in a later software release without notice. +* Recommended for use only in short-lived testing clusters, due to increased + risk of bugs and lack of long-term support. + +A *Beta* feature means: + +* Usually enabled by default. +* The feature is well tested. Enabling the feature is considered safe. +* Support for the overall feature will not be dropped, though details may change. +* The schema and/or semantics of objects may change in incompatible ways in a + subsequent beta or stable release. When this happens, we will provide instructions + for migrating to the next version. This may require deleting, editing, and + re-creating API objects. The editing process may require some thought. + This may require downtime for applications that rely on the feature. +* Recommended for only non-business-critical uses because of potential for + incompatible changes in subsequent releases. If you have multiple clusters + that can be upgraded independently, you may be able to relax this restriction. + +{{< note >}} +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. +{{< /note >}} + +A *General Availability* (GA) feature is also referred to as a *stable* feature. It means: + +* The feature is always enabled; you cannot disable it. +* The corresponding feature gate is no longer needed. +* Stable versions of features will appear in released software for many subsequent versions. + +## List of feature gates {#feature-gates} + +Each feature gate is designed for enabling/disabling a specific feature. + +* `DistributedTracing`: Enable experimental distributed tracing using OpenTelemetry Tracing. +* `StopGRPCServiceOnDefrag`: Enable etcd gRPC service to stop serving client requests on defragmentation. +* `TxnModeWriteWithSharedBuffer`: Enables the write transaction to use a shared buffer in its readonly check operations. +* `InitialCorruptCheck`: Enable to check data corruption before serving any client/peer traffic. +* `CompactHashCheck`: Enable leader to periodically check followers compaction hashes. From c6b9b2b31ba208ad2776bb8c5229513937d727f8 Mon Sep 17 00:00:00 2001 From: Gang Li Date: Mon, 6 Jan 2025 16:37:55 -0800 Subject: [PATCH 02/10] fix text Signed-off-by: Gang Li --- content/en/docs/v3.6/feature-gates/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/en/docs/v3.6/feature-gates/index.md b/content/en/docs/v3.6/feature-gates/index.md index b3544d40..6c38f6d3 100644 --- a/content/en/docs/v3.6/feature-gates/index.md +++ b/content/en/docs/v3.6/feature-gates/index.md @@ -24,8 +24,7 @@ on ETCD. ETCD lets you enable or disable a set of feature gates that are relevant to that component. Use `-h` flag to see a full set of feature gates for all components. -To set feature gates for a component, such as kubelet, use the `--feature-gates` -flag assigned to a list of feature pairs: +To set feature gates, use the `--feature-gates` flag assigned to a list of feature pairs: ```shell --feature-gates=...,DistributedTracing=true From b85aec314ccb5824a8a517171e0baa4d66e189a1 Mon Sep 17 00:00:00 2001 From: Gang Li Date: Tue, 7 Jan 2025 11:00:31 -0800 Subject: [PATCH 03/10] fix shortcode "note" Signed-off-by: Gang Li --- content/en/docs/v3.6/feature-gates/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/en/docs/v3.6/feature-gates/index.md b/content/en/docs/v3.6/feature-gates/index.md index 6c38f6d3..82612a85 100644 --- a/content/en/docs/v3.6/feature-gates/index.md +++ b/content/en/docs/v3.6/feature-gates/index.md @@ -71,10 +71,9 @@ A *Beta* feature means: incompatible changes in subsequent releases. If you have multiple clusters that can be upgraded independently, you may be able to relax this restriction. -{{< note >}} +**Note:** 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. -{{< /note >}} A *General Availability* (GA) feature is also referred to as a *stable* feature. It means: From 055ffd16e42386b9c064f5d51def4bd19e54e9e1 Mon Sep 17 00:00:00 2001 From: Gang Li Date: Tue, 7 Jan 2025 13:50:30 -0800 Subject: [PATCH 04/10] Resolve comments Signed-off-by: Gang Li --- content/en/docs/v3.6/feature-gates/index.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/content/en/docs/v3.6/feature-gates/index.md b/content/en/docs/v3.6/feature-gates/index.md index 82612a85..44f37c27 100644 --- a/content/en/docs/v3.6/feature-gates/index.md +++ b/content/en/docs/v3.6/feature-gates/index.md @@ -21,9 +21,8 @@ Feature gates are a set of key=value pairs that describe ETCD features. You can turn these features on or off using the `--feature-gates` command line flag on ETCD. -ETCD lets you enable or disable a set of feature gates that -are relevant to that component. -Use `-h` flag to see a full set of feature gates for all components. +ETCD lets you enable or disable a set of feature gates. +Use `-h` flag to see a full set of feature gates. To set feature gates, use the `--feature-gates` flag assigned to a list of feature pairs: ```shell @@ -59,17 +58,11 @@ An *Alpha* feature means: A *Beta* feature means: -* Usually enabled by default. +* Enabled by default. * The feature is well tested. Enabling the feature is considered safe. * Support for the overall feature will not be dropped, though details may change. -* The schema and/or semantics of objects may change in incompatible ways in a - subsequent beta or stable release. When this happens, we will provide instructions - for migrating to the next version. This may require deleting, editing, and - re-creating API objects. The editing process may require some thought. - This may require downtime for applications that rely on the feature. * Recommended for only non-business-critical uses because of potential for - incompatible changes in subsequent releases. If you have multiple clusters - that can be upgraded independently, you may be able to relax this restriction. + discovering new hard-to-spot bugs through wider adoption. **Note:** Please do try *Beta* features and give feedback on them! @@ -81,6 +74,11 @@ A *General Availability* (GA) feature is also referred to as a *stable* feature. * The corresponding feature gate is no longer needed. * Stable versions of features will appear in released software for many subsequent versions. +A *Deprecated* feature means: + +* The feature gate is no longer in use. +* The feature has graduated to GA or been removed. + ## List of feature gates {#feature-gates} Each feature gate is designed for enabling/disabling a specific feature. From f58a41db833a64f4c72d063d56f2438a19296ebe Mon Sep 17 00:00:00 2001 From: Gang Li Date: Tue, 7 Jan 2025 15:26:50 -0800 Subject: [PATCH 05/10] Remove DistributedTracing from feature gate list Signed-off-by: Gang Li --- content/en/docs/v3.6/feature-gates/index.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/content/en/docs/v3.6/feature-gates/index.md b/content/en/docs/v3.6/feature-gates/index.md index 44f37c27..fed333bd 100644 --- a/content/en/docs/v3.6/feature-gates/index.md +++ b/content/en/docs/v3.6/feature-gates/index.md @@ -26,7 +26,7 @@ Use `-h` flag to see a full set of feature gates. To set feature gates, use the `--feature-gates` flag assigned to a list of feature pairs: ```shell ---feature-gates=...,DistributedTracing=true +--feature-gates=...,StopGRPCServiceOnDefrag=true ``` The following tables are a summary of the feature gates that you can set on @@ -36,7 +36,6 @@ ETCD. | Feature | Default | Stage | |----------------------------------|---------|-------| -| DistributedTracing | false | Alpha | | StopGRPCServiceOnDefrag | false | Alpha | | InitialCorruptCheck | false | Alpha | | CompactHashCheck | false | Alpha | @@ -83,7 +82,6 @@ A *Deprecated* feature means: Each feature gate is designed for enabling/disabling a specific feature. -* `DistributedTracing`: Enable experimental distributed tracing using OpenTelemetry Tracing. * `StopGRPCServiceOnDefrag`: Enable etcd gRPC service to stop serving client requests on defragmentation. * `TxnModeWriteWithSharedBuffer`: Enables the write transaction to use a shared buffer in its readonly check operations. * `InitialCorruptCheck`: Enable to check data corruption before serving any client/peer traffic. From 3cf63e5b1db98660e78efb06c8f968bb86f093f3 Mon Sep 17 00:00:00 2001 From: Gang Li Date: Thu, 9 Jan 2025 10:55:46 -0800 Subject: [PATCH 06/10] use small cap etcd fix markdown lint error Signed-off-by: Gang Li --- content/en/docs/v3.6/feature-gates/index.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/content/en/docs/v3.6/feature-gates/index.md b/content/en/docs/v3.6/feature-gates/index.md index fed333bd..b19abc1f 100644 --- a/content/en/docs/v3.6/feature-gates/index.md +++ b/content/en/docs/v3.6/feature-gates/index.md @@ -9,19 +9,18 @@ card: This page contains an overview of the various feature gates an administrator -can specify on ETCD. +can specify on etcd. See [feature stages](#feature-stages) for an explanation of the stages for a feature. - ## Overview -Feature gates are a set of key=value pairs that describe ETCD features. +Feature gates are a set of key=value pairs that describe etcd features. You can turn these features on or off using the `--feature-gates` command line flag -on ETCD. +on etcd. -ETCD lets you enable or disable a set of feature gates. +Etcd lets you enable or disable a set of feature gates. Use `-h` flag to see a full set of feature gates. To set feature gates, use the `--feature-gates` flag assigned to a list of feature pairs: @@ -30,7 +29,7 @@ To set feature gates, use the `--feature-gates` flag assigned to a list of featu ``` The following tables are a summary of the feature gates that you can set on -ETCD. +etcd. ### Feature gates for Alpha or Beta features From e81bb9f07da0693b9192304ecf7716f62bb0a64f Mon Sep 17 00:00:00 2001 From: Gang Li Date: Fri, 10 Jan 2025 10:23:39 -0800 Subject: [PATCH 07/10] use replace Etcd with etcd Signed-off-by: Gang Li --- content/en/docs/v3.6/feature-gates/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/v3.6/feature-gates/index.md b/content/en/docs/v3.6/feature-gates/index.md index b19abc1f..9a90860f 100644 --- a/content/en/docs/v3.6/feature-gates/index.md +++ b/content/en/docs/v3.6/feature-gates/index.md @@ -20,7 +20,7 @@ Feature gates are a set of key=value pairs that describe etcd features. You can turn these features on or off using the `--feature-gates` command line flag on etcd. -Etcd lets you enable or disable a set of feature gates. +etcd lets you enable or disable a set of feature gates. Use `-h` flag to see a full set of feature gates. To set feature gates, use the `--feature-gates` flag assigned to a list of feature pairs: From b9940bdd0f8e296ccd3eaef5bdd042ca4a56a897 Mon Sep 17 00:00:00 2001 From: Gang Li Date: Wed, 15 Jan 2025 10:59:49 -0800 Subject: [PATCH 08/10] Update content/en/docs/v3.6/feature-gates/index.md Co-authored-by: James Blair Signed-off-by: Gang Li --- content/en/docs/v3.6/feature-gates/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/v3.6/feature-gates/index.md b/content/en/docs/v3.6/feature-gates/index.md index 9a90860f..e3e250f5 100644 --- a/content/en/docs/v3.6/feature-gates/index.md +++ b/content/en/docs/v3.6/feature-gates/index.md @@ -1,6 +1,6 @@ --- title: Feature Gates -weight: 10 +weight: 1175 content_type: concept card: name: reference From 01bcc7cde52b8cbf2d9de0c487648a662e7e846a Mon Sep 17 00:00:00 2001 From: Gang Li Date: Wed, 15 Jan 2025 14:50:00 -0800 Subject: [PATCH 09/10] Add example on how to set feature gates in yaml and move flag details to the table Signed-off-by: Gang Li --- content/en/docs/v3.6/feature-gates/index.md | 29 +++++++++------------ 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/content/en/docs/v3.6/feature-gates/index.md b/content/en/docs/v3.6/feature-gates/index.md index e3e250f5..625255c5 100644 --- a/content/en/docs/v3.6/feature-gates/index.md +++ b/content/en/docs/v3.6/feature-gates/index.md @@ -22,23 +22,29 @@ on etcd. etcd lets you enable or disable a set of feature gates. Use `-h` flag to see a full set of feature gates. -To set feature gates, use the `--feature-gates` flag assigned to a list of feature pairs: +To set feature gates, use the `--feature-gates` flag assigned to a list of feature pairs in commandline: ```shell --feature-gates=...,StopGRPCServiceOnDefrag=true ``` +Or specify them in YAML config file: + +```shell +feature-gates: ...,StopGRPCServiceOnDefrag=true +``` + The following tables are a summary of the feature gates that you can set on etcd. ### Feature gates for Alpha or Beta features -| Feature | Default | Stage | -|----------------------------------|---------|-------| -| StopGRPCServiceOnDefrag | false | Alpha | -| InitialCorruptCheck | false | Alpha | -| CompactHashCheck | false | Alpha | -| TxnModeWriteWithSharedBuffer | true | Beta | +| Feature | Default | Stage | Details | +|----------------------------------|---------|-------|--------------------------------------------------------------------------------------| +| StopGRPCServiceOnDefrag | false | Alpha |Enables etcd gRPC service to stop serving client requests on defragmentation. | +| InitialCorruptCheck | false | Alpha |Enables the write transaction to use a shared buffer in its readonly check operations.| +| CompactHashCheck | false | Alpha |Enables to check data corruption before serving any client/peer traffic. | +| TxnModeWriteWithSharedBuffer | true | Beta |Enables leader to periodically check followers compaction hashes. | ## Using a feature @@ -76,12 +82,3 @@ A *Deprecated* feature means: * The feature gate is no longer in use. * The feature has graduated to GA or been removed. - -## List of feature gates {#feature-gates} - -Each feature gate is designed for enabling/disabling a specific feature. - -* `StopGRPCServiceOnDefrag`: Enable etcd gRPC service to stop serving client requests on defragmentation. -* `TxnModeWriteWithSharedBuffer`: Enables the write transaction to use a shared buffer in its readonly check operations. -* `InitialCorruptCheck`: Enable to check data corruption before serving any client/peer traffic. -* `CompactHashCheck`: Enable leader to periodically check followers compaction hashes. From 067681a4e537dbbc6227b26925476bdb118135c1 Mon Sep 17 00:00:00 2001 From: Gang Li Date: Wed, 15 Jan 2025 14:52:28 -0800 Subject: [PATCH 10/10] fix Signed-off-by: Gang Li --- content/en/docs/v3.6/feature-gates/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/v3.6/feature-gates/index.md b/content/en/docs/v3.6/feature-gates/index.md index 625255c5..5b195c3a 100644 --- a/content/en/docs/v3.6/feature-gates/index.md +++ b/content/en/docs/v3.6/feature-gates/index.md @@ -28,7 +28,7 @@ To set feature gates, use the `--feature-gates` flag assigned to a list of featu --feature-gates=...,StopGRPCServiceOnDefrag=true ``` -Or specify them in YAML config file: +Or specify `feature-gates` in YAML config file: ```shell feature-gates: ...,StopGRPCServiceOnDefrag=true