etcdクラスタ

This is the documentation for etcd2 releases. Read etcd3 doc for etcd3 releases.
クラスタガイド
概観
静的にetcdクラスタを起動するには、各メンバーがクラスタ内の別のメンバーを知っている必要があります.多くの場合、クラスタメンバーのIPは不明である可能性があります.これらの場合、etcdクラスタは、サービスの発見の助けを得て起動することができる.
etcdクラスタが起動して実行するとruntime reconfiguration.メンバーを追加または削除します.実行時の再構成の設計をよりよく理解するために、the runtime configuration design documentを読むことをお勧めします.
このガイドでは、etcdクラスタを起動するメカニズムについて説明します.

静的

etcd発見

DNS発見

各ブートメカニズムは、次の詳細を含む3台のマシンのetcdクラスタを作成するために使用されます.
名前
アドレス
ホスト名
infra0
10.0.1.10
infra0.example.com
infra1
10.0.1.11
infra1.example.com
infra2
10.0.1.12
infra2.example.com
静的
起動前にクラスタメンバー、クラスタアドレス、クラスタサイズを知っているように、initial-clusterフラグを設定することで、オフラインブート構成を使用することができます.各マシンは、次の環境変数またはコマンドラインを取得します.

ETCD_INITIAL_CLUSTER="infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380"
ETCD_INITIAL_CLUSTER_STATE=new

--initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380 \
--initial-cluster-state new

ここで指定されたURL initial-clusterは、initial-advertise-peer-urlsの各ノードの値に一致するように通知されたピアURLであることに注意してください.
テストの目的で複数のクラスタを回転させる(または単一のクラスタを作成して破棄する)場合は、initial-cluster-tokenで異なるクラスタに一意のクラスタを指定することを強くお勧めします.これにより、etcdは、完全に同じ構成を有していても、クラスタに一意のクラスタIDおよびメンバーIDを生成することができる.これにより、クラスタを破壊する可能性のあるクラスタ間のインタラクションから保護できます.
etcdリスニングlisten-client-urlsは、クライアントトラフィックを受信する.etcdメンバーは、指定されたURL広告advertise-client-urlsを他のメンバー、エージェント、クライアントに渡す.advertise-client-urlsが予想されるお客様から到着できることを確認してください.一般的なエラーは、advertise-client-urlsをlocalhostに設定するか、リモートクライアントがetcdに到達するようにデフォルト値として保持するかです.
各マシンでは、これらのフラグを使用してetcdを起動できます.

$ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \
  --listen-peer-urls http://10.0.1.10:2380 \
  --listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \
  --advertise-client-urls http://10.0.1.10:2379 \
  --initial-cluster-token etcd-cluster-1 \
  --initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380 \
  --initial-cluster-state new

$ etcd --name infra1 --initial-advertise-peer-urls http://10.0.1.11:2380 \
  --listen-peer-urls http://10.0.1.11:2380 \
  --listen-client-urls http://10.0.1.11:2379,http://127.0.0.1:2379 \
  --advertise-client-urls http://10.0.1.11:2379 \
  --initial-cluster-token etcd-cluster-1 \
  --initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380 \
  --initial-cluster-state new

$ etcd --name infra2 --initial-advertise-peer-urls http://10.0.1.12:2380 \
  --listen-peer-urls http://10.0.1.12:2380 \
  --listen-client-urls http://10.0.1.12:2379,http://127.0.0.1:2379 \
  --advertise-client-urls http://10.0.1.12:2379 \
  --initial-cluster-token etcd-cluster-1 \
  --initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380 \
  --initial-cluster-state new

--initial-clusterは、後続のetcd実行中に、先頭のコマンドラインパラメータが無視される.ブートプロセスを開始すると、環境変数またはコマンドラインフラグを自由に削除できます.後で構成を変更する必要がある場合(たとえば、クラスタにメンバーを追加したり、クラスタからメンバーを削除したりする場合)、ランタイム構成ガイドを参照してください.
エラー・ケース
次の例では、新しいホストを列挙ノードのリストに含めていません.これが新しいクラスタである場合、ノードは初期クラスタメンバーリストに追加する必要があります.

$ etcd --name infra1 --initial-advertise-peer-urls http://10.0.1.11:2380 \
  --listen-peer-urls https://10.0.1.11:2380 \
  --listen-client-urls http://10.0.1.11:2379,http://127.0.0.1:2379 \
  --advertise-client-urls http://10.0.1.11:2379 \
  --initial-cluster infra0=http://10.0.1.10:2380 \
  --initial-cluster-state new
etcd: infra1 not listed in the initial cluster config
exit 1

この例では、クラスタリスト(10.0.1.10:2380)の列挙アドレスではなく、1つのノード(infra 0)を異なるアドレス(127.0.0.1:22380)にマッピングしようとした.このノードが複数のアドレスをリスニングする場合は、すべてのアドレスがinitial-cluster構成コマンドに反映される必要があります.

