本文へ移動

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

このページの通常のビューに戻る.

etcd 3.7 ドキュメント

開発者、運用担当者、アップグレード、API、内部実装に関するetcd 3.7の公式ガイド。

etcdは、強い整合性を備えた分散キー・バリューストアです。これらのガイドでは、etcdのインストールと運用、APIを使用したアプリケーションの構築、設計の理解、性能の測定、3.7リリース系列でのクラスターのアップグレードとダウングレードについて説明します。

ローカルの単一メンバークラスターを作成する場合はクイックスタート 、サポートされるインストール方法についてはインストール 、本番環境へのデプロイについては運用ガイド から始めてください。

1 - タスク

このセクションでは、etcdを使用するアプリケーションの開発者と、etcdクラスターのデプロイ、構成、保守を担当する運用担当者に向けて、タスク別のガイドを提供します。

1.1 - 運用担当者向けタスク

etcdクラスターのデプロイ、構成、保守に関する運用ガイド。

1.1.1 - etcdクラスターでリーダー選出を行う方法

etcdctlクライアントを使用してリーダー選出を行う手順

前提条件

  • etcd とetcdctl がインストールされていることを確認します。
  • 稼働中のetcdクラスターを確認します。

リーダー選出を行う

etcdctlコマンドは、etcdクラスターでリーダー選出を行うために使用します。一度にリーダーになれるクライアントが1つだけであることを保証します。

etcdctl --endpoints=$ENDPOINTS elect <election-name> [proposal]

etcdctl --endpoints=$ENDPOINTS elect election-name p1

オプション

  • --endpoints : $ENDPOINTS

各etcdクラスターメンバーのアドレス。

  • election-name文字列

選出を識別する文字列です。リーダーの地位を競うすべての参加者は、同じ選出名を使用する必要があります。

  • leader-name文字列

新しいリーダーの提案値。

例

./etcdctl elect my-election proposal1
my-election/694d99fafea88404
proposal1

another election:
./etcdctl elect new-election proposal1
new-election/694d99fafea8840f
proposal1

1.1.2 - データベースの保存方法

etcdデータベースのスナップショットを取得するためのガイド

前提条件

データベースのスナップショットを取得する

etcdデータベースのある時点のスナップショットを保存するsnapshot：

etcdctl --endpoints=$ENDPOINT snapshot save DB_NAME

グローバルオプション

etcdctl

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

スナップショットを要求できるetcdノードは1つだけなので、--endpointsフラグにはエンドポイントを1つだけ指定する必要があります。

etcdutl

-w, --write-out string   set the output format (fields, json, protobuf, simple, table) (default "simple")

例

11_etcdctl_snapshot_2016051001
ENDPOINTS=$HOST_1:2379
etcdctl --endpoints=$ENDPOINTS snapshot save my.db

Snapshot saved at my.db
etcdutl --write-out=table snapshot status my.db

+---------+----------+------------+------------+
|  HASH   | REVISION | TOTAL KEYS | TOTAL SIZE |
+---------+----------+------------+------------+
| c55e8b8 |        9 |         13 | 25 kB      |
+---------+----------+------------+------------+

1.2 - 開発者向けタスク

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

1.2.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"を指定すると、値はJSON形式で出力されます（キーは返されない点に注意してください）。

1.2.2 - etcdへの書き込み

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

前提条件

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

手順

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

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

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

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

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

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

前提条件

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

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

グローバルオプション

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

オプション

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

例

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

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

1.2.4 - キーの削除方法

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

前提条件

キーの追加と削除

指定したキーまたはキー範囲を削除する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

例

04_etcdctl_delete_2016050601
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

1.2.5 - キーの監視方法

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

前提条件

キーの監視

今後の変更の通知を受け取る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

例

06_etcdctl_watch_2016050501
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

1.2.6 - リースの作成方法

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

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

07_etcdctl_lease_2016050501
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

1.2.7 - ロックの作成方法

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

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

前提条件

ロックの作成

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

08_etcdctl_lock_2016050501
etcdctl --endpoints=$ENDPOINTS lock mutex1

