From afdcaa0684f4957c23d397750bcd124edad0e7fa Mon Sep 17 00:00:00 2001 From: Somoshree Date: Mon, 13 Sep 2021 10:55:37 +0530 Subject: [PATCH 1/5] Added 'Getting started with etcdctl' page and also modified Quickstart page to link to the newly added page --- .../docs/v3.5/Getting-started-with-etcdctl.md | 429 ++++++++++++++++++ content/en/docs/v3.5/quickstart.md | 2 + 2 files changed, 431 insertions(+) create mode 100644 content/en/docs/v3.5/Getting-started-with-etcdctl.md diff --git a/content/en/docs/v3.5/Getting-started-with-etcdctl.md b/content/en/docs/v3.5/Getting-started-with-etcdctl.md new file mode 100644 index 00000000..2f920fdf --- /dev/null +++ b/content/en/docs/v3.5/Getting-started-with-etcdctl.md @@ -0,0 +1,429 @@ +--- +title: Getting started with etcdctl +weight: 3250 +description: "etcdctl: a command line tool for interacting with the etcd server" +--- +Users mostly interact with etcd by putting or getting the value of a key. This page 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. + +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. + +Note that any key that was created using the v2 API will not be able to be queried via the v3 API. A v3 API ```etcdctl get``` of a v2 key will exit with 0 and no key data, this is the expected behaviour. + + +```bash +export ETCDCTL_API=3 +``` + +## Synopsis of operations performed by etcdctl + + +### Finding versions + +etcdctl version and Server API version can be useful in finding the appropriate commands to be used for performing various operations on etcd. + +Here is the command to find the versions: + +```bash +$ etcdctl version +etcdctl version: 3.1.0-alpha.0+git +API version: 3.1 +``` + +## Write a key + +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. + +Here is the command to set the value of key `foo` to `bar`: + +```bash +$ etcdctl put foo bar +OK +``` + + +## Read keys + +Applications can read values of keys from an etcd cluster. Queries may read a single key, or a range of keys. + +Suppose the etcd cluster has stored the following keys: + +```bash +foo = bar +foo1 = bar1 +foo2 = bar2 +foo3 = bar3 +``` + +Here is the command to read the value of key `foo`: + +```bash +$ etcdctl get foo +foo +bar +``` + +Here is the command to read only the value of key `foo`: + +```bash +$ etcdctl get foo --print-value-only +bar +``` + +Here is the command to range over the keys from `foo` to `foo3`: + +```bash +$ etcdctl get foo foo3 +foo +bar +foo1 +bar1 +foo2 +bar2 +``` + +Note that `foo3` is excluded since the range is over the half-open interval `[foo, foo3)`, excluding `foo3`. + + + +## Read past version of keys + +Applications may want to read superseded versions of a key. 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. + +Suppose an etcd cluster already has the following keys: + +```bash +foo = bar # revision = 2 +foo1 = bar1 # revision = 3 +foo = bar_new # revision = 4 +foo1 = bar1_new # revision = 5 +``` + +Here are an example to access the past versions of keys: + +```bash +$ etcdctl get --prefix foo # access the most recent versions of keys +foo +bar_new +foo1 +bar1_new + +$ etcdctl get --prefix --rev=4 foo # access the versions of keys at revision 4 +foo +bar_new +foo1 +bar1 + +$ etcdctl get --prefix --rev=3 foo # access the versions of keys at revision 3 +foo +bar +foo1 +bar1 + +$ etcdctl get --prefix --rev=2 foo # access the versions of keys at revision 2 +foo +bar + +$ etcdctl get --prefix --rev=1 foo # access the versions of keys at revision 1 +``` + +## Read keys which are greater than or equal to the byte value of the specified key + +Applications may want to read keys which are greater than or equal to the byte value of the specified key. + +Suppose an etcd cluster already has the following keys: + +```bash +a = 123 +b = 456 +z = 789 +``` + +Here is the command to read keys which are greater than or equal to the byte value of key `b` : + +```bash +$ etcdctl get --from-key b +b +456 +z +789 +``` +## Delete keys + +Applications can delete a key or a range of keys from an etcd cluster. + +Suppose an etcd cluster already has the following keys: + +```bash +foo = bar +foo1 = bar1 +foo3 = bar3 +zoo = val +zoo1 = val1 +zoo2 = val2 +a = 123 +b = 456 +z = 789 +``` + +Here is the command to delete key `foo`: + +```bash +$ etcdctl del foo +1 # one key is deleted +``` + +Here is the command to delete keys ranging from `foo` to `foo9`: + +```bash +$ etcdctl del foo foo9 +2 # two keys are deleted +``` + +Here is the command to delete key `zoo` with the deleted key value pair returned: + +```bash +$ etcdctl del --prev-kv zoo +1 # one key is deleted +zoo # deleted key +val # the value of the deleted key +``` + +Here is the command to delete keys having prefix as `zoo`: + +```bash +$ etcdctl del --prefix zoo +2 # two keys are deleted +``` + +Here is the command to delete keys which are greater than or equal to the byte value of key `b` : + +```bash +$ etcdctl del --from-key b +2 # two keys are deleted +``` + +## Watch key changes + +Applications can watch on a key or a range of keys to monitor for any updates. + +Here is the command to watch on key `foo`: + +```bash +$ etcdctl watch foo +# in another terminal: etcdctl put foo bar +PUT +foo +bar +``` + +Here is the command to watch on a range key from `foo` to `foo9`: + +```bash +$ etcdctl watch foo foo9 +# in another terminal: etcdctl put foo bar +PUT +foo +bar +# in another terminal: etcdctl put foo1 bar1 +PUT +foo1 +bar1 +``` + +Here is the command to watch on multiple keys `foo` and `zoo`: + +```bash +$ etcdctl watch -i +$ watch foo +$ watch zoo +# in another terminal: etcdctl put foo bar +PUT +foo +bar +# in another terminal: etcdctl put zoo val +PUT +zoo +val +``` + +## Watch historical changes of keys + +Applications may want to watch for historical changes of keys in etcd.To do this, an application can specify a historical revision on a watch, just like reading past version of keys. + +Suppose we finished the following sequence of operations: + +```bash +$ etcdctl put foo bar # revision = 2 +OK +$ etcdctl put foo1 bar1 # revision = 3 +OK +$ etcdctl put foo bar_new # revision = 4 +OK +$ etcdctl put foo1 bar1_new # revision = 5 +OK +``` + +Here is an example to watch the historical changes: + +```bash +# watch for changes on key `foo` since revision 2 +$ etcdctl watch --rev=2 foo +PUT +foo +bar +PUT +foo +bar_new +``` + +```bash +# watch for changes on key `foo` since revision 3 +$ etcdctl watch --rev=3 foo +PUT +foo +bar_new +``` + +Here is an example to watch only from the last historical change: + +```bash +# watch for changes on key `foo` and return last revision value along with modified value +$ etcdctl watch --prev-kv foo +# in another terminal: etcdctl put foo bar_latest +PUT +foo # key +bar_new # last value of foo key before modification +foo # key +bar_latest # value of foo key after modification +``` + +## Watch progress + +Applications may want to check the progress of a watch to determine how up-to-date the watch stream is. 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: + +```bash +$ etcdctl watch -i +$ watch a +$ progress +progress notify: 1 +# in another terminal: etcdctl put x 0 +# in another terminal: etcdctl put y 1 +$ progress +progress notify: 3 +``` + +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 +than the revision returned by a quorum read against a non-partitioned etcd server node. + +## Compacted revisions + +After compacting past revisions, etcd removes historical revisions, releasing resources for future use. All superseded data with revisions before the compacted revision will be unavailable. + +Here is the command to compact the revisions: + +```bash +$ etcdctl compact 5 +compacted revision 5 + +# any revisions before the compacted one are not accessible +$ etcdctl get --rev=4 foo +Error: rpc error: code = 11 desc = etcdserver: mvcc: required revision has been compacted +``` + +## Grant leases + +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. Once a lease's TTL elapses, the lease expires and all attached keys are deleted. + +Here is the command to grant a lease: + +```bash +# grant a lease with 60 second TTL +$ etcdctl lease grant 60 +lease 32695410dcc0ca06 granted with TTL(60s) + +# attach key foo to lease 32695410dcc0ca06 +$ etcdctl put --lease=32695410dcc0ca06 foo bar +OK +``` + +## Revoke leases + +Applications revoke leases by lease ID. Revoking a lease deletes all of its attached keys. + +Suppose we finished the following sequence of operations: + +```bash +$ etcdctl lease grant 60 +lease 32695410dcc0ca06 granted with TTL(60s) +$ etcdctl put --lease=32695410dcc0ca06 foo bar +OK +``` + +Here is the command to revoke the same lease: + +```bash +$ etcdctl lease revoke 32695410dcc0ca06 +lease 32695410dcc0ca06 revoked + +$ etcdctl get foo +# empty response since foo is deleted due to lease revocation +``` + +## Keep leases alive + +Applications can keep a lease alive by refreshing its TTL so it does not expire. + +Suppose we finished the following sequence of operations: + +```bash +$ etcdctl lease grant 60 +lease 32695410dcc0ca06 granted with TTL(60s) +``` + +Here is the command to keep the same lease alive: + +```bash +$ etcdctl lease keep-alive 32695410dcc0ca06 +lease 32695410dcc0ca06 keepalived with TTL(60) +lease 32695410dcc0ca06 keepalived with TTL(60) +lease 32695410dcc0ca06 keepalived with TTL(60) +... +``` + +## Get lease information + +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. + +Suppose we finished the following sequence of operations: + +```bash +# grant a lease with 500 second TTL +$ etcdctl lease grant 500 +lease 694d5765fc71500b granted with TTL(500s) + +# attach key zoo1 to lease 694d5765fc71500b +$ etcdctl put zoo1 val1 --lease=694d5765fc71500b +OK + +# attach key zoo2 to lease 694d5765fc71500b +$ etcdctl put zoo2 val2 --lease=694d5765fc71500b +OK +``` + +Here is the command to get information about the lease: + +```bash +$ etcdctl lease timetolive 694d5765fc71500b +lease 694d5765fc71500b granted with TTL(500s), remaining(258s) +``` + +Here is the command to get information about the lease along with the keys attached with the lease: + +```bash +$ etcdctl lease timetolive --keys 694d5765fc71500b +lease 694d5765fc71500b granted with TTL(500s), remaining(132s), attached keys([zoo2 zoo1]) + +# if the lease has expired or does not exist it will give the below response: +Error: etcdserver: requested lease not found +``` +This is all that you need to get started with using etcdctl! \ No newline at end of file diff --git a/content/en/docs/v3.5/quickstart.md b/content/en/docs/v3.5/quickstart.md index a91b06fd..c22e12eb 100644 --- a/content/en/docs/v3.5/quickstart.md +++ b/content/en/docs/v3.5/quickstart.md @@ -87,6 +87,7 @@ Learn about more ways to configure and use etcd from the following pages: - Explore the gRPC [API][]. - Set up a [multi-machine cluster][clustering]. - Learn how to [configure][] etcd. +- Learn how to get started with [etcdctl][]. - Find [language bindings and tools][integrations]. - Use TLS to [secure an etcd cluster][security]. - [Tune etcd][tuning]. @@ -94,6 +95,7 @@ Learn about more ways to configure and use etcd from the following pages: [api]: /docs/{{< param version >}}/learning/api [clustering]: /docs/{{< param version >}}/op-guide/clustering [configure]: /docs/{{< param version >}}/op-guide/configuration +[etcdctl]: /docs/{{< param version >}}/Getting-started-with-etcdctl [integrations]: /docs/{{< param version >}}/integrations [security]: /docs/{{< param version >}}/op-guide/security [tuning]: /docs/{{< param version >}}/tuning From 0a18b2b929443c1db3f8490524235b45a52cb645 Mon Sep 17 00:00:00 2001 From: Somoshree Date: Mon, 13 Sep 2021 11:00:14 +0530 Subject: [PATCH 2/5] Added 'Getting started with etcdctl' page and also modified Quickstart page to link to the newly added page --- content/en/docs/v3.5/quickstart.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/content/en/docs/v3.5/quickstart.md b/content/en/docs/v3.5/quickstart.md index c22e12eb..a91b06fd 100644 --- a/content/en/docs/v3.5/quickstart.md +++ b/content/en/docs/v3.5/quickstart.md @@ -87,7 +87,6 @@ Learn about more ways to configure and use etcd from the following pages: - Explore the gRPC [API][]. - Set up a [multi-machine cluster][clustering]. - Learn how to [configure][] etcd. -- Learn how to get started with [etcdctl][]. - Find [language bindings and tools][integrations]. - Use TLS to [secure an etcd cluster][security]. - [Tune etcd][tuning]. @@ -95,7 +94,6 @@ Learn about more ways to configure and use etcd from the following pages: [api]: /docs/{{< param version >}}/learning/api [clustering]: /docs/{{< param version >}}/op-guide/clustering [configure]: /docs/{{< param version >}}/op-guide/configuration -[etcdctl]: /docs/{{< param version >}}/Getting-started-with-etcdctl [integrations]: /docs/{{< param version >}}/integrations [security]: /docs/{{< param version >}}/op-guide/security [tuning]: /docs/{{< param version >}}/tuning From 9d8ec46bb0fd40d79ace26184769c05f6a84a4e8 Mon Sep 17 00:00:00 2001 From: Somoshree Date: Mon, 13 Sep 2021 11:03:50 +0530 Subject: [PATCH 3/5] Added 'Getting started with etcdctl' page and also modified Quickstart page to link to the newly added page --- content/en/docs/v3.5/quickstart.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/en/docs/v3.5/quickstart.md b/content/en/docs/v3.5/quickstart.md index a91b06fd..ec8faffe 100644 --- a/content/en/docs/v3.5/quickstart.md +++ b/content/en/docs/v3.5/quickstart.md @@ -87,6 +87,7 @@ Learn about more ways to configure and use etcd from the following pages: - Explore the gRPC [API][]. - Set up a [multi-machine cluster][clustering]. - Learn how to [configure][] etcd. +- Learn how to get started with [etcdctl][]. - Find [language bindings and tools][integrations]. - Use TLS to [secure an etcd cluster][security]. - [Tune etcd][tuning]. @@ -94,6 +95,7 @@ Learn about more ways to configure and use etcd from the following pages: [api]: /docs/{{< param version >}}/learning/api [clustering]: /docs/{{< param version >}}/op-guide/clustering [configure]: /docs/{{< param version >}}/op-guide/configuration +[etcdctl]: /docs/{{< param version >}}/getting-started-with-etcdctl [integrations]: /docs/{{< param version >}}/integrations [security]: /docs/{{< param version >}}/op-guide/security [tuning]: /docs/{{< param version >}}/tuning From 5397fa8acd216790ba9b2fa94fc60f62c76d46ef Mon Sep 17 00:00:00 2001 From: Somoshree Date: Tue, 14 Sep 2021 12:11:49 +0530 Subject: [PATCH 4/5] Modified structure of Getting-started-with-etcdctl page --- .../docs/v3.5/Getting-started-with-etcdctl.md | 398 +----------------- 1 file changed, 7 insertions(+), 391 deletions(-) diff --git a/content/en/docs/v3.5/Getting-started-with-etcdctl.md b/content/en/docs/v3.5/Getting-started-with-etcdctl.md index 2f920fdf..09e977d6 100644 --- a/content/en/docs/v3.5/Getting-started-with-etcdctl.md +++ b/content/en/docs/v3.5/Getting-started-with-etcdctl.md @@ -3,7 +3,7 @@ title: Getting started with etcdctl weight: 3250 description: "etcdctl: a command line tool for interacting with the etcd server" --- -Users mostly interact with etcd by putting or getting the value of a key. This page 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. +Users mostly interact with etcd by putting or getting the value of a key. This page describes how to do that by using etcdctl, a command line tool for interacting with etcd server and also points to various links for more detailed explanations on important/advanced topics. The concepts described here should apply to the gRPC APIs or client library APIs. 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. @@ -14,12 +14,11 @@ Note that any key that was created using the v2 API will not be able to be queri export ETCDCTL_API=3 ``` -## Synopsis of operations performed by etcdctl +To get started with installing and setting up an etcd cluster, follow the instructions in [Install]( ../../../docs/v3.5/install) page of the documentation. +To configure local etcd cluster for testing and development purposes, visit [Set up a local cluster](../../../docs/v3.5/dev-guide/local_cluster) for more details. -### Finding versions - -etcdctl version and Server API version can be useful in finding the appropriate commands to be used for performing various operations on etcd. +Once the etcd cluster is set up and running, it might be a good option to know the versions of etcdctl and Server API in order to find the appropriate commands to be used for performing various operations on etcd. Here is the command to find the versions: @@ -28,33 +27,14 @@ $ etcdctl version etcdctl version: 3.1.0-alpha.0+git API version: 3.1 ``` - -## Write a key - -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. - -Here is the command to set the value of key `foo` to `bar`: +To write a key to be stored into the etcd cluster, below is the command to set the value of a key `foo` to `bar`: ```bash $ etcdctl put foo bar OK ``` - -## Read keys - -Applications can read values of keys from an etcd cluster. Queries may read a single key, or a range of keys. - -Suppose the etcd cluster has stored the following keys: - -```bash -foo = bar -foo1 = bar1 -foo2 = bar2 -foo3 = bar3 -``` - -Here is the command to read the value of key `foo`: +Similarly, to read the values of keys from an etcd cluster, here is the command to read the value of the key `foo`: ```bash $ etcdctl get foo @@ -62,368 +42,4 @@ foo bar ``` -Here is the command to read only the value of key `foo`: - -```bash -$ etcdctl get foo --print-value-only -bar -``` - -Here is the command to range over the keys from `foo` to `foo3`: - -```bash -$ etcdctl get foo foo3 -foo -bar -foo1 -bar1 -foo2 -bar2 -``` - -Note that `foo3` is excluded since the range is over the half-open interval `[foo, foo3)`, excluding `foo3`. - - - -## Read past version of keys - -Applications may want to read superseded versions of a key. 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. - -Suppose an etcd cluster already has the following keys: - -```bash -foo = bar # revision = 2 -foo1 = bar1 # revision = 3 -foo = bar_new # revision = 4 -foo1 = bar1_new # revision = 5 -``` - -Here are an example to access the past versions of keys: - -```bash -$ etcdctl get --prefix foo # access the most recent versions of keys -foo -bar_new -foo1 -bar1_new - -$ etcdctl get --prefix --rev=4 foo # access the versions of keys at revision 4 -foo -bar_new -foo1 -bar1 - -$ etcdctl get --prefix --rev=3 foo # access the versions of keys at revision 3 -foo -bar -foo1 -bar1 - -$ etcdctl get --prefix --rev=2 foo # access the versions of keys at revision 2 -foo -bar - -$ etcdctl get --prefix --rev=1 foo # access the versions of keys at revision 1 -``` - -## Read keys which are greater than or equal to the byte value of the specified key - -Applications may want to read keys which are greater than or equal to the byte value of the specified key. - -Suppose an etcd cluster already has the following keys: - -```bash -a = 123 -b = 456 -z = 789 -``` - -Here is the command to read keys which are greater than or equal to the byte value of key `b` : - -```bash -$ etcdctl get --from-key b -b -456 -z -789 -``` -## Delete keys - -Applications can delete a key or a range of keys from an etcd cluster. - -Suppose an etcd cluster already has the following keys: - -```bash -foo = bar -foo1 = bar1 -foo3 = bar3 -zoo = val -zoo1 = val1 -zoo2 = val2 -a = 123 -b = 456 -z = 789 -``` - -Here is the command to delete key `foo`: - -```bash -$ etcdctl del foo -1 # one key is deleted -``` - -Here is the command to delete keys ranging from `foo` to `foo9`: - -```bash -$ etcdctl del foo foo9 -2 # two keys are deleted -``` - -Here is the command to delete key `zoo` with the deleted key value pair returned: - -```bash -$ etcdctl del --prev-kv zoo -1 # one key is deleted -zoo # deleted key -val # the value of the deleted key -``` - -Here is the command to delete keys having prefix as `zoo`: - -```bash -$ etcdctl del --prefix zoo -2 # two keys are deleted -``` - -Here is the command to delete keys which are greater than or equal to the byte value of key `b` : - -```bash -$ etcdctl del --from-key b -2 # two keys are deleted -``` - -## Watch key changes - -Applications can watch on a key or a range of keys to monitor for any updates. - -Here is the command to watch on key `foo`: - -```bash -$ etcdctl watch foo -# in another terminal: etcdctl put foo bar -PUT -foo -bar -``` - -Here is the command to watch on a range key from `foo` to `foo9`: - -```bash -$ etcdctl watch foo foo9 -# in another terminal: etcdctl put foo bar -PUT -foo -bar -# in another terminal: etcdctl put foo1 bar1 -PUT -foo1 -bar1 -``` - -Here is the command to watch on multiple keys `foo` and `zoo`: - -```bash -$ etcdctl watch -i -$ watch foo -$ watch zoo -# in another terminal: etcdctl put foo bar -PUT -foo -bar -# in another terminal: etcdctl put zoo val -PUT -zoo -val -``` - -## Watch historical changes of keys - -Applications may want to watch for historical changes of keys in etcd.To do this, an application can specify a historical revision on a watch, just like reading past version of keys. - -Suppose we finished the following sequence of operations: - -```bash -$ etcdctl put foo bar # revision = 2 -OK -$ etcdctl put foo1 bar1 # revision = 3 -OK -$ etcdctl put foo bar_new # revision = 4 -OK -$ etcdctl put foo1 bar1_new # revision = 5 -OK -``` - -Here is an example to watch the historical changes: - -```bash -# watch for changes on key `foo` since revision 2 -$ etcdctl watch --rev=2 foo -PUT -foo -bar -PUT -foo -bar_new -``` - -```bash -# watch for changes on key `foo` since revision 3 -$ etcdctl watch --rev=3 foo -PUT -foo -bar_new -``` - -Here is an example to watch only from the last historical change: - -```bash -# watch for changes on key `foo` and return last revision value along with modified value -$ etcdctl watch --prev-kv foo -# in another terminal: etcdctl put foo bar_latest -PUT -foo # key -bar_new # last value of foo key before modification -foo # key -bar_latest # value of foo key after modification -``` - -## Watch progress - -Applications may want to check the progress of a watch to determine how up-to-date the watch stream is. 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: - -```bash -$ etcdctl watch -i -$ watch a -$ progress -progress notify: 1 -# in another terminal: etcdctl put x 0 -# in another terminal: etcdctl put y 1 -$ progress -progress notify: 3 -``` - -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 -than the revision returned by a quorum read against a non-partitioned etcd server node. - -## Compacted revisions - -After compacting past revisions, etcd removes historical revisions, releasing resources for future use. All superseded data with revisions before the compacted revision will be unavailable. - -Here is the command to compact the revisions: - -```bash -$ etcdctl compact 5 -compacted revision 5 - -# any revisions before the compacted one are not accessible -$ etcdctl get --rev=4 foo -Error: rpc error: code = 11 desc = etcdserver: mvcc: required revision has been compacted -``` - -## Grant leases - -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. Once a lease's TTL elapses, the lease expires and all attached keys are deleted. - -Here is the command to grant a lease: - -```bash -# grant a lease with 60 second TTL -$ etcdctl lease grant 60 -lease 32695410dcc0ca06 granted with TTL(60s) - -# attach key foo to lease 32695410dcc0ca06 -$ etcdctl put --lease=32695410dcc0ca06 foo bar -OK -``` - -## Revoke leases - -Applications revoke leases by lease ID. Revoking a lease deletes all of its attached keys. - -Suppose we finished the following sequence of operations: - -```bash -$ etcdctl lease grant 60 -lease 32695410dcc0ca06 granted with TTL(60s) -$ etcdctl put --lease=32695410dcc0ca06 foo bar -OK -``` - -Here is the command to revoke the same lease: - -```bash -$ etcdctl lease revoke 32695410dcc0ca06 -lease 32695410dcc0ca06 revoked - -$ etcdctl get foo -# empty response since foo is deleted due to lease revocation -``` - -## Keep leases alive - -Applications can keep a lease alive by refreshing its TTL so it does not expire. - -Suppose we finished the following sequence of operations: - -```bash -$ etcdctl lease grant 60 -lease 32695410dcc0ca06 granted with TTL(60s) -``` - -Here is the command to keep the same lease alive: - -```bash -$ etcdctl lease keep-alive 32695410dcc0ca06 -lease 32695410dcc0ca06 keepalived with TTL(60) -lease 32695410dcc0ca06 keepalived with TTL(60) -lease 32695410dcc0ca06 keepalived with TTL(60) -... -``` - -## Get lease information - -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. - -Suppose we finished the following sequence of operations: - -```bash -# grant a lease with 500 second TTL -$ etcdctl lease grant 500 -lease 694d5765fc71500b granted with TTL(500s) - -# attach key zoo1 to lease 694d5765fc71500b -$ etcdctl put zoo1 val1 --lease=694d5765fc71500b -OK - -# attach key zoo2 to lease 694d5765fc71500b -$ etcdctl put zoo2 val2 --lease=694d5765fc71500b -OK -``` - -Here is the command to get information about the lease: - -```bash -$ etcdctl lease timetolive 694d5765fc71500b -lease 694d5765fc71500b granted with TTL(500s), remaining(258s) -``` - -Here is the command to get information about the lease along with the keys attached with the lease: - -```bash -$ etcdctl lease timetolive --keys 694d5765fc71500b -lease 694d5765fc71500b granted with TTL(500s), remaining(132s), attached keys([zoo2 zoo1]) - -# if the lease has expired or does not exist it will give the below response: -Error: etcdserver: requested lease not found -``` -This is all that you need to get started with using etcdctl! \ No newline at end of file +To know more about all the functionalities that etcdctl offers, visit [Interacting with etcd](../../../docs/v3.5/dev-guide/interacting_v3) for more details. From 97311f6ab0d25b7e1b24b8aa186dfe410b02ea4e Mon Sep 17 00:00:00 2001 From: Somoshree Date: Tue, 14 Sep 2021 19:05:44 +0530 Subject: [PATCH 5/5] Highlighted a few terms --- content/en/docs/v3.5/Getting-started-with-etcdctl.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/en/docs/v3.5/Getting-started-with-etcdctl.md b/content/en/docs/v3.5/Getting-started-with-etcdctl.md index 09e977d6..001673e3 100644 --- a/content/en/docs/v3.5/Getting-started-with-etcdctl.md +++ b/content/en/docs/v3.5/Getting-started-with-etcdctl.md @@ -14,9 +14,9 @@ Note that any key that was created using the v2 API will not be able to be queri export ETCDCTL_API=3 ``` -To get started with installing and setting up an etcd cluster, follow the instructions in [Install]( ../../../docs/v3.5/install) page of the documentation. ++ To get started with installing and setting up an etcd cluster, follow the instructions in **[Install]( ../../../docs/v3.5/install)** page of the documentation. -To configure local etcd cluster for testing and development purposes, visit [Set up a local cluster](../../../docs/v3.5/dev-guide/local_cluster) for more details. ++ To configure local etcd cluster for testing and development purposes, visit **[Set up a local cluster](../../../docs/v3.5/dev-guide/local_cluster)** for more details. Once the etcd cluster is set up and running, it might be a good option to know the versions of etcdctl and Server API in order to find the appropriate commands to be used for performing various operations on etcd. @@ -27,14 +27,14 @@ $ etcdctl version etcdctl version: 3.1.0-alpha.0+git API version: 3.1 ``` -To write a key to be stored into the etcd cluster, below is the command to set the value of a key `foo` to `bar`: +To **write a key** to be stored into the etcd cluster, below is the command to set the value of a key `foo` to `bar`: ```bash $ etcdctl put foo bar OK ``` -Similarly, to read the values of keys from an etcd cluster, here is the command to read the value of the key `foo`: +Similarly, to **read the values of keys** from an etcd cluster, here is the command to read the value of the key `foo`: ```bash $ etcdctl get foo @@ -42,4 +42,4 @@ foo bar ``` -To know more about all the functionalities that etcdctl offers, visit [Interacting with etcd](../../../docs/v3.5/dev-guide/interacting_v3) for more details. +To know more about all the functionalities that etcdctl offers, visit **[Interacting with etcd](../../../docs/v3.5/dev-guide/interacting_v3)** for more details.