$ etcd --name infra0 --initial-advertise-peer-urls http://127.0.0.1:2380 \
  --listen-peer-urls http://10.0.1.10:2380 \
  --listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \
  --advertise-client-urls http://10.0.1.10:2379 \
  --initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380 \
  --initial-cluster-state=new
etcd: error setting up initial cluster: infra0 has different advertised URLs in the cluster and advertised peer URLs list
exit 1

異なるコンフィギュレーションセットを使用してピアデバイスを構成し、クラスタに参加しようとすると、クラスタIDが一致せず、etcdが終了します.

$ etcd --name infra3 --initial-advertise-peer-urls http://10.0.1.13:2380 \
  --listen-peer-urls http://10.0.1.13:2380 \
  --listen-client-urls http://10.0.1.13:2379,http://127.0.0.1:2379 \
  --advertise-client-urls http://10.0.1.13:2379 \
  --initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra3=http://10.0.1.13:2380 \
  --initial-cluster-state=new
etcd: conflicting cluster ID to the target cluster (c6ab534d07e8fcc4 != bc25ea2a74fb18b0). Exiting.
exit 1

検出
多くの場合、クラスタ・ピアのIPを事前に知らない可能性があります.これは、クラウドプロバイダまたはネットワークを使用してDHCPを使用する場合によく見られます.これらの場合、静的構成を指定するのではなく、既存のetcdクラスタを使用して新しいクラスタを起動できます.私たちはこの過程を「発見」と呼んでいます.
次の2つの方法があります.

etcd検出サービス

DNS SRVレコード

etcd検出
発見サービスプロトコルの設計をよりよく理解するために、それを読むことをお勧めします.
サイト発見の有効期間
URLは、一意のetcdクラスタを識別します.発見URLを繰り返し使用するのではなく、常に新しいクラスタの発見URLを作成する必要があります.
また,URLはクラスタの初期ブートにのみ使用できることが分かった.クラスタの実行後にクラスタメンバーシップを変更するには、実行時再構成ガイドを参照してください.
カスタムetcd検出サービス
Discoveryは、既存のクラスタを使用して独自に起動します.独自のetcdクラスタを使用する場合は、次のURLを作成できます.

$ curl -X PUT https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83/_config/size -d value=3

サイズキーをURLに設定すると、予想されるクラスタサイズ3の検出URLを作成できます.
発見サービスを使用してetcdクラスタを起動する回数が予想されるetcdメンバー数を超える場合、追加のetcdプロセスはデフォルトでプロキシサーバにロールバックされます.
この場合、使用するURLはhttps://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83 etcdメンバーであり、https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83の開始時にこのディレクトリを使用して登録されます.
各メンバーは、異なる名前フラグを指定する必要があります.Hostnameまたはmachine-idは良い選択です.または、重複した名前のために失敗することがわかります.
各メンバーの関連フラグでetcdを開始します.

$ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \
  --listen-peer-urls http://10.0.1.10:2380 \
  --listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \
  --advertise-client-urls http://10.0.1.10:2379 \
  --discovery https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83

$ etcd --name infra1 --initial-advertise-peer-urls http://10.0.1.11:2380 \
  --listen-peer-urls http://10.0.1.11:2380 \
  --listen-client-urls http://10.0.1.11:2379,http://127.0.0.1:2379 \
  --advertise-client-urls http://10.0.1.11:2379 \
  --discovery https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83

$ etcd --name infra2 --initial-advertise-peer-urls http://10.0.1.12:2380 \
  --listen-peer-urls http://10.0.1.12:2380 \
  --listen-client-urls http://10.0.1.12:2379,http://127.0.0.1:2379 \
  --advertise-client-urls http://10.0.1.12:2379 \
  --discovery https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83

これにより、各メンバーがカスタムetcdにサービス登録自体を発見し、すべてのマシン登録後にクラスタを開始します.
パブリックetcd検出サービス
既存のクラスタにアクセスできない場合は、管理する公開発見サービスdiscoveryを使用できます.etcd.io.次のように、「新規」エンドポイントを使用して、プライベート発見サイトを作成できます.

$ curl https://discovery.etcd.io/new?size=3
https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de

これにより、当初予想されたサイズが3つのメンバーのクラスタが作成されます.サイズを指定しない場合は、既定の3が使用されます.
発見サービスを使用してetcdクラスタを起動する回数が予想されるetcdメンバー数を超える場合、追加のetcdプロセスはデフォルトでプロキシサーバにロールバックされます.

ETCD_DISCOVERY=https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de

-discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de

