Etcd tutorial - Chapter 5 etcd etcdctl usage

Preface

Etcd In microservices and Kubernates Not only can it be used as a service in a cluster register And Find out , It can also be used as key-value Middleware for storage .

One 、etcdctl Introduce

etcdctl Is a command line client , It can provide some concise commands , For users to follow directly etcd Service contact , Without having to be based on HTTP API The way . It is convenient to test the service or modify the database content manually .
We can just start by etdctl To familiarize yourself with the relevant operations . These operations are similar to HTTP API It's basically the corresponding .etcdctl In two different etcd The behavior under version is also completely different .

export ETCDCTL_API=2
export ETCDCTL_API=3

This paper mainly uses API 3 Mainly .
Etcd The binary distribution package already contains etcdctl Tools ,etcdctl The supported commands are generally divided into database operation and non database operation .

Two 、 Non database operations

2.1 see Etcd Version of command

[[email protected] ~]# etcd --version
etcd Version: 3.5.4
Git SHA: 08407ff76
Go Version: go1.16.15
Go OS/Arch: linux/amd64

2.2 see etcdctl Common commands

[[email protected] ~]# etcdctl h
NAME:
        etcdctl - A simple command line client for etcd3.

USAGE:
        etcdctl [flags]

VERSION:
        3.5.4

API VERSION:
        3.5

COMMANDS:
        alarm disarm            Disarms all alarms
        alarm list              Lists all alarms
        auth disable            Disables authentication
        auth enable             Enables authentication
        auth status             Returns authentication status
        check datascale         Check the memory usage of holding data for different workloads on a given server endpoint.
        check perf              Check the performance of the etcd cluster
        compaction              Compacts the event history in etcd
        defrag                  Defragments the storage of the etcd members with given endpoints
        del                     Removes the specified key or range of keys [key, range_end)
        elect                   Observes and participates in leader election
        endpoint hashkv         Prints the KV history hash for each endpoint in --endpoints
        endpoint health         Checks the healthiness of endpoints specified in `--endpoints` flag
        endpoint status         Prints out the status of endpoints specified in `--endpoints` flag
        get                     Gets the key or a range of keys
        help                    Help about any command
        lease grant             Creates leases
        lease keep-alive        Keeps leases alive (renew)
        lease list              List all active leases
        lease revoke            Revokes leases
        lease timetolive        Get lease information
        lock                    Acquires a named lock
        make-mirror             Makes a mirror at the destination etcd cluster
        member add              Adds a member into the cluster
        member list             Lists all members in the cluster
        member promote          Promotes a non-voting member in the cluster
        member remove           Removes a member from the cluster
        member update           Updates a member in the cluster
        move-leader             Transfers leadership to another etcd cluster member.
        put                     Puts the given key into the store
        role add                Adds a new role
        role delete             Deletes a role
        role get                Gets detailed information of a role
        role grant-permission   Grants a key to a role
        role list               Lists all roles
        role revoke-permission  Revokes a key from a role
        snapshot restore        Restores an etcd member snapshot to an etcd directory
        snapshot save           Stores an etcd node backend snapshot to a given file
        snapshot status         [deprecated] Gets backend snapshot status of a given file
        txn                     Txn processes all the requests in one transaction
        user add                Adds a new user
        user delete             Deletes a user
        user get                Gets detailed information of a user
        user grant-role         Grants a role to a user
        user list               Lists all users
        user passwd             Changes password of user
        user revoke-role        Revokes a role from a user
        version                 Prints the version of etcdctl
        watch                   Watches events stream on keys or prefixes

