#22435 docs: Inconsistent/drifting help descriptions in etcd --help output and descriptions in flag code definitions

Bug report criteria

This bug report is not security related, security issues should be disclosed privately via the report form.
This is not a support request or question, support requests or questions should be raised in the etcd discussion forums.
You have read the etcd bug reporting guidelines.
Existing open issues along with etcd frequently asked questions have been checked and this is not a duplicate.

What happened?

There seem to be 2 drifting descriptions for each of the flag descriptions, from etcd --help and server/etcdmain/config.go and server/embed/config.go. I have found around 33 flags where their descriptions have differences between these two places.

P.S. jberkus mentioned that similar descriptions are also in code comments in server/config/config.go https://github.com/etcd-io/etcd/blob/0da1b60a2bb26b47f9680748a2acce1374ed2ea1/server/config/config.go#L167 https://github.com/etcd-io/etcd/blob/0da1b60a2bb26b47f9680748a2acce1374ed2ea1/server/embed/config.go#L387 https://github.com/etcd-io/etcd/blob/0da1b60a2bb26b47f9680748a2acce1374ed2ea1/server/embed/config.go#L724 https://github.com/etcd-io/etcd/blob/0da1b60a2bb26b47f9680748a2acce1374ed2ea1/server/etcdmain/help.go#L258

This seems to be related to https://github.com/etcd-io/etcd/issues/16034 where a system for generating the help text would probably resolve this issue

Examples: config.go

auth-token : Specify auth token specific options. auth-token-ttl : The lifetime in seconds of the auth token. auto-compaction-mode : interpret 'auto-compaction-retention' one of: periodic|revision. 'periodic' for duration ` based retention, defaulting to hours if no time unit is provided (e.g. '5m'). 'revision' for revision number based retention.

help.go

auth-token : Specify a v3 authentication token type and its options ('simple' or 'jwt'). auth-token-ttl : Time (in seconds) of the auth-token-ttl. auto-compaction-mode : Interpret 'auto-compaction-retention' one of: periodic|revision. 'periodic' for duration ` based retention, defaulting to hours if no time unit is provided (e.g. '5m'). 'revision' for revision number based retention.

What did you expect to happen?

There should Ideally be one source of truth for the flag descriptions so that edits to the descriptions do not only happen in only one place or the other or both, which lead to drift, outdated descriptions shown to user, confusion, etc.

How can we reproduce it (as minimally and precisely as possible)?

Look at the flag descriptions in code https://github.com/etcd-io/etcd/blob/0da1b60a2bb26b47f9680748a2acce1374ed2ea1/server/embed/config.go#L729-L732

Look at the flag descriptions in help.go https://github.com/etcd-io/etcd/blob/0da1b60a2bb26b47f9680748a2acce1374ed2ea1/server/etcdmain/help.go#L224-L230

Anything else we need to know?

In the commit history I see PRs with:

Changes made to both descriptions #22248

Changes made to only one description #17202 #19385

In my opinion, this is prone to mistakes in updating the descriptions.

In addition to this, the usage descriptions defined in config.go are never be shown to the user as far as I can tell.

Whenever this is resolved this other issue might be relevant https://github.com/etcd-io/website/issues/1074

List of differences in format flag-name : flag-description: auth-token : Specify a v3 authentication token type and its options ('simple' or 'jwt'). auth-token : Specify auth token specific options.

auth-token-ttl : Time (in seconds) of the auth-token-ttl. auth-token-ttl : The lifetime in seconds of the auth token.

auto-compaction-mode : Interpret 'auto-compaction-retention' one of: periodic|revision. 'periodic' for duration based retention, defaulting to hours if no time unit is provided (e.g. '5m'). 'revision' for revision number based retention. auto-compaction-mode : interpret 'auto-compaction-retention' one of: periodic|revision. 'periodic' for duration based retention, defaulting to hours if no time unit is provided (e.g. '5m'). 'revision' for revision number based retention.

auto-compaction-retention : Auto compaction retention length. 0 means disable auto compaction. auto-compaction-retention : Auto compaction retention for mvcc key value store. 0 means disable auto compaction.

bcrypt-cost : Specify the cost / strength of the bcrypt algorithm for hashing auth passwords. Valid values are between 4 and 31. bcrypt-cost : Specify bcrypt algorithm cost factor for auth password hashing.

client-cert-allowed-hostname : Comma-separated list of SAN hostnames for client cert authentication. client-cert-allowed-hostname : Comma-separated list of allowed SAN hostnames for client cert authentication.

compaction-batch-limit : CompactionBatchLimit sets the maximum revisions deleted in each compaction batch. compaction-batch-limit : Sets the maximum revisions deleted in each compaction batch.

cors : Comma-separated whitelist of origins for CORS, or cross-origin resource sharing, (empty or * means allow all). cors : Comma-separated white list of origins for CORS, or cross-origin resource sharing, (empty or * means allow all)

discovery-fallback : Expected behavior ('exit') when discovery services fails. Note that v2 proxy is removed. discovery-fallback : Valid values include ["exit" "proxy"]

discovery-srv : DNS srv domain used to bootstrap the cluster for v2 discovery. Will be deprecated in v3.7, and be decommissioned in v3.8. discovery-srv : DNS domain used to bootstrap initial cluster.

