序章
CoreOSを可能にするテクノロジーの1つは etcd
、グローバルに分散されたKey-Valueストア。 このサービスは、個々のCoreOSマシンがクラスターを形成するため、およびグローバルにアクセス可能なデータを格納するためのプラットフォームとして使用されます。
このガイドでは、 etcd
デーモンと etcdctl
ユーティリティとそれを制御するために使用できるHTTP/JSONAPI。
前提条件
このガイドに従うために、DigitalOceanでCoreOSクラスターをセットアップするためのガイドとしてCoreOSマシンのクラスターがあることを前提としています。 これにより、1つのクラスターに3台のサーバーが残ります。
- coreos-1
- coreos-2
- coreos-3
これらのマシンを稼働させたら、このガイドを続けることができます。
Etcdクラスター検出モデル
最も基本的なタスクの1つ etcd
は、個々のマシンをクラスターに編成する責任があります。 これは、CoreOSが起動されたときに、で指定された検出アドレスでチェックインすることによって行われます。 cloud-config
作成時に渡されるファイル。
CoreOSによって実行される検出サービスには、次のURLからアクセスできます。 https://discovery.etcd.io
. にアクセスすると、新しいトークンを取得できます。 /new
ページ。 そこで、マシンがコンパニオンノードを検出するために使用できるトークンを取得します。 次のようになります。
https://discovery.etcd.io/dcadc5d4d42328488ecdcd7afae5f57c
は、新しいクラスターごとに新しいトークンを提供する必要があります。 これには、同じIPアドレスを持つ可能性のあるノードを使用してクラスターを再構築する必要がある場合も含まれます。 The etcd
これによりインスタンスが混乱し、検出アドレスを再利用すると、クラスターを構築するために正しく機能しなくなります。
Webブラウザーで検出アドレスにアクセスすると、既知のマシンを説明するJSONオブジェクトが返されます。 最初に開始したとき、これにはノードがありません。
{"action":"get","node":{"key":"/_etcd/registry/dcadc5d4d42328488ecdcd7afae5f57c","dir":true,"modifiedIndex":102511104,"createdIndex":102511104}}
クラスタをブートストラップした後、ここで詳細情報を確認できます。
{"action":"get","node":{"key":"/_etcd/registry/1edee33e6b03e75d9428eacf0ff94fda","dir":true,"nodes":[{"key":"/_etcd/registry/1edee33e6b03e75d9428eacf0ff94fda/2ddbdb7c872b4bc59dd1969ac166501e","value":"http://10.132.252.38:7001","expiration":"2014-09-19T13:41:26.912303668Z","ttl":598881,"modifiedIndex":102453704,"createdIndex":102453704},{"key":"/_etcd/registry/1edee33e6b03e75d9428eacf0ff94fda/921a7241c31a499a97d43f785108b17c","value":"http://10.132.248.118:7001","expiration":"2014-09-19T13:41:29.602508981Z","ttl":598884,"modifiedIndex":102453736,"createdIndex":102453736},{"key":"/_etcd/registry/1edee33e6b03e75d9428eacf0ff94fda/27987f5eaac243f88ca6823b47012c5b","value":"http://10.132.248.121:7001","expiration":"2014-09-19T13:41:41.817958205Z","ttl":598896,"modifiedIndex":102453860,"createdIndex":102453860}],"modifiedIndex":101632353,"createdIndex":101632353}}
クラスタの検出URLを見つける必要がある場合は、メンバーである任意のマシンから見つけることができます。 この情報は、 /run
階層:
cat /run/systemd/system/etcd.service.d/20-cloudinit.conf
[Service]
Environment="ETCD_ADDR=10.132.248.118:4001"
Environment="ETCD_DISCOVERY=https://discovery.etcd.io/dcadc5d4d42328488ecdcd7afae5f57c"
Environment="ETCD_NAME=921a7241c31a499a97d43f785108b17c"
Environment="ETCD_PEER_ADDR=10.132.248.118:7001"
URLは内に保存されます ETCD_DISCOVERY
エントリ。
マシンが実行されているとき etcd
起動すると、このURLの情報を確認します。 それはそれ自身の情報を提出し、他のメンバーについて質問します。 クラスタの最初のノードは明らかに他のノードに関する情報を検出しないため、それ自体をクラスタリーダーとして指定します。
後続のマシンも、その情報を検出URLに接続します。 すでにチェックインしているマシンに関する情報を受け取ります。 次に、これらのマシンの1つを選択して直接接続し、正常なクラスターメンバーの完全なリストを取得します。 データの複製と配布は、Raftコンセンサスアルゴリズムを介して実行されます。
各マシンに関するデータは、内の隠しディレクトリ構造内に保存されます etcd
. あなたはそのマシンについての情報を見ることができます etcd
次のように入力して認識します。
etcdctl ls /_etcd/machines --recursive
/_etcd/machines/2ddbdb7c872b4bc59dd1969ac166501e
/_etcd/machines/921a7241c31a499a97d43f785108b17c
/_etcd/machines/27987f5eaac243f88ca6823b47012c5b
その詳細 etcd
新しいクラスターメンバーへのパスは、これらのキーに含まれています。 あなたはそれらを要求することによって個々の値を見ることができます etcdctl
:
etcdctl get /_etcd/machines/2ddbdb7c872b4bc59dd1969ac166501e
etcd=http%3A%2F%2F10.132.252.38%3A4001&raft=http%3A%2F%2F10.132.252.38%3A7001
私たちは行きます etcdctl
コマンドについては後で詳しく説明します。
Etcdctlの使用法
と対話する2つの基本的な方法があります etcd
. HTTP / JSON APIを介して、および含まれているようなクライアントを介して etcdctl
効用。 行きます etcdctl
最初。
キーとディレクトリの表示
始めに、何を見てみましょう etcdctl
現在保存中です。 次のように入力すると、最上位のキーが表示されます。
etcdctl ls /
/coreos.com
ご覧のとおり、1つの結果があります。 現時点では、これがディレクトリなのかキーなのかは不明です。 私たちは試みることができます get
キーの値を確認するか、それがディレクトリであることを確認するノード:
etcdctl get /coreos.com
/coreos.com: is a directory
この手動の再帰的プロセスを回避するために、次のことができます。 etcdctl
次のように入力して、表示される情報の階層全体を一覧表示します。
etcdctl ls / --recursive
/coreos.com
/coreos.com/updateengine
/coreos.com/updateengine/rebootlock
/coreos.com/updateengine/rebootlock/semaphore
ご覧のとおり、最初のディレクトリの下にはかなりの数のディレクトリがありました /coreos.com
ノード。 最終エンドポイントで情報を要求することにより、ノードから実際のデータを取得することがどのように見えるかを確認できます。
etcdctl get /coreos.com/updateengine/rebootlock/semaphore
{"semaphore":1,"max":1,"holders":null}
これには、私たちにとって非常に役立つ情報は含まれていません。 このエントリに関する追加のメタデータを取得するには、 -o extended
オプション。 これはグローバルオプションであるため、 get
指図:
etcdctl -o extended get /coreos.com/updateengine/rebootlock/semaphore
Key: /coreos.com/updateengine/rebootlock/semaphore
Created-Index: 6
Modified-Index: 6
TTL: 0
Etcd-Index: 170387
Raft-Index: 444099
Raft-Term: 8
{"semaphore":1,"max":1,"holders":null}
キーの設定とノードの作成
新しいディレクトリを作成するには、 mkdir
そのようなコマンド:
etcdctl mkdir /example
キーを作成するには、 mk
指図:
etcdctl mk /example/key data
data
これは、キーがまだ存在しない場合にのみ機能します。 作成したキーの値を尋ねると、設定したデータを取得できます。
etcdctl get /example/key
data
既存のキーを更新するには、 update
指図:
etcdctl update /example/key turtles
turtles
コンパニオン updatedir
ディレクトリのコマンドは、TTLまたはディレクトリの存続時間を設定している場合にのみ役立つ可能性があります。 これにより、TTL時間が渡されたもので更新されます。 ディレクトリまたはキーのTTLを設定するには、 --ttl #
引数。ここで、「#」は保持する秒数です。
etcdctl mkdir /here/you/go --ttl 120
その後、TTLを更新できます updatedir
:
etcdctl updatedir /here/you/go --ttl 500
既存のキーの値を変更するには、またはキーが存在しない場合はキーを作成するには、 set
指図。 これをの組み合わせと考えてください mk
と update
指図:
etcdctl set /example/key new
new
これには、存在しないパスが含まれる場合があります。 パスコンポーネントは動的に作成されます。
etcdctl set /a/b/c here
here
ディレクトリに対してこれと同じcreate-if-does-not-exist機能を取得するには、 setdir
指図:
etcdctl setdir /x/y/z
注: setdir
コマンドは現在、記載されているように機能しません。 現在のビルドでは、その使用法は updatedir
コマンドであり、ディレクトリがすでに存在する場合は失敗します。 これに対処するために、GitHubリポジトリに未解決の問題があります。
エントリの削除
既存のキーを削除するには、 rm
また rmdir
指図。
The rm
コマンドを使用してキーを削除できます。
etcdctl rm /a/b/c
また、ディレクトリとすべてのサブディレクトリを削除するために再帰的に使用することもできます。
etcdctl rm /a --recursive
空のディレクトリまたはキーのみを削除するには、 rmdir
指図:
etcdctl rmdir /x/y/z
これを使用して、階層のエンドポイントのみを削除していることを確認できます。
変化を監視する
特定のキーまたはディレクトリ全体のいずれかで変更を監視できます。 これらを見て etcdctl
監視されているものに何らかのイベントが発生するまで、操作がハングします。
キーを監視するには、フラグなしで使用します。
etcdctl watch /example/hello
視聴を停止するには、を押すことができます CTRL-C
. 監視中に変更が検出された場合は、新しい値が返されます。
ディレクトリ構造全体を監視するには、 --recursive
国旗:
etcdctl watch --recursive /example
値の状態を常に監視するために単純なループ構造に配置することで、これがどのように役立つかを確認できます。
while true; do etcdctl watch --recursive /example; done
変更が検出されるたびにコマンドを実行する場合は、 exec-watch
指図:
etcdctl exec-watch --recursive /example -- echo "hello"
これにより、そのディレクトリの値が変更されるたびに、画面に「hello」がエコーされます。
隠された値
すぐにはわからないことの1つは、内部に隠しディレクトリ構造があることです。 etcd
. これらは、アンダースコアで始まるディレクトリまたはキーです。
これらは従来のリストにはありません etcdctl
ツールとあなたはそれらを見つけるためにあなたが探しているものを知っている必要があります。
たとえば、という隠しディレクトリがあります /_coreos.com
に関するいくつかの内部情報を保持します fleet
. 明示的に要求することで、階層を確認できます。
etcdctl ls --recursive /_coreos.com
/_coreos.com/fleet
/_coreos.com/fleet/states
/_coreos.com/fleet/states/apache@6666.service
/_coreos.com/fleet/states/apache@6666.service/2ddbdb7c872b4bc59dd1969ac166501e
/_coreos.com/fleet/states/apache@7777.service
/_coreos.com/fleet/states/apache@7777.service/921a7241c31a499a97d43f785108b17c
. . .
別のそのようなディレクトリ構造は、 /_etcd
:
etcdctl ls --recursive /_etcd
/_etcd/machines
/_etcd/machines/27987f5eaac243f88ca6823b47012c5b
/_etcd/machines/2ddbdb7c872b4bc59dd1969ac166501e
/_etcd/machines/921a7241c31a499a97d43f785108b17c
/_etcd/config
これらは他のエントリとまったく同じように機能しますが、唯一の違いは、一般的なリストに表示されないことです。 キーまたはディレクトリ名をアンダースコアで始めるだけで作成できます。
Etcd HTTP /JSONAPIの使用法
と対話する別の方法 etcd
単純なHTTP/JSONAPIを使用します。
APIにアクセスするには、次のような単純なHTTPプログラムを使用できます。 curl
. あなたは供給しなければなりません -L
返されるリダイレクトを追跡するためのフラグ。 クラスタ内から、ローカルを使用できます 127.0.0.1
インターフェイスとポート 4001
ほとんどのクエリで。
注:に接続するには etcd
Dockerコンテナ内から、アドレス http://172.17.42.1:4001
に使える。 これは、アプリケーションが登録された情報に基づいて構成を更新する場合に役立ちます。
通常のキースペースには、次のURLにアクセスしてアクセスできます。 http://127.0.0.1:4001/v2/keys/
いずれかのホストマシン上。 たとえば、最上位のキー/ディレクトリのリストを取得するには、次のように入力します。
curl -L http://127.0.0.1:4001/v2/keys/
{"action":"get","node":{"key":"/","dir":true,"nodes":[{"key":"/coreos.com","dir":true,"modifiedIndex":6,"createdIndex":6},{"key":"/services","dir":true,"modifiedIndex":333,"createdIndex":333}]}}
リクエストの末尾のスラッシュは必須です。 それがないと正しく解決されません。
通常のHTTP動詞を使用して値を設定または取得できます。
これらの操作の動作を変更するには、リクエストの最後に、を使用してフラグを渡すことができます。 ?flag=value
構文。 複数のフラグは、 &
キャラクター。
たとえば、すべてのキーを再帰的に一覧表示するには、次のように入力します。
curl -L http://127.0.0.1:4001/v2/keys/?recursive=true
{"action":"get","node":{"key":"/","dir":true,"nodes":[{"key":"/coreos.com","dir":true,"nodes":[{"key":"/coreos.com/updateengine","dir":true,"nodes":[{"key":"/coreos.com/updateengine/rebootlock","dir":true,"nodes":[{"key":"/coreos.com/updateengine/rebootlock/semaphore","value":"{\"semaphore\":1,\"max\":1,\"holders\":null}","modifiedIndex":6,"createdIndex":6}],"modifiedIndex":6,"createdIndex":6}],"modifiedIndex":6,"createdIndex":6}],"modifiedIndex":6,"createdIndex":6}. . .
通常のキースペースの外でアクセスできるもう1つの便利な情報は、バージョン情報です。ここからアクセスできます。
curl -L http://127.0.0.1:4001/version
etcd 0.4.6
このエンドポイントにアクセスすると、クラスターリーダーと各フォロワーとの各関係に関する統計を表示できます。
curl -L http://127.0.0.1:4001/v2/stats/leader
{"leader":"921a7241c31a499a97d43f785108b17c","followers":{"27987f5eaac243f88ca6823b47012c5b":{"latency":{"current":1.607038,"average":1.3762888642395448,"standardDeviation":1.4404313533578545,"minimum":0.471432,"maximum":322.728852},"counts":{"fail":0,"success":98718}},"2ddbdb7c872b4bc59dd1969ac166501e":{"latency":{"current":1.584985,"average":1.1554367141497013,"standardDeviation":0.6872303198242179,"minimum":0.427485,"maximum":31.959235},"counts":{"fail":0,"success":98723}}}}
同様の操作を使用して、現在使用しているマシンに関する統計を検出できます。
curl -L http://127.0.0.1:4001/v2/stats/self
{"name":"921a7241c31a499a97d43f785108b17c","state":"leader","startTime":"2014-09-11T16:42:03.035382298Z","leaderInfo":{"leader":"921a7241c31a499a97d43f785108b17c","uptime":"1h19m11.469872568s","startTime":"2014-09-12T19:47:25.242151859Z"},"recvAppendRequestCnt":1944480,"sendAppendRequestCnt":201817,"sendPkgRate":40.403374523779064,"sendBandwidthRate":3315.096879676072}
実行された操作に関する統計を表示するには、次のように入力します。
curl -L http://127.0.0.1:4001/v2/stats/store
{"getsSuccess":78823,"getsFail":14,"setsSuccess":121370,"setsFail":4,"deleteSuccess":28,"deleteFail":32,"updateSuccess":20468,"updateFail":4,"createSuccess":39,"createFail":102340,"compareAndSwapSuccess":51169,"compareAndSwapFail":0,"compareAndDeleteSuccess":0,"compareAndDeleteFail":0,"expireCount":3,"watchers":6}
これらは、制御に使用できる操作のほんの一部です。 etcd
APIを介して。
Etcd構成
The etcd
サービスは、いくつかの異なる方法で構成できます。
最初の方法は、パラメータを渡すことです cloud-config
ノードのブートストラップに使用するファイル。 ブートストラップガイドでは、これを行う方法について少し見ました。
#cloud-config
coreos:
etcd:
discovery: https://discovery.etcd.io/<token>
addr: $private_ipv4:4001
peer-addr: $private_ipv4:7001
. . .
利用可能なオプションを確認するには、 -h
フラグ etcd
:
etcd -h
これらのオプションを cloud-config
、単に先頭のダッシュを外し、等号の代わりにコロンを使用して値からキーを区切ります。 そう -peer-addr=<host:port>
になります peer-addr: <host:port>
.
読んだら cloud-config
ファイルの場合、CoreOSはこれらをスタブユニットファイルの環境変数に変換します。このファイルはサービスの開始に使用されます。
の設定を調整する別の方法 etcd
APIを介してです。 これは通常、 7001
標準の代わりにポート 4001
これはキークエリに使用されます。
たとえば、次のように入力すると、現在の構成値の一部を取得できます。
curl -L http://127.0.0.1:7001/v2/admin/config
{"activeSize":9,"removeDelay":1800,"syncInterval":5}
これらの値を変更するには、PUT操作で新しいJSONをデータペイロードとして渡します。
curl -L http://127.0.0.1:7001/v2/admin/config -XPUT -d '{"activeSize":9,"removeDelay":1800,"syncInterval":5}'
{"activeSize":9,"removeDelay":1800,"syncInterval":5}
マシンのリストを取得するには、 /v2/admin/machines
終点:
curl -L http://127.0.0.1:7001/v2/admin/machines
[{"name":"27987f5eaac243f88ca6823b47012c5b","state":"follower","clientURL":"http://10.132.248.121:4001","peerURL":"http://10.132.248.121:7001"},{"name":"2ddbdb7c872b4bc59dd1969ac166501e","state":"follower","clientURL":"http://10.132.252.38:4001","peerURL":"http://10.132.252.38:7001"},{"name":"921a7241c31a499a97d43f785108b17c","state":"leader","clientURL":"http://10.132.248.118:4001","peerURL":"http://10.132.248.118:7001"}]
これは、DELETEメソッドを使用してクラスターからマシンを強制的に削除するために使用できます。
結論
ご覧のように、 etcd
クラスタ内の任意のマシンから情報を保存または取得するために使用できます。 これにより、データを同期し、サービスが構成データと接続の詳細を検索する場所を提供できます。
これは、クラスター内の任意の場所から有効になる単純なエンドポイントを提供できるため、分散システムを構築するときに特に役立ちます。 このリソースを利用することで、サービスは動的に構成できます。