Verwendung von Etcdctl und Etcd, dem Distributed Key-Value Store von CoreOS

Einführung

Eine der Technologien, die CoreOS möglich machen, ist "+ etcd +", ein global verteilter Schlüsselwertspeicher. Dieser Dienst wird von den einzelnen CoreOS-Maschinen zur Bildung eines Clusters und als Plattform zum Speichern von global zugänglichen Daten verwendet.

In diesem Handbuch werden wir den Dämon "+ etcd " sowie das Dienstprogramm " etcdctl +" und die HTTP / JSON-API untersuchen, die zur Steuerung verwendet werden können.

Voraussetzungen

Wir gehen davon aus, dass Sie einen Cluster von CoreOS-Computern als Leitfaden unter https://www.digitalocean.com/community/tutorials/how-to-set-up-a-coreos-cluster-on haben -digitalocean [Einrichten eines CoreOS-Clusters auf DigitalOcean] Auf diese Weise verbleiben drei Server in einem einzigen Cluster:

Coreos-1
Coreos-2
Coreos-3

Sobald Sie diese Maschinen in Betrieb genommen haben, können Sie mit dieser Anleitung fortfahren.

Etcd Cluster Discovery Model

Eine der grundlegendsten Aufgaben, für die "+ etcd " verantwortlich ist, besteht darin, einzelne Maschinen in einem Cluster zu organisieren. Dies geschieht beim Booten von CoreOS durch Einchecken an der Erkennungsadresse, die in der Datei " cloud-config +" angegeben ist, die bei der Erstellung übergeben wird.

Der von CoreOS ausgeführte Discovery-Service ist unter "+ https: // discovery.etcd.io " verfügbar. Sie können einen neuen Token erhalten, indem Sie die Seite " / new +" besuchen. Dort erhalten Sie ein Token, mit dem Ihre Computer ihre Companion-Knoten ermitteln können. Es wird ungefähr so aussehen:

https://discovery.etcd.io/

Sie müssen für jeden neuen Cluster ein neues Token bereitstellen. Dies gilt auch, wenn Sie den Cluster mithilfe von Knoten neu erstellen müssen, die möglicherweise dieselbe IP-Adresse haben. Die + etcd + Instanzen werden dadurch verwirrt und funktionieren nicht richtig, um den Cluster zu erstellen, wenn Sie die Erkennungsadresse wiederverwenden.

Wenn Sie die Erkennungsadresse in Ihrem Webbrowser aufrufen, erhalten Sie ein JSON-Objekt zurück, das die bekannten Maschinen beschreibt. Dies hat beim ersten Start keine Knoten:

{"action":"get","node":{"key":"/_etcd/registry/dcadc5d4d42328488ecdcd7afae5f57c","dir":true,"modifiedIndex":102511104,"createdIndex":102511104}}

Nachdem Sie Ihren Cluster gebootet haben, können Sie hier weitere Informationen sehen:

{"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}}

Wenn Sie die Erkennungs-URL eines Clusters suchen müssen, können Sie dies von jedem der Computer aus tun, der Mitglied ist. Diese Informationen können aus der Hierarchie "+ / run +" abgerufen werden:

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"

Die URL wird im Eintrag "+ ETCD_DISCOVERY +" gespeichert.

Wenn die Maschinen, auf denen "+ etcd +" ausgeführt wird, hochfahren, überprüfen sie die Informationen unter dieser URL. Sie übermittelt ihre eigenen Informationen und fragt nach anderen Mitgliedern. Der erste Knoten im Cluster findet offensichtlich keine Informationen zu anderen Knoten, sodass er sich selbst als Cluster-Leader ausweist.

Die nachfolgenden Computer werden auch die Erkennungs-URL mit ihren Informationen kontaktieren. Sie erhalten Informationen über die bereits eingecheckten Maschinen zurück. Anschließend wählen sie einen dieser Computer aus und stellen eine direkte Verbindung her. Dort erhalten sie die vollständige Liste der fehlerfreien Cluster-Mitglieder. Die Replikation und Verteilung der Daten erfolgt über den Konsensusalgorithmus Raft.

Die Daten zu jeder Maschine werden in einer versteckten Verzeichnisstruktur in "+ etcd " gespeichert. Sie können die Informationen zu den Maschinen anzeigen, die " etcd +" kennt, indem Sie Folgendes eingeben:

etcdctl ls /_etcd/machines --recursive

/_etcd/machines/2ddbdb7c872b4bc59dd1969ac166501e
/_etcd/machines/921a7241c31a499a97d43f785108b17c
/_etcd/machines/27987f5eaac243f88ca6823b47012c5b

Die Details, die "+ etcd " an neue Clustermitglieder weitergeben, sind in diesen Schlüsseln enthalten. Sie können die einzelnen Werte anzeigen, indem Sie diese mit ` etcdctl +` anfordern:

etcdctl get /_etcd/machines/2ddbdb7c872b4bc59dd1969ac166501e

etcd=http%3A%2F%2F10.132.252.38%3A4001&raft=http%3A%2F%2F10.132.252.38%3A7001

Wir werden die Befehle "+ etcdctl +" später genauer betrachten.

Etcdctl Usage

Es gibt zwei grundlegende Arten der Interaktion mit "+ etcd ". Über die HTTP / JSON-API und über einen Client, wie das mitgelieferte Dienstprogramm " etcdctl ". Wir werden zuerst ` etcdctl +` durchgehen.

Anzeigen von Schlüsseln und Verzeichnissen

Schauen wir uns zunächst an, was "+ etcdctl +" gerade speichert. Wir können die Schlüssel der obersten Ebene sehen, indem wir Folgendes eingeben:

etcdctl ls /

/coreos.com

Wie Sie sehen, haben wir ein Ergebnis. Derzeit ist nicht klar, ob es sich um ein Verzeichnis oder einen Schlüssel handelt. Wir können versuchen, den Knoten zu "+ holen +", um entweder den Wert des Schlüssels zu sehen oder um zu sehen, ob es sich um ein Verzeichnis handelt:

etcdctl get /coreos.com

/coreos.com: is a directory

Um diesen manuellen rekursiven Prozess zu vermeiden, können wir + etcdctl + anweisen, die gesamte Hierarchie der sichtbaren Informationen aufzulisten, indem wir Folgendes eingeben:

etcdctl ls / --recursive

/coreos.com
/coreos.com/updateengine
/coreos.com/updateengine/rebootlock
/coreos.com/updateengine/rebootlock/semaphore

Wie Sie sehen, befanden sich unter dem ursprünglichen Knoten "+ / coreos.com +" einige Verzeichnisse. Wir können sehen, wie es aussieht, wenn tatsächliche Daten von einem Knoten abgerufen werden, indem wir am endgültigen Endpunkt nach den Informationen fragen:

etcdctl get /coreos.com/updateengine/rebootlock/semaphore

{"semaphore":1,"max":1,"holders":null}

Dies enthält keine Informationen, die für uns sehr nützlich sind. Wir können einige zusätzliche Metadaten zu diesem Eintrag abrufen, indem wir die Option "+ -o extended " übergeben. Dies ist eine globale Option, daher muss sie vor dem Befehl " get +" stehen:

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}

Festlegen von Schlüsseln und Erstellen von Knoten

Um ein neues Verzeichnis zu erstellen, können Sie den Befehl + mkdir + folgendermaßen verwenden:

etcdctl mkdir /example

Um einen Schlüssel zu erstellen, können Sie den Befehl + mk + verwenden:

etcdctl mk /example/key data

data

Dies funktioniert nur, wenn der Schlüssel noch nicht existiert. Wenn wir nach dem Wert des von uns erstellten Schlüssels fragen, können wir die von uns festgelegten Daten abrufen:

etcdctl get /example/key

data

Verwenden Sie den Befehl "+ update", um einen vorhandenen Schlüssel zu aktualisieren:

etcdctl update /example/key turtles

turtles

Der Companion-Befehl "+ updatedir " für Verzeichnisse ist wahrscheinlich nur nützlich, wenn Sie eine TTL oder die Lebensdauer eines Verzeichnisses festgelegt haben. Dadurch wird die TTL-Zeit mit der übergebenen aktualisiert. Sie können TTLs für Verzeichnisse oder Schlüssel festlegen, indem Sie das Argument " - ttl # +" übergeben, wobei "#" die Anzahl der Sekunden ist, die aufbewahrt werden sollen:

etcdctl mkdir /here/you/go --ttl 120

Sie können dann die TTL mit + updatedir + aktualisieren:

etcdctl updatedir /here/you/go --ttl 500

Verwenden Sie den Befehl + set +, um den Wert eines vorhandenen Schlüssels zu ändern oder einen Schlüssel zu erstellen, falls er nicht vorhanden ist. Stellen Sie sich dies als eine Kombination aus dem Befehl + k + und + update vor:

etcdctl set /example/key new

new

Dies kann nicht vorhandene Pfade einschließen. Die Pfadkomponenten werden dynamisch erstellt:

etcdctl set /a/b/c here

here

Mit dem Befehl + setdir + können Sie dieselbe Funktion zum Erstellen von Verzeichnissen erhalten, die es nicht gibt:

etcdctl setdir /x/y/z