オプション

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

2 - クイックスタート

5分以内にetcdを起動して使い始めましょう！

次の手順に従って、単一メンバーのetcdクラスターをローカルにインストールし、実行してテストします。

  1. ビルド済みのバイナリーまたはソースからetcdをインストールします。詳細はインストール を参照してください。

    警告

    重要：インストール手順の最後のステップを必ず実行し、etcdが検索パスに含まれていることを確認してください。

  2. etcdを起動します。

    $ etcd
{"level":"info","ts":"2021-09-17T09:19:32.783-0400","caller":"etcdmain/etcd.go:72","msg":... }
⋮
    注記

    注意：etcdの出力はログ です。— infoレベルのログは無視できます。

  3. 別のターミナルから、etcdctlを使用してキーを設定します。

    $ etcdctl put greeting "Hello, etcd"
OK

  4. 同じターミナルからキーを取得します。

    $ etcdctl get greeting
greeting
Hello, etcd

次のステップ

etcdの構成方法と使用方法について、詳しくは次のページを参照してください。

3 - デモ

etcdクラスターの操作手順

この一連の例では、etcdクラスターを操作するための基本的な手順を示します。

認証

認証に使用するauth、user、role：

export ETCDCTL_API=3
ENDPOINTS=localhost:2379

etcdctl --endpoints=${ENDPOINTS} role add root
etcdctl --endpoints=${ENDPOINTS} role get root

etcdctl --endpoints=${ENDPOINTS} user add root
etcdctl --endpoints=${ENDPOINTS} user grant-role root root
etcdctl --endpoints=${ENDPOINTS} user get root

etcdctl --endpoints=${ENDPOINTS} role add role0
etcdctl --endpoints=${ENDPOINTS} role grant-permission role0 readwrite foo
etcdctl --endpoints=${ENDPOINTS} user add user0
etcdctl --endpoints=${ENDPOINTS} user grant-role user0 role0

etcdctl --endpoints=${ENDPOINTS} auth enable
# now all client requests go through auth

etcdctl --endpoints=${ENDPOINTS} --user=user0:123 put foo bar
etcdctl --endpoints=${ENDPOINTS} get foo
# permission denied, user name is empty because the request does not issue an authentication request
etcdctl --endpoints=${ENDPOINTS} --user=user0:123 get foo
# user0 can read the key foo
etcdctl --endpoints=${ENDPOINTS} --user=user0:123 get foo1

4 - バグの報告

etcdプロジェクトに問題を報告する方法

etcdプロジェクトのいずれかの部分にバグやドキュメントの誤りを見つけた場合は、Issueを作成 してお知らせください。私たちはバグや誤りを真剣に受け止めており、小さすぎて報告する必要のない問題はないと考えています。バグを報告する前に、同じ問題を報告するIssueがすでに存在していないか確認してください。

バグ報告を正確で理解しやすいものにするため、次の点を満たすようにしてください。

  • 具体的であること。バージョン、環境、構成など、できるだけ多くの詳細を含めてください。etcdサーバーの実行に関するバグの場合は、etcdのログを添付してください（etcdの構成が記録された起動時のログは特に重要です）。

  • 再現可能であること。問題を再現する手順を含めてください。再現が難しい問題もあることは承知していますので、問題につながる可能性のある手順を記載してください。可能であれば、影響を受けたetcdのデータディレクトリとスタックトレースをバグ報告に添付してください。

  • 問題が切り分けられていること。できる限り依存関係を最小限にして、バグを切り分け、再現してください。バグ報告に多すぎる依存関係が含まれていると、修正に大幅に時間がかかります。etcdに依存する外部システムのデバッグは対象外ですが、適切な方向性についての助言やetcd自体の使用方法については、喜んで支援します。

  • 重複していないこと。既存のバグ報告と重複する報告はしないでください。

  • 範囲が限定されていること。1つの報告につきバグは1つとしてください。同じ報告の中で、別のバグについて追記しないでください。

バグを報告する前に、適切なバグ報告の書き方に関するElika Etemadの記事 を読むと役立つかもしれません。

