Skip to content

Commit 274b120

Browse files
loomtsloomts
authored
feat: improve etcd params (#1778)
1 parent c13fbb2 commit 274b120

4 files changed

Lines changed: 448 additions & 116 deletions

File tree

‎addons/etcd/config/etcd-config-constraint.cue‎

Lines changed: 284 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,103 +1,318 @@
11
// etcd configuration constraint definition
22
#EtcdParameter: {
3-
// ========== IMMUTABLE PARAMETERS ==========
4-
// These parameters are managed by scripts/templates and cannot be modified by users
3+
// ========== MEMBER PARAMETERS ==========
4+
// Basic member configuration
55

6-
// Node identifier (set by start.sh)
6+
// Human-readable name for this member
77
name?: string | *"default"
88

9-
// Network advertising configuration (set by start.sh)
10-
"initial-advertise-peer-urls"?: string
11-
"advertise-client-urls"?: string
9+
// Path to the data directory
10+
"data-dir"?: string | *"/var/run/etcd/default.etcd"
1211

13-
// Data directory path (set by etcd.conf.yaml.tpl)
14-
"data-dir"?: string | *"/var/lib/etcd"
12+
// Path to the dedicated wal directory (empty = use /var/run/etcd/default.etcd/member/wal)
13+
"wal-dir"?: string | *"/var/run/etcd/default.etcd/member/wal"
1514

16-
// Network listening configuration (set by etcd.conf.yaml.tpl)
17-
"listen-peer-urls"?: string | *"http://0.0.0.0:2380"
18-
"listen-client-urls"?: string | *"http://0.0.0.0:2379"
15+
// Time (in milliseconds) of a heartbeat interval.
16+
"heartbeat-interval"?: uint & >=50 & <=5000 | *100
1917

20-
// TLS configuration (set by etcd.conf.yaml.tpl when TLS enabled)
18+
// Time (in milliseconds) for an election to timeout. See tuning documentation for details.
19+
"election-timeout"?: uint & >=500 & <=50000 | *1000
20+
21+
// Whether to fast-forward initial election ticks on boot for faster election.
22+
"initial-election-tick-advance"?: bool | *true
23+
24+
// List of URLs to listen on for peer traffic
25+
"listen-peer-urls"?: string | *"http://localhost:2380"
26+
27+
// List of URLs to listen on for client grpc traffic and http
28+
"listen-client-urls"?: string | *"http://localhost:2379"
29+
30+
// List of URLs to listen on for http only client traffic
31+
"listen-client-http-urls"?: string | *""
32+
33+
// List of this member's peer URLs to advertise to the rest of the cluster
34+
"initial-advertise-peer-urls"?: string | *"http://localhost:2380"
35+
36+
// List of this member's client URLs to advertise to the public
37+
"advertise-client-urls"?: string | *"http://localhost:2379"
38+
39+
// Number of committed transactions to trigger a snapshot to disk.
40+
// NOTE: default changed from 100000 (v3.5) to 10000 (v3.6)
41+
"snapshot-count"?: uint & >=1000 & <=1000000 | *10000
42+
43+
// Maximum number of snapshot files to retain (0 is unlimited).
44+
"max-snapshots"?: uint & >=0 & <=100 | *5
45+
46+
// Maximum number of wal files to retain (0 is unlimited).
47+
"max-wals"?: uint & >=0 & <=100 | *5
48+
49+
// Raise alarms when backend size exceeds the given quota (0 defaults to low space quota).
50+
"quota-backend-bytes"?: uint & >=0 | *0
51+
52+
// BackendFreelistType specifies the type of freelist that boltdb backend uses(array and map are supported types).
53+
"backend-bbolt-freelist-type"?: string & ("map" | "array") | *"map"
54+
55+
// BackendBatchInterval is the maximum time before commit the backend transaction.
56+
"backend-batch-interval"?: string | *""
57+
58+
// BackendBatchLimit is the maximum operations before commit the backend transaction.
59+
"backend-batch-limit"?: uint & >=0 | *0
60+
61+
// Maximum number of operations permitted in a transaction.
62+
"max-txn-ops"?: uint & >=1 & <=10000 | *128
63+
64+
// Maximum client request size in bytes the server will accept.
65+
"max-request-bytes"?: uint & >=1024 & <=33554432 | *1572864
66+
67+
// Minimum duration interval that a client should wait before pinging server
68+
"grpc-keepalive-min-time"?: string | *"5s"
69+
70+
// Frequency duration of server-to-client ping to check if a connection is alive (0 to disable)
71+
"grpc-keepalive-interval"?: string | *"2h"
72+
73+
// Additional duration of wait before closing a non-responsive connection (0 to disable)
74+
"grpc-keepalive-timeout"?: string | *"20s"
75+
76+
// Enable to set socket option SO_REUSEPORT on listeners allowing rebinding of a port already in use
77+
"socket-reuse-port"?: bool | *false
78+
79+
// Enable to set socket option SO_REUSEADDR on listeners allowing binding to an address in TIME_WAIT state
80+
"socket-reuse-address"?: bool | *false
81+
82+
// ========== CLUSTERING PARAMETERS ==========
83+
84+
// Discovery URL used to bootstrap the cluster
85+
"discovery"?: string | *""
86+
87+
// Expected behavior ('exit' or 'proxy') when discovery services fails
88+
"discovery-fallback"?: string & ("exit" | "proxy") | *"proxy"
89+
90+
// HTTP proxy to use for traffic to discovery service
91+
"discovery-proxy"?: string | *""
92+
93+
// DNS srv domain used to bootstrap the cluster
94+
"discovery-srv"?: string | *""
95+
96+
// Suffix to the dns srv name queried when bootstrapping
97+
"discovery-srv-name"?: string | *""
98+
99+
// Initial cluster configuration for bootstrapping
100+
"initial-cluster"?: string | *"default=http://localhost:2380"
101+
102+
// Initial cluster state ('new' or 'existing')
103+
"initial-cluster-state"?: string & ("new" | "existing") | *"new"
104+
105+
// Initial cluster token for the etcd cluster during bootstrap
106+
"initial-cluster-token"?: string | *"etcd-cluster"
107+
108+
// Reject reconfiguration requests that would cause quorum loss
109+
"strict-reconfig-check"?: bool | *true
110+
111+
// Enable the raft Pre-Vote algorithm to prevent disruption
112+
"pre-vote"?: bool | *true
113+
114+
// Auto compaction retention length. 0 means disable auto compaction
115+
"auto-compaction-retention"?: string | *"1"
116+
117+
// Interpret 'auto-compaction-retention' as 'periodic' or 'revision'
118+
"auto-compaction-mode"?: string & ("periodic" | "revision") | *"periodic"
119+
120+
// Accept etcd V2 client requests. Deprecated and to be decommissioned in v3.6
121+
"enable-v2"?: bool | *false
122+
123+
// Phase of v2store deprecation
124+
"v2-deprecation"?: string & ("not-yet" | "write-only" | "write-only-drop-data" | "gone") | *"not-yet"
125+
126+
// TLS configuration is handled through nested structures below
127+
// (removed duplicate top-level TLS fields to avoid confusion)
128+
129+
// 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.
130+
"self-signed-cert-validity"?: uint & >=1 & <=10 | *1
131+
132+
// Comma-separated list of supported TLS cipher suites
133+
"cipher-suites"?: [...string] | *["TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"]
134+
135+
// Minimum TLS version supported by etcd
136+
"tls-min-version"?: string & ("TLS1.0" | "TLS1.1" | "TLS1.2" | "TLS1.3") | *"TLS1.2"
137+
138+
// Maximum TLS version supported by etcd
139+
"tls-max-version"?: string & ("TLS1.0" | "TLS1.1" | "TLS1.2" | "TLS1.3" | "") | *"TLS1.3"
140+
141+
// Comma-separated whitelist of origins for CORS (cross-origin resource sharing)
142+
"cors"?: string | *""
143+
144+
// Acceptable hostnames from HTTP client requests, if server is not secure
145+
"host-whitelist"?: string | *"*"
146+
147+
// ========== AUTHENTICATION PARAMETERS ==========
148+
149+
// Specify a v3 authentication token type and its options ('simple' or 'jwt').
150+
"auth-token"?: string & ("simple" | "jwt") | *"simple"
151+
152+
// Specify the cost / strength of the bcrypt algorithm for hashing auth passwords. Valid values are between 4 and 31.
153+
"bcrypt-cost"?: uint & >=4 & <=31 | *10
154+
155+
// Time (in seconds) of the auth-token-ttl.
156+
"auth-token-ttl"?: uint & >=1 & <=86400 | *300
157+
158+
// ========== PROFILING AND MONITORING PARAMETERS ==========
159+
160+
// Enable runtime profiling data via HTTP server
161+
"enable-pprof"?: bool | *true
162+
163+
// Set level of detail for exported metrics
164+
"metrics"?: string & ("basic" | "extensive") | *"basic"
165+
166+
// List of URLs to listen on for the metrics and health endpoints
167+
"listen-metrics-urls"?: string | *""
168+
169+
// ========== NESTED TLS CONFIGURATION STRUCTURES ==========
170+
// These nested structures are used by etcd.conf.yaml.tpl template
171+
// for backward compatibility with etcd v2 configuration format
172+
173+
// Client TLS transport security configuration
21174
"client-transport-security"?: {
22-
"cert-file"?: string
23-
"key-file"?: string
175+
// Path to the client server TLS cert file (must be absolute path if specified)
176+
"cert-file"?: string | *""
177+
178+
// Path to the client server TLS key file (must be absolute path if specified)
179+
"key-file"?: string | *""
180+
181+
// Enable client cert authentication
24182
"client-cert-auth"?: bool | *false
25-
"trusted-ca-file"?: string
26-
"auto-tls"?: bool | *false
183+
184+
// Path to the client server TLS trusted CA cert file (must be absolute path if specified)
185+
"trusted-ca-file"?: string | *""
186+
187+
// Client TLS using generated certificates (incompatible with cert-file/key-file)
188+
"auto-tls"?: bool | *false
27189
}
28190

191+
// Peer TLS transport security configuration
29192
"peer-transport-security"?: {
30-
"cert-file"?: string
31-
"key-file"?: string
193+
// Path to the peer server TLS cert file (must be absolute path if specified)
194+
"cert-file"?: string | *""
195+
196+
// Path to the peer server TLS key file (must be absolute path if specified)
197+
"key-file"?: string | *""
198+
199+
// Enable peer client cert authentication
32200
"client-cert-auth"?: bool | *false
33-
"trusted-ca-file"?: string
34-
"auto-tls"?: bool | *false
35-
"allowed-cn"?: string
36-
"allowed-hostname"?: string
201+
202+
// Path to the peer server TLS trusted CA file (must be absolute path if specified)
203+
"trusted-ca-file"?: string | *""
204+
205+
// Peer TLS using self-generated certificates (incompatible with cert-file/key-file)
206+
"auto-tls"?: bool | *false
207+
208+
// Required CN for client certs connecting to the peer endpoint (comma-separated list)
209+
"allowed-cn"?: string | *""
210+
211+
// Allowed TLS hostname for inter peer authentication (comma-separated list)
212+
"allowed-hostname"?: string | *""
37213
}
38214

39-
// Cluster initialization (set by etcd.conf.yaml.tpl and data-load.sh)
40-
"initial-cluster"?: string
41-
"initial-cluster-token"?: string
42-
"initial-cluster-state"?: string & ("new" | "existing") | *"new"
215+
// ========== UNSAFE FEATURES PARAMETERS ==========
216+
// Warning: using unsafe features may break the guarantees given by the consensus protocol!
43217

44-
// Cluster management (immutable)
218+
// Force to create a new one-member cluster.
45219
"force-new-cluster"?: bool | *false
46220

47-
// ========== STATIC PARAMETERS ==========
48-
// These parameters require etcd restart to take effect and can be configured by users
221+
// Disables fsync, unsafe, will cause data loss.
222+
"unsafe-no-fsync"?: bool | *false
49223

50-
// WAL directory path
51-
"wal-dir"?: string
224+
// ========== LOGGING PARAMETERS ==========
52225

53-
// Snapshot configuration
54-
"snapshot-count"?: uint & >=1000 & <=1000000 | *10000
55-
"max-snapshots"?: uint & >=1 & <=100 | *5
56-
"max-wals"?: uint & >=1 & <=100 | *5
226+
// Currently only supports 'zap' for structured logging
227+
"logger"?: string & ("zap") | *"zap"
57228

58-
// Cluster timing configuration
59-
"heartbeat-interval"?: uint & >=50 & <=1000 | *100
60-
"election-timeout"?: uint & >=500 & <=10000 | *1000
61-
"quota-backend-bytes"?: uint & >=0 | *0
229+
// Specify 'stdout' or 'stderr' to skip journald logging even when running under systemd
230+
"log-outputs"?: [...string] | *["stderr"]
62231

63-
// Cluster behavior
64-
"strict-reconfig-check"?: bool | *true
232+
// Configures log level
233+
"log-level"?: string & ("debug" | "info" | "warn" | "error" | "panic" | "fatal") | *"info"
65234

66-
// Auto compaction configuration
67-
"auto-compaction-mode"?: string & ("periodic" | "revision") | *"periodic"
68-
"auto-compaction-retention"?: string | *"1"
235+
// Configures log format. Only supports json, console
236+
// NOTE: log-format is new in v3.6, ignored by v3.5
237+
"log-format"?: string & ("json" | "console") | *"json"
69238

70-
// TLS cipher suites configuration
71-
"cipher-suites"?: [...string]
72-
"tls-min-version"?: string & ("TLS1.0" | "TLS1.1" | "TLS1.2" | "TLS1.3") | *"TLS1.2"
73-
"tls-max-version"?: string & ("TLS1.0" | "TLS1.1" | "TLS1.2" | "TLS1.3") | *"TLS1.3"
239+
// Enable log rotation of a single log-outputs file target
240+
"enable-log-rotation"?: bool | *false
74241

75-
// Proxy configuration
76-
"proxy"?: string & ("off" | "readonly" | "on") | *"off"
77-
"proxy-failure-wait"?: uint & >=1000 & <=60000 | *5000
78-
"proxy-refresh-interval"?: uint & >=1000 & <=60000 | *30000
79-
"proxy-dial-timeout"?: uint & >=1000 & <=60000 | *1000
80-
"proxy-write-timeout"?: uint & >=1000 & <=60000 | *5000
81-
"proxy-read-timeout"?: uint & >=0 & <=60000 | *0
242+
// Configures log rotation if enabled with a JSON logger config
243+
"log-rotation-config-json"?: string | *"{\"maxsize\": 100, \"maxage\": 0, \"maxbackups\": 0, \"localtime\": false, \"compress\": false}"
82244

83-
// Performance configuration
84-
"enable-pprof"?: bool | *false
245+
// ========== EXPERIMENTAL DISTRIBUTED TRACING PARAMETERS ==========
85246

86-
// Security configuration
87-
"cors"?: string
88-
"self-signed-cert-validity"?: uint & >=1 & <=10 | *1
247+
// Enable experimental distributed tracing.
248+
"experimental-enable-distributed-tracing"?: bool | *false
89249

90-
// Discovery configuration
91-
"discovery"?: string
92-
"discovery-fallback"?: string & ("exit" | "proxy") | *"proxy"
93-
"discovery-proxy"?: string
94-
"discovery-srv"?: string
250+
// Distributed tracing collector address.
251+
"experimental-distributed-tracing-address"?: string | *"localhost:4317"
95252

96-
// Logging configuration
97-
"log-level"?: string & ("debug" | "info" | "warn" | "error" | "panic" | "fatal") | *"info"
98-
"logger"?: string & ("capnslog" | "zap") | *"zap"
99-
"log-outputs"?: [...string] | *["stderr"]
253+
// Distributed tracing service name, must be same across all etcd instances.
254+
"experimental-distributed-tracing-service-name"?: string | *"etcd"
255+
256+
// Distributed tracing instance ID, must be unique per each etcd instance.
257+
"experimental-distributed-tracing-instance-id"?: string | *""
258+
259+
// Number of samples to collect per million spans for OpenTelemetry Tracing (if enabled with experimental-enable-distributed-tracing flag).
260+
"experimental-distributed-tracing-sampling-rate"?: uint & >=0 & <=1000000 | *0
261+
262+
// ========== V2 PROXY PARAMETERS ==========
263+
// Note: flags will be deprecated in v3.6.
264+
265+
// Proxy mode setting ('off', 'readonly' or 'on').
266+
"proxy"?: string & ("off" | "readonly" | "on") | *"off"
267+
268+
// Time (in milliseconds) an endpoint will be held in a failed state.
269+
"proxy-failure-wait"?: uint & >=1000 & <=300000 | *5000
270+
271+
// Time (in milliseconds) of the endpoints refresh interval.
272+
"proxy-refresh-interval"?: uint & >=1000 & <=300000 | *30000
273+
274+
// Time (in milliseconds) for a dial to timeout.
275+
"proxy-dial-timeout"?: uint & >=1000 & <=60000 | *1000
276+
277+
// Time (in milliseconds) for a write to timeout.
278+
"proxy-write-timeout"?: uint & >=1000 & <=60000 | *5000
279+
280+
// Time (in milliseconds) for a read to timeout.
281+
"proxy-read-timeout"?: uint & >=0 & <=60000 | *0
282+
283+
// ========== EXPERIMENTAL FEATURES PARAMETERS ==========
284+
285+
// Enable to check data corruption before serving any client/peer traffic.
286+
"experimental-initial-corrupt-check"?: bool | *false
287+
288+
// Duration of time between cluster corruption check passes.
289+
"experimental-corrupt-check-time"?: string | *"0s"
290+
291+
// Serve v2 requests through the v3 backend under a given prefix. Deprecated and to be decommissioned in v3.6.
292+
"experimental-enable-v2v3"?: string | *""
293+
294+
// ExperimentalEnableLeaseCheckpoint enables primary lessor to persist lease remainingTTL to prevent indefinite auto-renewal of long lived leases.
295+
"experimental-enable-lease-checkpoint"?: bool | *false
296+
297+
// ExperimentalCompactionBatchLimit sets the maximum revisions deleted in each compaction batch.
298+
"experimental-compaction-batch-limit"?: uint & >=1 & <=10000 | *1000
299+
300+
// Skip verification of SAN field in client certificate for peer connections.
301+
"experimental-peer-skip-client-san-verification"?: bool | *false
302+
303+
// Duration of periodical watch progress notification.
304+
"experimental-watch-progress-notify-interval"?: string | *"10m"
305+
306+
// Warning is generated if requests take more than this duration.
307+
"experimental-warning-apply-duration"?: string | *"100ms"
308+
309+
// Enable the write transaction to use a shared buffer in its readonly check operations.
310+
"experimental-txn-mode-write-with-shared-buffer"?: bool | *true
311+
312+
// Enable the defrag during etcd server bootstrap on condition that it will free at least the provided threshold of disk space. Needs to be set to non-zero value to take effect.
313+
"experimental-bootstrap-defrag-threshold-megabytes"?: uint & >=0 | *0
100314

315+
// other parameters
101316
...
102317
}
103318

0 commit comments

Comments
 (0)