技術文章 » etcd — 操作手冊

etcd — 操作手冊

2020-10-05 16:00:22

目錄

文章目錄

與 etcd 互動

etcd v3 API 使用 gRPC 協定。etcd 專案包括了一個基於 gRPC 的 Golang Client SDK 和一個指令行工具 etcdctl，用於通過 gRPC 協定與 etcd Cluster 進行通訊。對於不支援 gRPC 的程式語言，etcd 還提供了一個 JSON gRPC 閘道器。 該閘道器提供一個 RESTful Proxy，該 Proxy 將 HTTP/JSON 請求轉換為 gRPC 訊息。

  • Swagger API Docs：https://github.com/etcd-io/etcd/blob/master/Documentation/dev-guide/apispec/swagger/rpc.swagger.json

注意，gRPC 閘道器不支援使用 TLS 通用名稱的身份驗證。

etcdctl 互動

Put（建立/更新）

通過 put 將 key 和 value 儲存到 etcd 叢集中。每個儲存的 key 都通過 Raft 協定複製到所有 etcd 叢整合員，以實現一致性和可靠性。

$ ./etcdctl put foo bar --user root --password=pass
OK

Get（查詢）

通過 get 可以從一個 etcd 叢集中讀取 key 的值。

假設現在 etcd 叢集已經儲存了以下資料：

foo = bar
foo1 = bar1
foo2 = bar2
foo3 = bar3
a = 123
b = 456
z = 789
  • 讀取鍵為 foo 的命令：
$ ./etcdctl get foo --user root --password=pass
foo    // key
bar    // value
  • 唯讀取 key 對應的值呢：
$ ./etcdctl get foo --print-value-only --user root --password=pass
bar
  • 讀取一系列 key，例如區間 [foo, foo3)：
$ ./etcdctl get foo foo3 --print-value-only --user root --password=pass
bar
bar1
bar2
  • 按字首讀取：
$ ./etcdctl get --prefix foo --print-value-only --user root --password=pass
bar
bar1
bar2
bar3
  • 限制結果數量：
$ ./etcdctl get --prefix foo --print-value-only --limit=2 --user root --password=pass
bar
bar1
  • 讀取大於或等於指定鍵的位元組值的鍵：
$ ./etcdctl get --from-key b --user root --password=pass
b
456
c
789
foo
bar
foo1
bar1
foo2
bar2
foo3
bar3

使用者可能希望通過存取早期版本的 key 來回滾到舊版本的設定。由於對 etcd 叢集鍵值儲存區的每次修改都會增加一個 etcd 叢集的全域性修訂版本（revision），因此使用者可以通過提供舊的 etcd 修訂版（revision）來讀取被取代的鍵。

假設一個 etcd 叢集已經有以下 key：

foo = bar         # revision = 2
foo1 = bar1       # revision = 3
foo = bar_new     # revision = 4
foo1 = bar1_new   # revision = 5

以下是存取以前版本 key 的範例：

# 存取最新版本的 key
$ etcdctl get --prefix foo 
foo
bar_new
foo1
bar1_new

# 存取第 4 個版本的 key
$ etcdctl get --prefix foo --rev=4
foo
bar_new
foo1
bar1

#  存取第 3 個版本的key
$ etcdctl get --prefix foo --rev=3
foo
bar
foo1
bar1

Del（刪除）

通過 del 可以從一個 etcd 叢集中刪除一個 key 或一系列 key。

假設一個 etcd 叢集已經有以下key：

foo = bar
foo1 = bar1
foo3 = bar3
zoo = val
zoo1 = val1
zoo2 = val2
a = 123
b = 456
z = 789
  • 刪除指定的 key：
$ etcdctl del foo
1
  • 刪除指定的鍵值對：
$ etcdctl del --prev-kv zoo
1
zoo
val
  • 刪除從 foo 到 foo9 的命令：
$ etcdctl del foo foo9
2
  • 刪除具有字首的鍵的命令：
$ etcdctl del --prefix zoo
2
  • 刪除大於或等於鍵的位元組值的鍵的命令:
$ etcdctl del --from-key b
2

Watch（監控）

Watch 用於監測一個 key-value 的變化，一旦 key-value 發生更新，就會輸出最新的值並退出。

  • 開啟第一個終端，監聽 foo 的變化：
$ etcdctl watch foo
  • 開啟另外一個終端來對 foo 進行操作：