バグの原因を特定するため、追加の情報をお願いする場合があります。重複したバグ報告はクローズします。

よくある質問

スタックトレースの取得方法

$ kill -QUIT $PID

etcdのバージョンの確認方法

$ etcd --version

systemdサービス「etcd2.service」として実行されるetcdの構成とログを取得する方法

$ sudo systemctl cat etcd2
$ sudo journalctl -u etcd2

アップストリームのsystemdのバグにより、プロセスの終了時にjournaldがログの最後の数行を記録しない場合があります。journalctlでetcdが停止したと表示されるのにfatalまたはpanicメッセージがない場合は、sudo journalctl -f -t etcd2を試して完全なログを取得してください。

5 - 内部実装

etcdコントリビューター向けのディスカバリー、ログ、Goモジュールの規約。

5.1 - ログの規約

ログレベルの分類

etcdはzap ライブラリーを使用し、アプリケーションの出力をレベル別に分類してログに記録します。ログメッセージのレベルは、次の規約に従って決まります。

  • DebugLevelのログは通常、大量に出力されるため、本番環境では一般に無効にします。

    • 例：
      • リモートピアへの通常のメッセージの送信
      • ディスクへのログエントリーの書き込み

  • InfoLevelは、デフォルトのログ優先度です。

    • 例：
      • 起動時の構成
      • スナップショット作成の開始
      • クラスターへの新しいノードの追加
      • 認証サブシステムへの新しいユーザーの追加

  • WarnLevelのログはInfoより重要ですが、人が個別に確認する必要はありません。

    • 例：
      • リモートピアへのRaftメッセージの送信失敗
      • 設定された選出タイムアウト内でのハートビートメッセージの受信失敗

  • ErrorLevelのログは優先度が高いログです。アプリケーションが正常に動作している場合、エラーレベルのログは出力されないはずです。

    • 例：
      • WAL用のディスク領域の割り当て失敗

  • PanicLevelはメッセージをログに記録した後、パニックを発生させます。

    • 例：
      • Raftメッセージのエンコード失敗

  • FatalLevelはメッセージをログに記録した後、os.Exit(1)を呼び出します。

    • 例：
      • Raftスナップショットの保存失敗

6 - 学習

学習リソース

7 - 開発者ガイド

開発者向けのetcdガイド

7.1 - Goアプリケーションへのetcdの組み込み

etcdのGoパッケージembedを使用して、アプリケーション内でetcdサーバーを実行する

etcdのGoパッケージembedを使用すると、etcdサーバーをアプリケーションに直接、簡単に組み込めます。

詳細はembedパッケージのドキュメント を参照してください。

7.2 - システムの制限

etcdの制限：リクエストとストレージ

リクエストサイズの上限

etcdは、メタデータで一般的な小さなキー・バリューペアを処理するように設計されています。大きなリクエストも処理できますが、他のリクエストのレイテンシーが増加する可能性があります。デフォルトでは、各リクエストの最大サイズは1.5 MiBです。この上限は、etcdサーバーの--max-request-bytesフラグで設定できます。

ストレージサイズの上限

ストレージサイズのデフォルトの上限は2 GiBで、--quota-backend-bytesフラグで設定できます。通常の環境で推奨される最大サイズは8 GiBです。設定値がこのサイズを超えると、etcdは起動時に警告を出します。

8 - 運用ガイド

etcdのインストール、保守、トラブルシューティングのガイド

8.1 - 認証ガイド

etcdの認証とロールベースのアクセス制御のガイド

8.1.1 - 認証

etcdクラスターの認証に関するガイド

認証に使用するauth、user、role：

export ETCDCTL_API=3
ENDPOINTS=localhost:2379

etcdctl --endpoints=${ENDPOINTS} role add root
etcdctl --endpoints=${ENDPOINTS} role get root

etcdctl --endpoints=${ENDPOINTS} user add root
etcdctl --endpoints=${ENDPOINTS} user grant-role root root
etcdctl --endpoints=${ENDPOINTS} user get root