OPTIONS:
      --cacert=""                               verify certificates of TLS-enabled secure servers using this CA bundle
      --cert=""                                 identify secure client using this TLS certificate file
      --command-timeout=5s                      timeout for short running command (excluding dial timeout)
      --debug[=false]                           enable client-side debug logging
      --dial-timeout=2s                         dial timeout for client connections
  -d, --discovery-srv=""                        domain name to query for SRV records describing cluster endpoints
      --discovery-srv-name=""                   service name to query when using DNS discovery
      --endpoints=[127.0.0.1:2379]              gRPC endpoints
  -h, --help[=false]                            help for etcdctl
      --hex[=false]                             print byte strings as hex encoded strings
      --insecure-discovery[=true]               accept insecure SRV records describing cluster endpoints
      --insecure-skip-tls-verify[=false]        skip server certificate verification (CAUTION: this option should be enabled only for testing purposes)
      --insecure-transport[=true]               disable transport security for client connections
      --keepalive-time=2s                       keepalive time for client connections
      --keepalive-timeout=6s                    keepalive timeout for client connections
      --key=""                                  identify secure client using this TLS key file
      --password=""                             password for authentication (if this option is used, --user option shouldn't include password)
      --user=""                                 username[:password] for authentication (prompt if password is not supplied)
  -w, --write-out="simple"                      set the output format (fields, json, protobuf, simple, table)

You can see ,etcdctl A lot of orders , Common command options 【OPTIONS】：

--debug  Output CURL command , Display the request initiated when executing the command 
--no-sync  Do not synchronize cluster information before making a request 
--output, -o 'simple'  Format of output content (simple  For the original information ,json  For the json Format decoding , Easier to read )
--peers, -C  Specify the peer information in the cluster , Separated by commas ( The default is : "127.0.0.1:4001")
--cert-file HTTPS For the next client SSL Certificate file 
--key-file HTTPS For the next client SSL The key file 
--ca-file  Server use HTTPS when , Use CA Document validation 
--help, -h  Display help command information 
--version, -v  Print version information 

3、 ... and 、 Database operation

Database operations revolve around the of key values and directories CRUD （ I.e. add, delete, change and check , accord with REST A set of styles API operation ） Complete lifecycle management .

Etcd The hierarchical spatial structure is adopted in the organization of keys ( Similar to the concept of directory in file system ), The key specified by the user can be a separate name , Such as ：testkey, At this time, it is actually placed in the root directory / below , You can also specify a directory structure for , Such as /cluster1/node2/testkey, The corresponding directory structure will be created .

3.1 Write operations

[[email protected] ~]# etcdctl put /testdir/testkey "Hello world"
OK
[[email protected] ~]# etcdctl put /testdir/testkey2 "Hello world2"
OK
[[email protected] ~]# etcdctl put /testdir/testkey3 "Hello world3"
OK

Three pairs of key values were written successfully ,/testdir/testkey、/testdir/testkey2 and /testdir/testkey3.

3.2 Read operations

[[email protected] ~]# etcdctl get /testdir/testkey
/testdir/testkey
Hello world

get Hexadecimal reads the specified value ：

[[email protected] ~]# etcdctl get /testdir/testkey --hex
\x2f\x74\x65\x73\x74\x64\x69\x72\x2f\x74\x65\x73\x74\x6b\x65\x79
\x48\x65\x6c\x6c\x6f\x20\x77\x6f\x72\x6c\x64

get Values in the specified range ：

[[email protected] ~]# etcdctl get /testdir/testkey /testdir/testkey3
/testdir/testkey
Hello world
/testdir/testkey2
Hello world2

You can see , Obtained greater than or equal to /testdir/testkey, And less than /testdir/testkey3 The key/value pair .testkey3 Out of range , Because the range is Semi open interval [testkey, testkey3), It doesn't contain testkey3.

Gets all key value pairs for the specified prefix , adopt –prefix You can specify a prefix ：

[[email protected] ~]# etcdctl get --prefix /testdir/testkey
/testdir/testkey
Hello world
/testdir/testkey2
Hello world2
/testdir/testkey3
Hello world3

In this way, you can get all the information in /testdir/testkey The first key value pair . When the current result is too many , You can also use –limit=2 Limit the number of acquisitions ：

etcdctl get --prefix --limit=2 /testdir/testkey

Read values from previous versions of the key ：

The application may want to read the substituted value of the key 【 That is, the old value 】. for example , The application may want to rollback to the old configuration through the previous version of the access key . perhaps , An application may want to obtain a unified view covering multiple keys through multiple requests , These requests can be made by accessing the key history . because etcd Each modification of the key value store on the cluster will increase etcd Global revision of the cluster , The application can provide the old etcd Modify the version to read the replaced key . The following key value pairs exist ：

foo = bar         # revision = 2
foo1 = bar2       # revision = 3
foo = bar_new     # revision = 4
foo1 = bar2_new   # revision = 5

preparation ：

[[email protected] ~]# etcdctl put foo bar
OK
[[email protected] ~]# etcdctl put foo1 bar2
OK
[[email protected] ~]# etcdctl put foo bar_new
OK
[[email protected] ~]# etcdctl put foo1 bar2_new
OK

Access previous versions key An example of ：

[[email protected] ~]# etcdctl get --prefix foo # Visit the latest version of key
foo
bar_new
foo1
bar2_new

[[email protected] ~]# etcdctl get --prefix --rev=4 foo #  Access No. 4 Versions key
foo
bar_new
foo1
bar2

[[email protected] ~]# etcdctl get --prefix --rev=3 foo #  Access No. 3 Versions key
foo
bar
foo1
bar2

[[email protected] ~]# etcdctl get --prefix --rev=2 foo #  Access No. 3 Versions key
foo
bar

[[email protected] ~]# etcdctl get --prefix --rev=1 foo #  Access No. 1 Versions key

Read a key greater than or equal to the specified key byte Value key
The application may want to read a key greater than or equal to the specified key Of byte Value key . hypothesis etcd The cluster already has the following keys ：

a = 123
b = 456
z = 789

Read keys greater than or equal to b Of byte Value key command ：

[[email protected] ~]# etcdctl get --from-key b
b
456
c
789

Delete key . Applications can be from etcd Delete a key or a specific range of keys in the cluster .
hypothesis etcd The cluster already has the following keys ：

a = 123
b = 456
c = 789
foo = bar_new
foo1 = bar2_new
hello = world

Delete key foo The order of ：

[[email protected] ~]# etcdctl del foo
1 #  Number of delete keys 

Remove from foo to foo1 Range key command ：

etcdctl del foo foo1

Delete key a And return the command of the deleted key value pair ：

[[email protected] ~]# etcdctl del --prev-kv a
1 #  Number of delete keys 
a #  Deleted key 
123 #  The value of the deleted key 

Delete prefix foo The command of the key ：

[[email protected] ~]# etcdctl del --prefix foo
1 #  Number of delete keys 

Delete keys greater than or equal to b Of byte Value key command ：

[[email protected] ~]# etcdctl del --from-key b
3 #  Number of delete keys 

3.3 watch History changes