Hinweis *: Der Befehl + setdir + funktioniert derzeit nicht wie angegeben. Im aktuellen Build spiegelt seine Verwendung den Befehl "+ updatedir +" wider und schlägt fehl, wenn das Verzeichnis bereits vorhanden ist. Es gibt ein offenes Problem im GitHub-Repository, um dieses Problem zu beheben.

Einträge entfernen

Um vorhandene Schlüssel zu entfernen, können Sie den Befehl + rm + oder + rmdir + verwenden.

Mit dem Befehl + rm + kann ein Schlüssel entfernt werden:

etcdctl rm /a/b/c

Es kann auch rekursiv verwendet werden, um ein Verzeichnis und jedes Unterverzeichnis zu entfernen:

etcdctl rm /a --recursive

Verwenden Sie den Befehl + rmdir +, um nur ein leeres Verzeichnis oder einen Schlüssel zu entfernen:

etcdctl rmdir /x/y/z

Auf diese Weise können Sie sicherstellen, dass Sie nur die Endpunkte der Hierarchien entfernen.

Auf Veränderungen achten

Sie können entweder einen bestimmten Schlüssel oder ein gesamtes Verzeichnis auf Änderungen überwachen. Wenn Sie diese mit + etcdctl + beobachten, bleibt der Vorgang hängen, bis ein Ereignis mit dem, was gerade beobachtet wird, eintritt.

Um einen Schlüssel zu sehen, verwenden Sie ihn ohne Flaggen:

etcdctl watch /example/hello

Um das Ansehen zu beenden, können Sie die Tastenkombination "+ STRG-C +" drücken. Wird während der Uhr eine Änderung festgestellt, wird der neue Wert zurückgegeben.

Verwenden Sie das Flag "+ - recursive +", um eine gesamte Verzeichnisstruktur zu überwachen:

etcdctl watch --recursive /example

Sie können sehen, wie nützlich dies wäre, wenn Sie es in ein einfaches Schleifenkonstrukt einfügen, um den Status der Werte ständig zu überwachen:

while true; do etcdctl watch --recursive /example; done

Wenn Sie einen Befehl ausführen möchten, sobald eine Änderung festgestellt wird, verwenden Sie den Befehl + exec-watch +:

etcdctl exec-watch --recursive  /example -- echo "hello"

Dies wird auf dem Bildschirm als „Hallo“ angezeigt, wenn sich ein Wert in diesem Verzeichnis ändert.

Versteckte Werte

Eine Sache, die nicht sofort offensichtlich ist, ist, dass es versteckte Verzeichnisstrukturen innerhalb von "+ etcd +" gibt. Dies sind Verzeichnisse oder Schlüssel, die mit einem Unterstrich beginnen.

Diese werden von den herkömmlichen + etcdctl + - Tools nicht aufgelistet und Sie müssen wissen, wonach Sie suchen, um sie zu finden.

Zum Beispiel gibt es ein verstecktes Verzeichnis mit dem Namen "+ / _coreos.com ", das einige interne Informationen über " fleet +" enthält. Sie können die Hierarchie anzeigen, indem Sie explizit danach fragen:

etcdctl ls --recursive /_coreos.com

/_coreos.com/fleet
/_coreos.com/fleet/states
/_coreos.com/fleet/states/[email protected]
/_coreos.com/fleet/states/[email protected]/2ddbdb7c872b4bc59dd1969ac166501e
/_coreos.com/fleet/states/[email protected]
/_coreos.com/fleet/states/[email protected]/921a7241c31a499a97d43f785108b17c
. . .

Eine weitere solche Verzeichnisstruktur befindet sich in + / _ etcd +:

etcdctl ls --recursive /_etcd

/_etcd/machines
/_etcd/machines/27987f5eaac243f88ca6823b47012c5b
/_etcd/machines/2ddbdb7c872b4bc59dd1969ac166501e
/_etcd/machines/921a7241c31a499a97d43f785108b17c
/_etcd/config

Diese funktionieren genauso wie alle anderen Einträge, mit dem einzigen Unterschied, dass sie nicht in allgemeinen Auflistungen angezeigt werden. Sie können sie erstellen, indem Sie einfach Ihren Schlüssel oder Verzeichnisnamen mit einem Unterstrich beginnen.

Usw. HTTP / JSON-API-Verwendung

Die andere Möglichkeit, mit "+ etcd +" zu interagieren, bietet die einfache HTTP / JSON-API.

Um auf die API zuzugreifen, können Sie ein einfaches HTTP-Programm wie + curl + verwenden. Sie müssen das "+ -L " - Flag angeben, um allen Weiterleitungen zu folgen, die zurückgegeben werden. Innerhalb Ihres Clusters können Sie für die meisten Abfragen die lokale Schnittstelle " 127.0.0.1 " und den Port " 4001 +" verwenden.