etcdctl --endpoints=${ENDPOINTS} role add role0
etcdctl --endpoints=${ENDPOINTS} role grant-permission role0 readwrite foo
etcdctl --endpoints=${ENDPOINTS} user add user0
etcdctl --endpoints=${ENDPOINTS} user grant-role user0 role0

etcdctl --endpoints=${ENDPOINTS} auth enable
# now all client requests go through auth

etcdctl --endpoints=${ENDPOINTS} --user=user0:123 put foo bar
etcdctl --endpoints=${ENDPOINTS} get foo
# permission denied, user name is empty because the request does not issue an authentication request
etcdctl --endpoints=${ENDPOINTS} --user=user0:123 get foo
# user0 can read the key foo
etcdctl --endpoints=${ENDPOINTS} --user=user0:123 get foo1

注意：

これは、認証に関する情報を追加して更新する必要がある未完成のページです。上記のテキストはコード例にすぎません。

8.2 - バージョン管理

etcdでサポートされるバージョン

このドキュメントでは、etcdプロジェクトでサポートされるバージョンについて説明します。

サービスのバージョン管理とサポート対象バージョン

etcdのバージョンは、セマンティックバージョニング の用語に従い、x.y.zと表記します。xはメジャーバージョン、yはマイナーバージョン、zはパッチバージョンです。新しいマイナーバージョンでは、APIに機能が追加される場合があります。

etcdプロジェクトでは、現行バージョンとその前のリリースのリリースブランチを保守します。たとえば、v3.5が現行バージョンの場合、v3.4もサポートされます。v3.6がリリースされると、v3.4のサポートは終了します。

セキュリティー修正を含む適用可能な修正は、重大度と実現可能性に応じて、これら2つのリリースブランチにバックポートされる場合があります。必要に応じて、これらのブランチからパッチリリースを作成します。

この判断は、プロジェクトのメンテナー が行います。

稼働中のetcdクラスターのバージョンは、etcdctlで確認できます。

etcdctl --endpoints=127.0.0.1:2379 endpoint status

APIのバージョン管理

v3 APIのレスポンスは、3.0.0リリース以降は変更されない想定ですが、新機能は今後も追加されます。

9 - ベンチマーク

etcdの性能測定

ベンチマーク

etcdのベンチマークは定期的に公開され、以下の各リリースについて追跡されます。

メモリー使用量のベンチマーク

さまざまなシナリオで想定されるメモリー使用量を記録します。

9.1 - etcd v3のベンチマーク

etcd v3の性能測定

物理マシン

GCE n1-highcpu-2マシンタイプ

  • /var/lib/etcdにマウントした専用ローカルSSD × 1
  • OS用の専用低速ディスク × 1
  • メモリー1.8 GB
  • CPU × 2
  • etcdバージョン2.2.0

etcd クラスター

v3デモモードで稼働するetcdメンバー1つ

テスト

etcd v3ベンチマークツール を使用します。

性能

単一キーの読み取り

キーサイズ（バイト）クライアント数読み取りQPS90パーセンタイルのレイテンシー（ms）
256127160.4
25664166236.1
2562561662221.7

空のサーバーハンドラーを使用した場合と、ほぼ同じ性能です。

書き込み後の単一キーの読み取り

キーサイズ（バイト）クライアント数読み取りQPS90パーセンタイルのレイテンシー（ms）
256122690.5
25664135828.6
2562561326247.5

空のサーバーハンドラーを使用した場合、1回のputによって性能は変わりません。したがって、性能低下の原因はストレージパッケージにあると考えられます。

9.2 - etcd v2.2.0-rc-memoryのベンチマーク

etcd v2.2.0-rc-memoryの性能測定

物理マシン

GCE n1-standard-2マシンタイプ

  • /var/lib/etcdにマウントした専用ローカルSSD × 1
  • OS用の専用低速ディスク × 1
  • メモリー7.5 GB
  • CPU × 2

etcd

etcd Version: 2.2.0-rc.0+git
Git SHA: 103cb5c
Go Version: go1.5
Go OS/Arch: linux/amd64

テスト

各メンバーが2コアを使用する3メンバーのetcdクラスターを起動します。