各メンバーは、異なる名前フラグを指定する必要があります.Hostnameまたはmachine-idは良い選択です.または、重複した名前のために失敗することがわかります.
各メンバーの関連フラグでetcdを開始します.

$ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \
  --listen-peer-urls http://10.0.1.10:2380 \
  --listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \
  --advertise-client-urls http://10.0.1.10:2379 \
  --discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de

$ etcd --name infra1 --initial-advertise-peer-urls http://10.0.1.11:2380 \
  --listen-peer-urls http://10.0.1.11:2380 \
  --listen-client-urls http://10.0.1.11:2379,http://127.0.0.1:2379 \
  --advertise-client-urls http://10.0.1.11:2379 \
  --discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de

$ etcd --name infra2 --initial-advertise-peer-urls http://10.0.1.12:2380 \
  --listen-peer-urls http://10.0.1.12:2380 \
  --listen-client-urls http://10.0.1.12:2379,http://127.0.0.1:2379 \
  --advertise-client-urls http://10.0.1.12:2379 \
  --discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de

これにより、各メンバーは発見サービスに自分自身を登録し、すべてのメンバーが登録された後にクラスタを開始します.
環境変数ETCD_を使用できます.DISCOVERY_PROXYはetcdにHTTPエージェントを用いて発見サービスに接続させる.
エラーと警告の事例
サーバエラーの検出

$ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \
  --listen-peer-urls http://10.0.1.10:2380 \
  --listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \
  --advertise-client-urls http://10.0.1.10:2379 \
  --discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de
etcd: error: the cluster doesn’t have a size configuration value in https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de/_config
exit 1

ユーザエラー
このエラーは、クラスタに構成数のメンバーがすでに存在し、discovery-fallbackが明示的に無効になっていることが判明した場合に発生します.

$ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \
  --listen-peer-urls http://10.0.1.10:2380 \
  --listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \
  --advertise-client-urls http://10.0.1.10:2379 \
  --discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de \
  --discovery-fallback exit
etcd: discovery: cluster is full
exit 1

警告
これは無害な警告で、このコンピュータの発見URLが無視されることを通知します.

$ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \
  --listen-peer-urls http://10.0.1.10:2380 \
  --listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \
  --advertise-client-urls http://10.0.1.10:2379 \
  --discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de
etcdserver: discovery token ignored since a cluster has already been initialized. Valid log found at /var/lib/etcd

DNS検出
DNS SRV記録は発見機構として利用できる.-discovery-srvフラグは、SRVレコードを発見するDNSドメイン名を設定するために使用することができる.次のDNS SRVレコードをリストの順序で検索します.

_etcd-server-ssl._tcp.example.com

_etcd-server._tcp.example.com

もし_etcd-server-ssl._tcp.example.comは、etcdがSSLを介してブートプロセスを試みることを発見した.
クライアントがetcdクラスタを検出するのを支援するために、以下のDNS SRVレコードをリストされた順序で検索します.

_etcd-client._tcp.example.com

_etcd-client-ssl._tcp.example.com

もし_etcd-client-ssl._tcp.example.comは、クライアントがSSLを介してetcdクラスタと通信しようとすることを発見した.
この-discovery-srv-nameフラグは、発見中にクエリのSRV名に接尾辞も構成します.このフラグを使用して、同じドメインの複数のetcdクラスタを区別します.例えば、discovery-srv=exampleである.comおよび-discovery-srv-name=foo設定、次のDNS SRVクエリは次のとおりです.

_etcd-server-ssl-foo._tcp.example.com

_etcd-server-foo._tcp.example.com

DNS SRVレコードの作成

$ dig +noall +answer SRV _etcd-server._tcp.example.com
_etcd-server._tcp.example.com. 300 IN  SRV  0 0 2380 infra0.example.com.
_etcd-server._tcp.example.com. 300 IN  SRV  0 0 2380 infra1.example.com.
_etcd-server._tcp.example.com. 300 IN  SRV  0 0 2380 infra2.example.com.

$ dig +noall +answer SRV _etcd-client._tcp.example.com
_etcd-client._tcp.example.com. 300 IN SRV 0 0 2379 infra0.example.com.
_etcd-client._tcp.example.com. 300 IN SRV 0 0 2379 infra1.example.com.
_etcd-client._tcp.example.com. 300 IN SRV 0 0 2379 infra2.example.com.

$ dig +noall +answer infra0.example.com infra1.example.com infra2.example.com
infra0.example.com.  300  IN  A  10.0.1.10
infra1.example.com.  300  IN  A  10.0.1.11
infra2.example.com.  300  IN  A  10.0.1.12

DNSを使用してetcdクラスタを起動する
etcdクラスタメンバーはドメイン名またはIPアドレスを傍受することができ、ブートプロセスはDNS Aレコードを解析する.
解析されたアドレス--initial-advertise-peer-urlsは、SRVターゲットで解析されたアドレスの1つと一致する必要があります.etcdメンバーは、SRVレコードで定義されたクラスタに属するかどうかを決定するために、解析されたアドレスを読み出す.