Hinweis *: Um innerhalb eines Docker-Containers eine Verbindung zu "+ etcd " herzustellen, kann die Adresse " http: //172.17.42.1: 4001 +" verwendet werden. Dies kann für Anwendungen nützlich sein, um ihre Konfigurationen basierend auf registrierten Informationen zu aktualisieren.

Sie erreichen den normalen Schlüsselbereich, indem Sie auf einem der Host-Computer zu "+ http: //127.0.0.1: 4001 / v2 / keys / +" wechseln. Geben Sie beispielsweise Folgendes ein, um eine Liste der Schlüssel / Verzeichnisse der obersten Ebene zu erhalten:

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}]}}

Der abschließende Schrägstrich in der Anforderung ist obligatorisch. Ohne wird es nicht richtig aufgelöst.

Sie können Werte mit normalen HTTP-Verben festlegen oder abrufen.

Um das Verhalten dieser Vorgänge zu ändern, können Sie am Ende Ihrer Anforderung Flags mit der Syntax +? Flag = value + übergeben. Mehrere Flags können durch ein "" und "" getrennt werden.

Um beispielsweise alle Schlüssel rekursiv aufzulisten, können Sie Folgendes eingeben:

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}. . .

Eine weitere nützliche Information, auf die außerhalb des normalen Schlüsselbereichs zugegriffen werden kann, sind die Versionsinformationen, die hier abgerufen werden können:

curl -L http://127.0.0.1:4001/version

etcd 0.4.6

Sie können Statistiken zu jeder Beziehung des Clusterleiters zu jedem Follower anzeigen, indem Sie diesen Endpunkt besuchen:

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}}}}

Ein ähnlicher Vorgang kann verwendet werden, um Statistiken zu dem Computer zu ermitteln, auf dem Sie sich gerade befinden:

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}

Geben Sie Folgendes ein, um Statistiken zu durchgeführten Vorgängen anzuzeigen:

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}

Dies sind nur einige der Operationen, die zur Steuerung von "+ etcd +" über die API verwendet werden können.

Usw. Konfiguration

Der "+ etcd +" - Dienst kann auf verschiedene Arten konfiguriert werden.

Der erste Weg ist die Übergabe von Parametern mit Ihrer + cloud-config + - Datei, mit der Sie Ihre Knoten booten. In der Bootstrapping-Anleitung haben Sie ein bisschen gesehen, wie das geht:

#cloud-config

coreos:
 etcd:
   discovery: https://discovery.etcd.io/
   addr: $private_ipv4:4001
   peer-addr: $private_ipv4:7001
. . .

Um die verfügbaren Optionen anzuzeigen, verwenden Sie das Flag "+ -h " mit " etcd +":

etcd -h

Um diese Optionen in Ihre + cloud-config + aufzunehmen, entfernen Sie einfach den führenden Bindestrich und trennen Sie die Schlüssel von den Werten mit einem Doppelpunkt anstelle eines Gleichheitszeichens. So wird aus "+ -peer-addr = <host: port> " " peer-addr: <host: port> +".

Beim Lesen der Datei "+ cloud-config +" übersetzt CoreOS diese in Umgebungsvariablen in eine Stub-Unit-Datei, mit der der Dienst gestartet wird.

Eine andere Möglichkeit, die Einstellungen für "+ etcd " anzupassen, ist die API. Dies geschieht in der Regel über den Port " 7001 " anstelle des Standards " 4001 +", der für Schlüsselabfragen verwendet wird.

Beispielsweise können Sie einige der aktuellen Konfigurationswerte abrufen, indem Sie Folgendes eingeben:

curl -L http://127.0.0.1:7001/v2/admin/config

{"activeSize":9,"removeDelay":1800,"syncInterval":5}

Sie können diese Werte ändern, indem Sie den neuen JSON als Datennutzdaten mit einer PUT-Operation übergeben:

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}

Um eine Liste der Maschinen zu erhalten, können Sie zum Endpunkt "+ / v2 / admin / machines +" gehen:

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"}]

Dies kann verwendet werden, um Computer mit der DELETE-Methode zwangsweise aus dem Cluster zu entfernen.

Fazit

Wie Sie sehen, können Sie mit + etcd + Informationen von jedem Computer in Ihrem Cluster speichern oder abrufen. Auf diese Weise können Sie Daten synchronisieren und Dienste können an einem Speicherort nach Konfigurationsdaten und Verbindungsdetails suchen.

Dies ist besonders nützlich, wenn Sie verteilte Systeme erstellen, da Sie einen einfachen Endpunkt bereitstellen können, der von jedem Ort innerhalb des Clusters aus gültig ist. Wenn Sie diese Ressource nutzen, können sich Ihre Dienste dynamisch konfigurieren.

TOC