キー名の長さは常に64バイトとします。これは、キーの平均的なバイト長として妥当な長さです。

最大メモリー使用量

  • フォロワーの1つが停止し、リーダーがスナップショットを送信し続けると、etcdのメモリー使用量が最大になる場合があります。
  • max RSSは、3回の実行で記録された最大メモリー使用量です。
値のバイト数キー数データサイズ（MB）最大RSS（MB）リーダーの最大RSSとデータサイズの比率
12850000643372x
1281000001265954x
12820000024146661x
10245000048125326x
102410000096234424x
1024200000192436122x

データサイズのしきい値

  • etcdのデータサイズがしきい値に達すると、リーダー選出が起こりやすくなり、提案の一部が破棄される場合があります。
  • ほとんどの場合、しきい値に達していなければetcdクラスターは問題なく動作するはずです。リソース不足によって正常に動作しない場合は、データサイズを減らしてください。
値のバイト数キー数の上限推奨データサイズしきい値（MB）使用RSS（MB）
128400K482400
1024300K2926500

10 - アップグレード

etcdクラスターとアプリケーションのアップグレード

10.1 - etcdクラスターとアプリケーションのアップグレード

etcdクラスターとアプリケーションのアップグレードに関するドキュメント一覧

このセクションには、etcdクラスターとアプリケーションのアップグレードに関するドキュメントをまとめています。

アップグレード方針

アップグレードを始める前に、etcdでサポートされるアップグレードは次の2つの場合だけであることに注意してください。

  • パッチアップグレード： 同じマイナーバージョン内でのパッチリリース間のアップグレードです（例：3.7.0 - 3.7.1）。
  • マイナーアップグレード： マイナーバージョンを1つずつ上げるアップグレードです（例：3.6 - 3.7）。マイナーバージョンを飛ばすアップグレードはサポートされず、失敗する可能性が高くなります。次のマイナーバージョンにアップグレードする前に、最新のパッチバージョンに更新してください。

etcd v3.xクラスターのアップグレード

etcd v2.3からのアップグレード

11 - ダウングレード

etcdクラスターとアプリケーションのダウングレード

11.1 - etcdクラスターとアプリケーションのダウングレード

etcdクラスターとアプリケーションのダウングレードに関するドキュメント一覧

このセクションには、etcdクラスターとアプリケーションのダウングレードに関するドキュメントをまとめています。

etcd v3.xクラスターのダウングレード

12 - トリアージ

etcdの変更管理

12.1 - PRの管理

etcdのプルリクエストを管理するためのガイドライン

目的

PRの管理を迅速にすること。

etcdのPRはhttps://github.com/etcd-io/etcd/pullsに一覧表示されています。 PRにはさまざまなラベル、マイルストーン、レビュアーなどを設定できます。ラベルの詳細な一覧は、次のページを参照してください。 https://github.com/kubernetes/kubernetes/labels

便利なPR検索の例を以下に示します。

対象範囲

このガイドラインは、etcdでPRを管理する際の基本となるドキュメントです。PRの管理への協力はどなたでも歓迎しますが、このドキュメントで扱う作業と責任は、etcdのメンテナーと積極的に活動するコントリビューターを想定しています。

動きのないPRへの対応

レビューコメントに15日間対応がない場合は、PRの作成者に確認を促してください。PRの作成者から90日間返信がない場合は、可能であれば新しいコミットでPRを更新してください。それができなければ、動きのないPRは180日後にクローズするべきです。

必要に応じてレビュアーに確認を促す

レビュアーは適時に応答していますが、全員が忙しいことを考慮し、レビューを依頼してすぐに応答がなくても、しばらく待ってください。10日間応答がなければ、PRへのコメントの追加、メールの送信、Slackでのメッセージ送信によって連絡して構いません。

重要なラベルが付いていることを確認する

PRに適切なレビュアーが追加されていることを確認してください。また、マイルストーンが指定されていることも確認してください。これらの項目やその他の重要なラベルが不足していれば追加してください。適切なラベルを判断できない場合は、必要に応じてメンテナーに対応を依頼するコメントを残してください。