$ etcdctl put foo 123
OK
$ etcdctl put foo 456
OK
$ ./etcdctl del foo
1
  • 第一個終端追蹤的結果如下：
$ etcdctl watch foo
PUT
foo
123
PUT
foo
456
DELETE
foo

除了以上基本操作，Watch 也可以像 get、del 操作那樣使用 prefix、rev、hex 等引數。

Lock（分散式鎖）

Distributed locks（分散式鎖），即：一個人操作的時候，另外一個人只能看，不能操作。

etcd 的 lock 指令對指定的 key 進行加鎖。注意，只有當正常退出且釋放鎖後，lock 命令的退出碼是 0，否則這個鎖會一直被佔用直到過期（預設 60 秒）。

  • 在第一個終端輸入如下命令：
$ etcdctl lock mutex1 --user root --password=pass
mutex1/326963a02758b52d
  • 在第二個終端輸入同樣的命令：
$ etcdctl lock mutex1 --user root --password=pass

在此可以發現第二個終端發生了阻塞，並未返回類似 mutex1/326963a02758b52d 的輸出。此時，如果我們使用 Ctrl+C 結束了第一個終端的 lock，然後第二個終端的顯示如下：

mutex1/694d74f33b51c654

可見，這就是一個分散式鎖的實現。

Transactions（事務）

txn 支援從標準輸入中讀取多個請求，並將它們看做一個原子性的事務執行。事務是由條件列表，條件判斷成功時的執行列表（條件列表中全部條件為真表示成功）和條件判斷失敗時的執行列表（條件列表中有一個為假即為失敗）組成的。

$ ./etcdctl put user frank --user root --password=pass
OK

$ ./etcdctl txn -i --user root --password=pass
compares:
value("user") = "frank"

success requests (get, put, del):
put result ok

failure requests (get, put, del):
put result failed

SUCCESS

OK

$ ./etcdctl get result --user root --password=pass
result
ok
  1. 先使用 etcdctl put user frank 設定 user 為 frank。然後 etcdctl txn -i 開啟事務（-i 表示互動模式）。
  2. 第 2 步輸入命令後回車，終端顯示出 compares:。
  3. 輸入 value("user") = "frank"，此命令是比較 user 的值與 frank 是否相等。
  4. 第 4 步完成後輸入回車，終端會換行顯示，此時可以繼續輸入判斷條件（前面說過事務由條件列表組成），再次輸入回車表示判斷條件輸入完畢。
  5. 第 5 步連續輸入兩個回車後，終端顯示出 success requests (get, put, delete):，表示下面輸入判斷條件為真時要執行的命令。
  6. 與輸入判斷條件相同，連續兩個回車表示成功時的執行列表輸入完成。
  7. 終端顯示 failure requests (get, put, delete): 後輸入條件判斷失敗時的執行列表。

為了看起來簡潔，此範例中條件列表和執行列表只寫了一行命令，實際可以輸入多行。總結上面的事務，要做的事情就是 user 為 frank 時設定 result 為 ok，否則設定 result 為 failed，事務執行完成後檢視 result 值為 ok。

Compact（壓縮）

etcd 會儲存資料的修訂版本，以便使用者可以讀取舊版本的 key。但是為了避免累積無盡頭的版本歷史，就需要壓縮過去的修訂版本。壓縮後，etcd 會刪除歷史版本並釋放資源。

$ etcdctl compact 5
compacted revision 5

$ etcdctl get --rev=4 foo
Error: etcdserver: mvcc: required revision has been compacted

Lease（租約）

key TTL（生存時間）是 etcd 的重要特性之一，即設定 key 的超時時間。與 Redis 不同，etcd 需要先建立 lease（租約），通過 put --lease= 設定。而 lease 又由 TTL 管理，以此來實現 key 超時設定的功能。

  • 授予 Lease：
$ etcdctl lease grant 30                                                                                                                        
lease 694d6ee9ac06945d granted with TTL(30s)

$ etcdctl put --lease=694d6ee9ac06945d foo bar
OK
  • 復原指定 Lease：
$ etcdctl lease revoke 694d6ee9ac06945d                                                                                                               
lease 694d6ee9ac06945d revoked

$ etcdctl get foo
  • 使用者可以通過重新整理指定的 key TTL 來保持 Lease：
$ etcdctl lease grant 10
lease 32695410dcc0ca06 granted with TTL(10s)