discovery-srv-name : Suffix to the dns srv name queried when bootstrapping. discovery-srv-name : Service name to query when using DNS discovery.

distributed-tracing-address : Distributed tracing collector address. distributed-tracing-address : Address for distributed tracing used for OpenTelemetry Tracing (if enabled with enable-distributed-tracing flag).

distributed-tracing-instance-id : Distributed tracing instance ID, must be unique per each etcd instance. distributed-tracing-instance-id : Configures service instance ID for distributed tracing to be used to define service instance ID key for OpenTelemetry Tracing (if enabled with enable-distributed-tracing flag). There is no default value set. This ID must be unique per etcd instance.

distributed-tracing-sampling-rate : Number of samples to collect per million spans for distributed tracing. distributed-tracing-sampling-rate : Number of samples to collect per million spans for OpenTelemetry Tracing (if enabled with enable-distributed-tracing flag).

distributed-tracing-service-name : Distributed tracing service name, must be same across all etcd instances. distributed-tracing-service-name : Configures service name for distributed tracing to be used to define service name for OpenTelemetry Tracing (if enabled with enable-distributed-tracing flag). 'etcd' is the default service name. Use the same service name for all instances of etcd.

enable-distributed-tracing : Enable distributed tracing. enable-distributed-tracing : Enable distributed tracing using OpenTelemetry Tracing.

force-new-cluster : Force to create a new one-member cluster. force-new-cluster : Force to create a new one member cluster.

grpc-keepalive-min-time : Minimum duration interval that a client should wait before pinging server. grpc-keepalive-min-time : Minimum interval duration that a client should wait before pinging server.

host-whitelist : Acceptable hostnames from HTTP client requests, if server is not secure (empty or * means allow all). host-whitelist : Comma-separated acceptable hostnames from HTTP client requests, if server is not secure (empty means allow all).

initial-cluster-state : Initial cluster state ('new' when bootstrapping a new cluster or 'existing' when adding new members to an existing cluster). After successful initialization (bootstrapping or adding), flag is ignored on restarts. initial-cluster-state : Initial cluster state ('new' when bootstrapping a new cluster or 'existing' when adding new members to an existing cluster). After successful initialization (bootstrapping or adding), flag is ignored on restarts.

listen-metrics-urls : List of URLs to listen on for the /metrics and /health endpoints. For https, the client URL TLS info is used. listen-metrics-urls : List of URLs to listen on for the metrics and health endpoints.

log-format : Configures log format. Only supports json, console. log-format : Configures log format. Only supports json, console. Default is 'json'.

log-level : Configures log level. Only supports debug, info, warn, error, panic, or fatal. log-level : Configures log level. Only supports debug, info, warn, error, panic, or fatal. Default 'info'.

log-rotation-config-json : Configures log rotation if enabled with a JSON logger config. MaxSize(MB), MaxAge(days,0=no limit), MaxBackups(0=no limit), LocalTime(use computers local time), Compress(gzip)". log-rotation-config-json : Configures log rotation if enabled with a JSON logger config. Default: MaxSize=100(MB), MaxAge=0(days,no limit), MaxBackups=0(no limit), LocalTime=false(UTC), Compress=false(gzip)

max-learners : Set the max number of learner members allowed in the cluster membership. max-learners : Sets the maximum number of learners that can be available in the cluster membership.

peer-auto-tls : Peer TLS using self-generated certificates if --peer-key-file and --peer-cert-file are not provided. peer-auto-tls : Peer TLS using generated certificates

self-signed-cert-validity : The validity period of the client and peer certificates that are automatically generated by etcd when you specify ClientAutoTLS and PeerAutoTLS, the unit is year, and the default is 1. self-signed-cert-validity : The validity period of the client and peer certificates, unit is year

socket-reuse-address : Enable to set socket option SO_REUSEADDR on listeners allowing binding to an address in TIME_WAIT state. socket-reuse-address : Enable to set socket option SO_REUSEADDR on listeners allowing binding to an address in TIME_WAIT state.

tls-max-version : Maximum TLS version supported by etcd. Possible values: TLS1.2, TLS1.3. tls-max-version : Maximum TLS version supported by etcd. Possible values: TLS1.2, TLS1.3 (empty defers to Go).

version : Show the version of etcd. version : Print the version and exit.

warning-apply-duration : Warning is generated if requests take more than this duration. warning-apply-duration : Time duration after which a warning is generated if watch progress takes more time.

warning-unary-request-duration : Set time duration after which a warning is logged if a unary request takes more than this duration. warning-unary-request-duration : Time duration after which a warning is generated if a unary request takes more time.

watch-progress-notify-interval : Duration of periodical watch progress notification. watch-progress-notify-interval : Duration of periodic watch progress notifications.

Etcd version (please run commands below)

$ etcd --version
# paste output here
etcd Version: 3.7.1
Git SHA: 5e7fd0de9
Go Version: go1.26.5
Go OS/Arch: darwin/arm64

$ etcdctl version
# paste output here
N/A

Etcd configuration (command line flags or environment variables)

paste your configuration here

etcd --help

Etcd debug information (please run commands below, feel free to obfuscate the IP address or FQDN in the output)

$ etcdctl member list -w table
# paste output here
N/A

$ etcdctl --endpoints=<member list> endpoint status -w table
# paste output here
N/A

docs: Inconsistent/drifting help descriptions in etcd --help output and descriptions in flag code definitions