これはセクションの複数ページ印刷用ビューです。 .

開発者向けタスク

アプリケーションでetcdをキー・バリューストアとして使用する開発者向けの段階的なガイド。

1: etcdからの読み取り
2: etcdへの書き込み
3: プレフィックスでキーを取得する方法
4: キーの削除方法
5: トランザクションで複数の書き込みを行う方法
6: キーの監視方法
7: リースの作成方法
8: ロックの作成方法

1 - etcdからの読み取り

etcdクラスターの値を読み取る

前提条件

etcdctlをインストールします。

手順

getサブコマンドを使用して、etcdから読み取ります。

$ etcdctl --endpoints=$ENDPOINTS get foo
foo
Hello World!
$

各要素の意味は次のとおりです。

fooは要求したキーです。
Hello World!は取得した値です。

出力形式を指定する場合は、次のように実行します。

$ etcdctl --endpoints=$ENDPOINTS --write-out="json" get foo
{"header":{"cluster_id":289318470931837780,"member_id":14947050114012957595,"revision":3,"raft_term":4,
"kvs":[{"key":"Zm9v","create_revision":2,"mod_revision":3,"version":2,"value":"SGVsbG8gV29ybGQh"}]}}
$

ここで、write-out="json"を指定すると、キーと値の両方がbase64でエンコードされたJSONが返されます。

2 - etcdへの書き込み

etcdクラスターにキー・バリューペアを追加する

前提条件

etcdctlをインストールします。

手順

putサブコマンドを使用して、キー・バリューペアを書き込みます。

etcdctl --endpoints=$ENDPOINTS put foo "Hello World!"

各要素の意味は次のとおりです。

fooはキーの名前です。
"Hello World!"は引用符で囲んだ値です。

3 - プレフィックスでキーを取得する方法

プレフィックスでetcdのキーを抽出するためのガイド

前提条件

etcdctlをインストールします。
ローカルクラスターをセットアップします。

プレフィックスでキーを取得する

$ etcdctl --endpoints=$ENDPOINTS get PREFIX --prefix

グローバルオプション

--endpoints=[127.0.0.1:2379], gRPC endpoints

オプション

--prefix, get a range of keys with matching prefix

例

etcdctl --endpoints=$ENDPOINTS put web1 value1
etcdctl --endpoints=$ENDPOINTS put web2 value2
etcdctl --endpoints=$ENDPOINTS put web3 value3

etcdctl --endpoints=$ENDPOINTS get web --prefix

4 - キーの削除方法

etcdのキーを削除する方法を説明します

前提条件

etcdとetcdctl をインストールします。

キーの追加または削除

指定したキーまたはキー範囲を削除するdel：

etcdctl del $KEY [$END_KEY]

オプション

--prefix[=false]: delete keys with matching prefix
--prev-kv[=false]: return deleted key-value pairs
--from-key[=false]: delete keys that are greater than or equal to the given key using byte compare
--range[=false]: delete range of keys without delay

親コマンドから継承されるオプション

--endpoints="127.0.0.1:2379": gRPC endpoints

例

etcdctl --endpoints=$ENDPOINTS put key myvalue
etcdctl --endpoints=$ENDPOINTS del key

etcdctl --endpoints=$ENDPOINTS put k1 value1
etcdctl --endpoints=$ENDPOINTS put k2 value2
etcdctl --endpoints=$ENDPOINTS del k --prefix

5 - トランザクションで複数の書き込みを行う方法

トランザクションによる書き込みのガイド

前提条件

etcdとetcdctl がインストールされていること。
etcdクラスターが稼働していること。

用語

以下の例で使用する主な用語を定義します。

用語	定義
etcdctl	etcdサーバーを操作するコマンドラインツール。
`txn` コマンド	`txn`は「transaction」の略です。複数のetcdリクエストを標準入力から読み込み、単一の不可分なトランザクションとして適用します。トランザクションは、条件のリスト、すべての条件が真の場合に適用するリクエストのリスト、いずれかの条件が偽の場合に適用するリクエストのリストで構成されます。詳細はetcdctlのキー・バリューコマンドを参照してください。
`compare`	トランザクション（`txn`）内の`compare`句は、その処理を実行するかどうかを決める条件判定です。キー・バリューストアの現在の状態が期待する条件に一致する場合にのみ変更を適用することで、データの整合性を維持し、並行処理での競合を防ぎます。コマンドの構成は、以下のトランザクションの実行を参照してください。

トランザクション

