go.etcd.io/etcd@v3.3.27+incompatible/Documentation/dev-guide/interacting_v3.md (about) 1 --- 2 title: Interacting with etcd 3 --- 4 5 Users mostly interact with etcd by putting or getting the value of a key. This section describes how to do that by using etcdctl, a command line tool for interacting with etcd server. The concepts described here should apply to the gRPC APIs or client library APIs. 6 7 The API version used by etcdctl to speak to etcd may be set to version `2` or `3` via the `ETCDCTL_API` environment variable. By default, etcdctl on master (3.4) uses the v3 API and earlier versions (3.3 and earlier) default to the v2 API. 8 9 Note that any key that was created using the v2 API will not be able to be queried via the v2 API. A v3 API ```etcdctl get``` of a v2 key will exit with 0 and no key data, this is the expected behaviour. 10 11 12 ```bash 13 export ETCDCTL_API=3 14 ``` 15 16 ## Find versions 17 18 etcdctl version and Server API version can be useful in finding the appropriate commands to be used for performing various operations on etcd. 19 20 Here is the command to find the versions: 21 22 ```bash 23 $ etcdctl version 24 etcdctl version: 3.1.0-alpha.0+git 25 API version: 3.1 26 ``` 27 28 ## Write a key 29 30 Applications store keys into the etcd cluster by writing to keys. Every stored key is replicated to all etcd cluster members through the Raft protocol to achieve consistency and reliability. 31 32 Here is the command to set the value of key `foo` to `bar`: 33 34 ```bash 35 $ etcdctl put foo bar 36 OK 37 ``` 38 39 Also a key can be set for a specified interval of time by attaching lease to it. 40 41 Here is the command to set the value of key `foo1` to `bar1` for 10s. 42 43 ```bash 44 $ etcdctl put foo1 bar1 --lease=1234abcd 45 OK 46 ``` 47 48 Note: The lease id `1234abcd` in the above command refers to id returned on creating the lease of 10s. This id can then be attached to the key. 49 50 ## Read keys 51 52 Applications can read values of keys from an etcd cluster. Queries may read a single key, or a range of keys. 53 54 Suppose the etcd cluster has stored the following keys: 55 56 ```bash 57 foo = bar 58 foo1 = bar1 59 foo2 = bar2 60 foo3 = bar3 61 ``` 62 63 Here is the command to read the value of key `foo`: 64 65 ```bash 66 $ etcdctl get foo 67 foo 68 bar 69 ``` 70 71 Here is the command to read the value of key `foo` in hex format: 72 73 ```bash 74 $ etcdctl get foo --hex 75 \x66\x6f\x6f # Key 76 \x62\x61\x72 # Value 77 ``` 78 79 Here is the command to read only the value of key `foo`: 80 81 ```bash 82 $ etcdctl get foo --print-value-only 83 bar 84 ``` 85 86 Here is the command to range over the keys from `foo` to `foo3`: 87 88 ```bash 89 $ etcdctl get foo foo3 90 foo 91 bar 92 foo1 93 bar1 94 foo2 95 bar2 96 ``` 97 98 Note that `foo3` is excluded since the range is over the half-open interval `[foo, foo3)`, excluding `foo3`. 99 100 Here is the command to range over all keys prefixed with `foo`: 101 102 ```bash 103 $ etcdctl get --prefix foo 104 foo 105 bar 106 foo1 107 bar1 108 foo2 109 bar2 110 foo3 111 bar3 112 ``` 113 114 Here is the command to range over all keys prefixed with `foo`, limiting the number of results to 2: 115 116 ```bash 117 $ etcdctl get --prefix --limit=2 foo 118 foo 119 bar 120 foo1 121 bar1 122 ``` 123 124 ## Read past version of keys 125 126 Applications may want to read superseded versions of a key. For example, an application may wish to roll back to an old configuration by accessing an earlier version of a key. Alternatively, an application may want a consistent view over multiple keys through multiple requests by accessing key history. 127 Since every modification to the etcd cluster key-value store increments the global revision of an etcd cluster, an application can read superseded keys by providing an older etcd revision. 128 129 Suppose an etcd cluster already has the following keys: 130 131 ```bash 132 foo = bar # revision = 2 133 foo1 = bar1 # revision = 3 134 foo = bar_new # revision = 4 135 foo1 = bar1_new # revision = 5 136 ``` 137 138 Here are an example to access the past versions of keys: 139 140 ```bash 141 $ etcdctl get --prefix foo # access the most recent versions of keys 142 foo 143 bar_new 144 foo1 145 bar1_new 146 147 $ etcdctl get --prefix --rev=4 foo # access the versions of keys at revision 4 148 foo 149 bar_new 150 foo1 151 bar1 152 153 $ etcdctl get --prefix --rev=3 foo # access the versions of keys at revision 3 154 foo 155 bar 156 foo1 157 bar1 158 159 $ etcdctl get --prefix --rev=2 foo # access the versions of keys at revision 2 160 foo 161 bar 162 163 $ etcdctl get --prefix --rev=1 foo # access the versions of keys at revision 1 164 ``` 165 166 ## Read keys which are greater than or equal to the byte value of the specified key 167 168 Applications may want to read keys which are greater than or equal to the byte value of the specified key. 169 170 Suppose an etcd cluster already has the following keys: 171 172 ```bash 173 a = 123 174 b = 456 175 z = 789 176 ``` 177 178 Here is the command to read keys which are greater than or equal to the byte value of key `b` : 179 180 ```bash 181 $ etcdctl get --from-key b 182 b 183 456 184 z 185 789 186 ``` 187 188 ## Delete keys 189 190 Applications can delete a key or a range of keys from an etcd cluster. 191 192 Suppose an etcd cluster already has the following keys: 193 194 ```bash 195 foo = bar 196 foo1 = bar1 197 foo3 = bar3 198 zoo = val 199 zoo1 = val1 200 zoo2 = val2 201 a = 123 202 b = 456 203 z = 789 204 ``` 205 206 Here is the command to delete key `foo`: 207 208 ```bash 209 $ etcdctl del foo 210 1 # one key is deleted 211 ``` 212 213 Here is the command to delete keys ranging from `foo` to `foo9`: 214 215 ```bash 216 $ etcdctl del foo foo9 217 2 # two keys are deleted 218 ``` 219 220 Here is the command to delete key `zoo` with the deleted key value pair returned: 221 222 ```bash 223 $ etcdctl del --prev-kv zoo 224 1 # one key is deleted 225 zoo # deleted key 226 val # the value of the deleted key 227 ``` 228 229 Here is the command to delete keys having prefix as `zoo`: 230 231 ```bash 232 $ etcdctl del --prefix zoo 233 2 # two keys are deleted 234 ``` 235 236 Here is the command to delete keys which are greater than or equal to the byte value of key `b` : 237 238 ```bash 239 $ etcdctl del --from-key b 240 2 # two keys are deleted 241 ``` 242 243 ## Watch key changes 244 245 Applications can watch on a key or a range of keys to monitor for any updates. 246 247 Here is the command to watch on key `foo`: 248 249 ```bash 250 $ etcdctl watch foo 251 # in another terminal: etcdctl put foo bar 252 PUT 253 foo 254 bar 255 ``` 256 257 Here is the command to watch on key `foo` in hex format: 258 259 ```bash 260 $ etcdctl watch foo --hex 261 # in another terminal: etcdctl put foo bar 262 PUT 263 \x66\x6f\x6f # Key 264 \x62\x61\x72 # Value 265 ``` 266 267 Here is the command to watch on a range key from `foo` to `foo9`: 268 269 ```bash 270 $ etcdctl watch foo foo9 271 # in another terminal: etcdctl put foo bar 272 PUT 273 foo 274 bar 275 # in another terminal: etcdctl put foo1 bar1 276 PUT 277 foo1 278 bar1 279 ``` 280 281 Here is the command to watch on keys having prefix `foo`: 282 283 ```bash 284 $ etcdctl watch --prefix foo 285 # in another terminal: etcdctl put foo bar 286 PUT 287 foo 288 bar 289 # in another terminal: etcdctl put fooz1 barz1 290 PUT 291 fooz1 292 barz1 293 ``` 294 295 Here is the command to watch on multiple keys `foo` and `zoo`: 296 297 ```bash 298 $ etcdctl watch -i 299 $ watch foo 300 $ watch zoo 301 # in another terminal: etcdctl put foo bar 302 PUT 303 foo 304 bar 305 # in another terminal: etcdctl put zoo val 306 PUT 307 zoo 308 val 309 ``` 310 311 ## Watch historical changes of keys 312 313 Applications may want to watch for historical changes of keys in etcd. For example, an application may wish to receive all the modifications of a key; if the application stays connected to etcd, then `watch` is good enough. However, if the application or etcd fails, a change may happen during the failure, and the application will not receive the update in real time. To guarantee the update is delivered, the application must be able to watch for historical changes to keys. To do this, an application can specify a historical revision on a watch, just like reading past version of keys. 314 315 Suppose we finished the following sequence of operations: 316 317 ```bash 318 $ etcdctl put foo bar # revision = 2 319 OK 320 $ etcdctl put foo1 bar1 # revision = 3 321 OK 322 $ etcdctl put foo bar_new # revision = 4 323 OK 324 $ etcdctl put foo1 bar1_new # revision = 5 325 OK 326 ``` 327 328 Here is an example to watch the historical changes: 329 330 ```bash 331 # watch for changes on key `foo` since revision 2 332 $ etcdctl watch --rev=2 foo 333 PUT 334 foo 335 bar 336 PUT 337 foo 338 bar_new 339 ``` 340 341 ```bash 342 # watch for changes on key `foo` since revision 3 343 $ etcdctl watch --rev=3 foo 344 PUT 345 foo 346 bar_new 347 ``` 348 349 Here is an example to watch only from the last historical change: 350 351 ```bash 352 # watch for changes on key `foo` and return last revision value along with modified value 353 $ etcdctl watch --prev-kv foo 354 # in another terminal: etcdctl put foo bar_latest 355 PUT 356 foo # key 357 bar_new # last value of foo key before modification 358 foo # key 359 bar_latest # value of foo key after modification 360 ``` 361 362 ## Watch progress 363 364 Applications may want to check the progress of a watch to determine how up-to-date the watch stream is. For example, if a watch is used to update a cache, it can be useful to know if the cache is stale compared to the revision from a quorum read. 365 366 Progress requests can be issued using the "progress" command in interactive watch session to ask the etcd server to send a progress notify update in the watch stream: 367 368 ```bash 369 $ etcdctl watch -i 370 $ watch a 371 $ progress 372 progress notify: 1 373 # in another terminal: etcdctl put x 0 374 # in another terminal: etcdctl put y 1 375 $ progress 376 progress notify: 3 377 ``` 378 379 Note: The revision number in the progress notify response is the revision from the local etcd server node that the watch stream is connected to. If this node is partitioned and not part of quorum, this progress notify revision might be lower than 380 than the revision returned by a quorum read against a non-partitioned etcd server node. 381 382 ## Compacted revisions 383 384 As we mentioned, etcd keeps revisions so that applications can read past versions of keys. However, to avoid accumulating an unbounded amount of history, it is important to compact past revisions. After compacting, etcd removes historical revisions, releasing resources for future use. All superseded data with revisions before the compacted revision will be unavailable. 385 386 Here is the command to compact the revisions: 387 388 ```bash 389 $ etcdctl compact 5 390 compacted revision 5 391 392 # any revisions before the compacted one are not accessible 393 $ etcdctl get --rev=4 foo 394 Error: rpc error: code = 11 desc = etcdserver: mvcc: required revision has been compacted 395 ``` 396 397 Note: The current revision of etcd server can be found using get command on any key (existent or non-existent) in json format. Example is shown below for mykey which does not exist in etcd server: 398 399 ```bash 400 $ etcdctl get mykey -w=json 401 {"header":{"cluster_id":14841639068965178418,"member_id":10276657743932975437,"revision":15,"raft_term":4}} 402 ``` 403 404 ## Grant leases 405 406 Applications can grant leases for keys from an etcd cluster. When a key is attached to a lease, its lifetime is bound to the lease's lifetime which in turn is governed by a time-to-live (TTL). Each lease has a minimum time-to-live (TTL) value specified by the application at grant time. The lease's actual TTL value is at least the minimum TTL and is chosen by the etcd cluster. Once a lease's TTL elapses, the lease expires and all attached keys are deleted. 407 408 Here is the command to grant a lease: 409 410 ```bash 411 # grant a lease with 10 second TTL 412 $ etcdctl lease grant 10 413 lease 32695410dcc0ca06 granted with TTL(10s) 414 415 # attach key foo to lease 32695410dcc0ca06 416 $ etcdctl put --lease=32695410dcc0ca06 foo bar 417 OK 418 ``` 419 420 ## Revoke leases 421 422 Applications revoke leases by lease ID. Revoking a lease deletes all of its attached keys. 423 424 Suppose we finished the following sequence of operations: 425 426 ```bash 427 $ etcdctl lease grant 10 428 lease 32695410dcc0ca06 granted with TTL(10s) 429 $ etcdctl put --lease=32695410dcc0ca06 foo bar 430 OK 431 ``` 432 433 Here is the command to revoke the same lease: 434 435 ```bash 436 $ etcdctl lease revoke 32695410dcc0ca06 437 lease 32695410dcc0ca06 revoked 438 439 $ etcdctl get foo 440 # empty response since foo is deleted due to lease revocation 441 ``` 442 443 ## Keep leases alive 444 445 Applications can keep a lease alive by refreshing its TTL so it does not expire. 446 447 Suppose we finished the following sequence of operations: 448 449 ```bash 450 $ etcdctl lease grant 10 451 lease 32695410dcc0ca06 granted with TTL(10s) 452 ``` 453 454 Here is the command to keep the same lease alive: 455 456 ```bash 457 $ etcdctl lease keep-alive 32695410dcc0ca06 458 lease 32695410dcc0ca06 keepalived with TTL(10) 459 lease 32695410dcc0ca06 keepalived with TTL(10) 460 lease 32695410dcc0ca06 keepalived with TTL(10) 461 ... 462 ``` 463 464 ## Get lease information 465 466 Applications may want to know about lease information, so that they can be renewed or to check if the lease still exists or it has expired. Applications may also want to know the keys to which a particular lease is attached. 467 468 Suppose we finished the following sequence of operations: 469 470 ```bash 471 # grant a lease with 500 second TTL 472 $ etcdctl lease grant 500 473 lease 694d5765fc71500b granted with TTL(500s) 474 475 # attach key zoo1 to lease 694d5765fc71500b 476 $ etcdctl put zoo1 val1 --lease=694d5765fc71500b 477 OK 478 479 # attach key zoo2 to lease 694d5765fc71500b 480 $ etcdctl put zoo2 val2 --lease=694d5765fc71500b 481 OK 482 ``` 483 484 Here is the command to get information about the lease: 485 486 ```bash 487 $ etcdctl lease timetolive 694d5765fc71500b 488 lease 694d5765fc71500b granted with TTL(500s), remaining(258s) 489 ``` 490 491 Here is the command to get information about the lease along with the keys attached with the lease: 492 493 ```bash 494 $ etcdctl lease timetolive --keys 694d5765fc71500b 495 lease 694d5765fc71500b granted with TTL(500s), remaining(132s), attached keys([zoo2 zoo1]) 496 497 # if the lease has expired or does not exist it will give the below response: 498 Error: etcdserver: requested lease not found 499 ```