某些時候，使用者可能希望瞭解 Lease 的資訊，以便可以續約或檢查 Lease 是否仍然存在或已過期。另外，使用者也可能希望瞭解到指定 Lease 所附的 keys。

假設我們完成了以下一系列操作：

$ etcdctl lease grant 200
lease 694d6ee9ac06946a granted with TTL(200s)

$ etcdctl put demo1 val1 --lease=694d6ee9ac06946a
OK

$ etcdctl put demo2 val2 --lease=694d6ee9ac06946a
OK
  • 獲取指定 Lease 的資訊：
$ etcdctl lease timetolive 694d6ee9ac06946a
lease 694d6ee9ac06946a granted with TTL(200s), remaining(178s)
  • 獲取指定 Lease 所附的 keys：
$ etcdctl lease timetolive --keys 694d6ee9ac06946a
lease 694d6ee9ac06946a granted with TTL(200s), remaining(129s), attached keys([demo1 demo2])

API 互動

Authentication

Set up authentication with the /v3/auth service.

# create root user
$ curl -L http://localhost:2379/v3/auth/user/add \
  -X POST -d '{"name": "root", "password": "pass"}'
  
{
  "header": {
    "cluster_id": "14841639068965178418",
    "member_id": "10276657743932975437",
    "revision": "5",
    "raft_term": "3"
  }
}

# create root role
$ curl -L http://localhost:2379/v3/auth/role/add \
  -X POST -d '{"name": "root"}'
  
{
  "header": {
    "cluster_id": "14841639068965178418",
    "member_id": "10276657743932975437",
    "revision": "5",
    "raft_term": "3"
  }
}

# grant root role
$ curl -L http://localhost:2379/v3/auth/user/grant \
  -X POST -d '{"user": "root", "role": "root"}'
  
{
  "header": {
    "cluster_id": "14841639068965178418",
    "member_id": "10276657743932975437",
    "revision": "5",
    "raft_term": "3"
  }
}

# enable auth
$ curl -L http://localhost:2379/v3/auth/enable -X POST -d '{}'

{
  "header": {
    "cluster_id": "14841639068965178418",
    "member_id": "10276657743932975437",
    "revision": "5",
    "raft_term": "3"
  }
}

Authenticate with etcd for an authentication token using /v3/auth/authenticate.

# get the auth token for the root user
$ curl -L http://localhost:2379/v3/auth/authenticate \
  -X POST -d '{"name": "root", "password": "pass"}'
  
{
  "header": {
    "cluster_id": "14841639068965178418",
    "member_id": "10276657743932975437",
    "revision": "5",
    "raft_term": "3"
  },
  "token": "CAmBqFhXjZCCFRQV.15"
}

Set the Authorization header to the authentication token to fetch a key using authentication credentials.

$ curl -L http://localhost:2379/v3/kv/put \
  -H 'Authorization: CAmBqFhXjZCCFRQV.15' \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'
  
{
  "header": {
    "cluster_id": "14841639068965178418",
    "member_id": "10276657743932975437",
    "revision": "7",
    "raft_term": "3"
  }
}

Put and get keys

Use the /v3/kv/range and /v3/kv/put services to read and write keys.

# Write
$ curl -L http://localhost:2379/v3/kv/put \
  -H 'Authorization: CAmBqFhXjZCCFRQV.15' \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'
  
{
  "header": {
    "cluster_id": "14841639068965178418",
    "member_id": "10276657743932975437",
    "revision": "3",
    "raft_term": "3"
  }
}

# Read
$ curl -L http://localhost:2379/v3/kv/range \
  -H 'Authorization: CAmBqFhXjZCCFRQV.15' \
  -X POST -d '{"key": "Zm9v"}'
  
{
  "header": {
    "cluster_id": "14841639068965178418",
    "member_id": "10276657743932975437",
    "revision": "3",
    "raft_term": "3"
  },
  "kvs": [
    {
      "key": "Zm9v",
      "create_revision": "2",
      "mod_revision": "3",
      "version": "2",
      "value": "YmFy"
    }
  ],
  "count": "1"
}


# get all keys prefixed with "foo"
$ curl -L http://localhost:2379/v3/kv/range \
  -H 'Authorization: CAmBqFhXjZCCFRQV.15' \
  -X POST -d '{"key": "Zm9v", "range_end": "Zm9w"}'
  