$ etcd --name infra0 \
--discovery-srv example.com \
--initial-advertise-peer-urls http://infra0.example.com:2380 \
--initial-cluster-token etcd-cluster-1 \
--initial-cluster-state new \
--advertise-client-urls http://infra0.example.com:2379 \
--listen-client-urls http://infra0.example.com:2379 \
--listen-peer-urls http://infra0.example.com:2380

$ etcd --name infra1 \
--discovery-srv example.com \
--initial-advertise-peer-urls http://infra1.example.com:2380 \
--initial-cluster-token etcd-cluster-1 \
--initial-cluster-state new \
--advertise-client-urls http://infra1.example.com:2379 \
--listen-client-urls http://infra1.example.com:2379 \
--listen-peer-urls http://infra1.example.com:2380

$ etcd --name infra2 \
--discovery-srv example.com \
--initial-advertise-peer-urls http://infra2.example.com:2380 \
--initial-cluster-token etcd-cluster-1 \
--initial-cluster-state new \
--advertise-client-urls http://infra2.example.com:2379 \
--listen-client-urls http://infra2.example.com:2379 \
--listen-peer-urls http://infra2.example.com:2380

また、ドメイン名ではなくIPアドレスを使用してクラスタを起動することもできます.

$ etcd --name infra0 \
--discovery-srv example.com \
--initial-advertise-peer-urls http://10.0.1.10:2380 \
--initial-cluster-token etcd-cluster-1 \
--initial-cluster-state new \
--advertise-client-urls http://10.0.1.10:2379 \
--listen-client-urls http://10.0.1.10:2379 \
--listen-peer-urls http://10.0.1.10:2380

$ etcd --name infra1 \
--discovery-srv example.com \
--initial-advertise-peer-urls http://10.0.1.11:2380 \
--initial-cluster-token etcd-cluster-1 \
--initial-cluster-state new \
--advertise-client-urls http://10.0.1.11:2379 \
--listen-client-urls http://10.0.1.11:2379 \
--listen-peer-urls http://10.0.1.11:2380

$ etcd --name infra2 \
--discovery-srv example.com \
--initial-advertise-peer-urls http://10.0.1.12:2380 \
--initial-cluster-token etcd-cluster-1 \
--initial-cluster-state new \
--advertise-client-urls http://10.0.1.12:2379 \
--listen-client-urls http://10.0.1.12:2379 \
--listen-peer-urls http://10.0.1.12:2380

etcdエージェント構成
DNS SRVレコードは、プロキシ・モードで動作するetcdサーバのピア・リストを構成するためにも使用することができる.

$ etcd --proxy on --discovery-srv example.com

etcdクライアント構成
DNS SRVレコードはまた、クライアントがetcdクラスタを発見するのを助けるために使用することもできる.
公式etcd/クライアントはDNS発見をサポートしています.etcdctlは、--discovery-srvオプションを指定することによってDNS発見もサポートする.

$ etcdctl --discovery-srv example.com set foo bar

エラー・ケース
同様のエラーcannot find local etcd$name from SRV records.が表示される場合があります.これは、etcdメンバーがSRVレコードで定義されたクラスタから自分を見つけることができないことを意味します.解析されたアドレス--initial-advertise-peer-urlsは、SRVターゲットで解析されたアドレスの1つと一致する必要があります.
0.4～2.0+の移行ガイド
etcd 2.0では,複数のアドレスをリスニングし,複数のアドレスをパブリッシュする機能を導入した.複雑なネットワークがある場合、etcdの使用が容易になります.例えば、さまざまなクラウドプロバイダのプライベートネットワークやパブリックネットワークなどです.
この特性をより容易に理解するために、いくつかのフラグの名前を変更しましたが、古いフラグをサポートすることで、古いバージョンから新しいバージョンへの移行が容易になります.
Old Flag
New Flag
Migration Behavior
-peer-addr
--initial-advertise-peer-urls
If specified, peer-addr will be used as the only peer URL. Error if both flags specified.
-addr
--advertise-client-urls
If specified, addr will be used as the only client URL. Error if both flags specified.
-peer-bind-addr
--listen-peer-urls
If specified, peer-bind-addr will be used as the only peer bind URL. Error if both flags specified.
-bind-addr
--listen-client-urls
If specified, bind-addr will be used as the only client bind URL. Error if both flags specified.
-peers
none
Deprecated. The --initial-cluster flag provides a similar concept with different semantics. Please read this guide on cluster startup.
-peers-file
none
Deprecated. The --initial-cluster flag provides a similar concept with different semantics. Please read this guide on cluster startup.