txnを使用して、すべてのリクエストを1つのトランザクションで処理します。

etcdctl txn --help

etcdのトランザクションでは、複数の操作を不可分に実行し、すべての操作を適用するか、どれも適用しないかのいずれかとなることを保証します。これは、関連する更新を行う際のデータ整合性の維持に不可欠です。トランザクションの詳細はAPIドキュメントを参照してください。

例

ユーザーのメールアドレスと電話番号を1つのトランザクションで更新する場合を考えます。これにより、両方の更新がまとめて適用されることを保証します。

0. 使用する変数とフラグ

変数
`/users/{<user_id>/email`：ユーザーのメールアドレスを表すetcdキー。
`/users/<user_id>/phone`：ユーザーの電話番号を表すetcdキー。
フラグ
`--interactive` ：トランザクションのデータを手動で入力できるようにするフラグ。

1. 初期データの設定

まず、初期データを持つユーザーを作成します。

etcdctl put /users/12345/email "old.address@johndoe.com"
etcdctl put /users/12345/phone "123-456-7890"

2. トランザクションの実行

ユーザーのメールアドレスと電話番号を1つのトランザクションで更新します。

etcdctl txn --interactive

compares:
value("/users/12345/email") = "old.address@johndoe.com"

success requests (get, put, delete):
put /users/12345/email "new.address@johndoe.com"
put /users/12345/phone "098-765-4321"

failure requests (get, put, delete):
get /users/12345/email

比較：現在のメールアドレスが「old.address@johndoe.com 」であるかを確認します。これにより、データが期待どおりの場合にのみトランザクションを実行します。
成功：比較結果が真なら、メールアドレスと電話番号の両方を更新します。
失敗：比較に失敗した場合は、現在のメールアドレスを取得し、トランザクションが実行されなかった理由を確認します。

重要な注意点

原子性：トランザクションにより、メールアドレスと電話番号がまとめて更新されることを保証します。最初の条件（比較）を満たさなければ、どちらの更新も適用されません。
整合性：トランザクションを使用すると、特に複数の関連する更新を扱う場合に、データの整合性を維持できます。
同じキーへの複数回のputを避ける：予期しない結果を招く可能性があるため、1つのトランザクション内で同じキーに複数の値をputしないでください。各キーの更新は、1トランザクションにつき1回にすることを推奨します。

6 - キーの監視方法

etcdのキーを監視するためのガイド

前提条件

etcdとetcdctl をインストールします。

キーの監視

今後の変更の通知を受け取るwatch：

etcdctl watch $KEY [$END_KEY]

オプション

-i, --interactive[=false]: interactive mode
--prefix[=false]: watch on a prefix if prefix is set
--rev=0: Revision to start watching
--prev-kv[=false]: get the previous key-value pair before the event happens
--progress-notify[=false]: get periodic watch progress notification from server

親コマンドから継承されるオプション

--endpoints="127.0.0.1:2379": gRPC endpoints

例

etcdctl --endpoints=$ENDPOINTS watch stock1
etcdctl --endpoints=$ENDPOINTS put stock1 1000

etcdctl --endpoints=$ENDPOINTS watch stock --prefix
etcdctl --endpoints=$ENDPOINTS put stock1 10
etcdctl --endpoints=$ENDPOINTS put stock2 20

7 - リースの作成方法

etcdでリースを作成するためのガイド

TTLを指定した書き込みに使用するlease：

etcdctl --endpoints=$ENDPOINTS lease grant 300
# lease 2be7547fbc6a5afa granted with TTL(300s)

etcdctl --endpoints=$ENDPOINTS put sample value --lease=2be7547fbc6a5afa
etcdctl --endpoints=$ENDPOINTS get sample

etcdctl --endpoints=$ENDPOINTS lease keep-alive 2be7547fbc6a5afa
etcdctl --endpoints=$ENDPOINTS lease revoke 2be7547fbc6a5afa
# or after 300 seconds
etcdctl --endpoints=$ENDPOINTS get sample

8 - ロックの作成方法

etcdで分散ロックを作成するためのガイド

LOCKは、指定された名前の分散ミューテックスを取得します。取得したロックは、etcdctlが終了するまで保持されます。

前提条件

etcdとetcdctl をインストールします。

ロックの作成

分散ロックに使用するlock：

etcdctl --endpoints=$ENDPOINTS lock mutex1

オプション

endpoints - クラスター内のマシンのアドレスを、コンマ区切りのリストで指定します。
ttl - ロックセッションのタイムアウトを秒単位で指定します。