{
  "header": {
    "cluster_id": "14841639068965178418",
    "member_id": "10276657743932975437",
    "revision": "3",
    "raft_term": "3"
  },
  "kvs": [
    {
      "key": "Zm9v",
      "create_revision": "2",
      "mod_revision": "3",
      "version": "2",
      "value": "YmFy"
    }
  ],
  "count": "1"
}

Watch keys

Use the /v3/watch service to watch keys.

  • Watch 指定的 key：
$ curl -N http://localhost:2379/v3/watch \
  -H 'Authorization: CAmBqFhXjZCCFRQV.15' \
  -X POST -d '{"create_request": {"key":"Zm9v"} }' | jq .

{
  "result": {
    "header": {
      "cluster_id": "14841639068965178418",
      "member_id": "10276657743932975437",
      "revision": "3",
      "raft_term": "3"
    },
    "created": true
  }
}
  • 更新該 key：
$ curl -L http://localhost:2379/v3/kv/put \
  -H 'Authorization: CAmBqFhXjZCCFRQV.15' \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}' >/dev/null 2>&1
  • Watch key 的變更會被跟蹤到：
{
  "result": {
    "header": {
      "cluster_id": "14841639068965178418",
      "member_id": "10276657743932975437",
      "revision": "4",
      "raft_term": "3"
    },
    "events": [
      {
        "kv": {
          "key": "Zm9v",
          "create_revision": "2",
          "mod_revision": "4",
          "version": "3",
          "value": "YmFy"
        }
      }
    ]
  }
}

Transactions

Issue a transaction with /v3/kv/txn.

# target CREATE
$ curl -L http://localhost:2379/v3/kv/txn \
  -H 'Authorization: CAmBqFhXjZCCFRQV.15' \
  -X POST \
  -d '{"compare":[{"target":"CREATE","key":"Zm9v","createRevision":"2"}],"success":[{"requestPut":{"key":"Zm9v","value":"YmFy"}}]}'
  
{
  "header": {
    "cluster_id": "14841639068965178418",
    "member_id": "10276657743932975437",
    "revision": "5",
    "raft_term": "3"
  },
  "succeeded": true,
  "responses": [
    {
      "response_put": {
        "header": {
          "revision": "5"
        }
      }
    }
  ]
}

# target VERSION

$ curl -L http://localhost:2379/v3/kv/txn \
  -H 'Authorization: CAmBqFhXjZCCFRQV.15' \
  -X POST \
  -d '{"compare":[{"version":"4","result":"EQUAL","target":"VERSION","key":"Zm9v"}],"success":[{"requestRange":{"key":"Zm9v"}}]}'
  
{
  "header": {
    "cluster_id": "14841639068965178418",
    "member_id": "10276657743932975437",
    "revision": "5",
    "raft_term": "3"
  },
  "succeeded": true,
  "responses": [
    {
      "response_range": {
        "header": {
          "revision": "5"
        },
        "kvs": [
          {
            "key": "Zm9v",
            "create_revision": "2",
            "mod_revision": "5",
            "version": "4",
            "value": "YmFy"
          }
        ],
        "count": "1"
      }
    }
  ]
}

Golang Client SDK 互動

etcd 提供了一個 Golang Client SDK 用於編寫 etcd 使用者端程式，下面簡單列舉一些例子，加強體感。

首先範例化一個 client 範例：

    cli,err := clientv3.New(clientv3.Config{
        Endpoints:[]string{"localhost:2379"},
        DialTimeout: 5 * time.Second,
    })
  • Endpoints：etcd 的多個節點服務地址，因為筆者使用的單點部署，所以只傳 1 個服務入口。
  • DialTimeout：建立 client 的首次連線超時，這裡傳了 5 秒，如果 5 秒都沒有連線成功就會返回 err；值得注意的是，一旦 client 建立成功，我們就不用再關心後續底層連線的狀態了，client 內部會進行重連。

k-v 存取：

kv := clientev3.NewKV(client)

// Put
putResp, err := kv.Put(context.TODO(), "/data-dir/example", "hello-world!")

// Get
getResp, err := kv.Get(context.TODO(), "/data-dir/example")

Lease：

lease := clientv3.NewLease(client)

// 建立一個租約，它有 10 秒的 TTL
grantResp, err := lease.Grant(context.TODO(), 10)

// 指定一個租約建立 k-v
kv.Put(context.TODO(), "/example/expireme", "lease-go", clientv3.WithLease(grantResp.ID))