Dieser Abschnitt bietet aufgabenbezogene Anleitungen für Entwickler, die Anwendungen mit etcd erstellen, sowie für Betreiber, die etcd-Cluster bereitstellen, konfigurieren und warten.
Damit ist etcd einsatzbereit! So lässt sich mit etcdctl eine Verbindung zu etcd herstellen:
exportETCDCTL_API=3HOST_1=10.240.0.17
HOST_2=10.240.0.18
HOST_3=10.240.0.19
ENDPOINTS=$HOST_1:2379,$HOST_2:2379,$HOST_3:2379
etcdctl --endpoints=$ENDPOINTS member list
1.2 - Eine Leader-Wahl in einem etcd-Cluster durchführen
Schritte zum Durchführen einer Leader-Wahl mit dem etcdctl-Client
Voraussetzungen
Sicherstellen, dass etcd
und etcdctl
installiert sind.
Prüfen, ob ein etcd-Cluster aktiv ist.
Eine Leader-Wahl durchführen
Mit dem Befehl etcdctl werden Leader-Wahlen in einem etcd-Cluster durchgeführt. Er stellt sicher, dass jeweils nur ein Client Leader werden kann.
Anschließend ein Mitglied mit den Befehlen member remove und member add ersetzen:
# get member IDexportETCDCTL_API=3HOST_1=10.240.0.13
HOST_2=10.240.0.14
HOST_3=10.240.0.15
etcdctl --endpoints=${HOST_1}:2379,${HOST_2}:2379,${HOST_3}:2379 member list
# remove the memberMEMBER_ID=278c654c9a6dfd3b
etcdctl --endpoints=${HOST_1}:2379,${HOST_2}:2379,${HOST_3}:2379 \
member remove ${MEMBER_ID}# add a new member (node 4)exportETCDCTL_API=3NAME_1=etcd-node-1
NAME_2=etcd-node-2
NAME_4=etcd-node-4
HOST_1=10.240.0.13
HOST_2=10.240.0.14
HOST_4=10.240.0.16 # new memberetcdctl --endpoints=${HOST_1}:2379,${HOST_2}:2379 \
member add ${NAME_4}\
--peer-urls=http://${HOST_4}:2380
Danach das neue Mitglied mit der Option --initial-cluster-state existing starten:
# [WARNING] If the new member starts from the same disk space,# make sure to remove the data directory of the old member## restart with 'existing' flagTOKEN=my-etcd-token-1
CLUSTER_STATE=existing
NAME_1=etcd-node-1
NAME_2=etcd-node-2
NAME_4=etcd-node-4
HOST_1=10.240.0.13
HOST_2=10.240.0.14
HOST_4=10.240.0.16 # new memberCLUSTER=${NAME_1}=http://${HOST_1}:2380,${NAME_2}=http://${HOST_2}:2380,${NAME_4}=http://${HOST_4}:2380
THIS_NAME=${NAME_4}THIS_IP=${HOST_4}etcd --data-dir=data.etcd --name ${THIS_NAME}\
--initial-advertise-peer-urls http://${THIS_IP}:2380 \
--listen-peer-urls http://${THIS_IP}:2380 \
--advertise-client-urls http://${THIS_IP}:2379 \
--listen-client-urls http://${THIS_IP}:2379 \
--initial-cluster ${CLUSTER}\
--initial-cluster-state ${CLUSTER_STATE}\
--initial-cluster-token ${TOKEN}
2 - Aufgaben für Entwickler
Schrittweise Anleitungen für Entwickler, die etcd als Schlüssel-Wert-Speicher in ihren Anwendungen verwenden.
2.1 - Aus etcd lesen
Einen Wert aus einem etcd-Cluster lesen
Voraussetzungen
etcdctl installieren
Vorgehensweise
Mit dem Unterbefehl get aus etcd lesen:
$ etcdctl --endpoints=$ENDPOINTS get foo
foo
Hello World!
$
Dabei gilt:
foo ist der angeforderte Schlüssel
Hello World! ist der abgerufene Wert
Für eine formatierte Ausgabe:
$ 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"}]}}
$
Dabei gibt write-out="json" JSON aus, in dem sowohl der Schlüssel als auch der Wert base64-kodiert sind.
2.2 - In etcd schreiben
Ein KV-Paar zu einem etcd-Cluster hinzufügen
Voraussetzungen
etcdctl installieren
Vorgehensweise
Mit dem Unterbefehl put ein Schlüssel-Wert-Paar schreiben:
etcdctl --endpoints=$ENDPOINTS put foo "Hello World!"
Dabei gilt:
foo ist der Schlüsselname
"Hello World!" ist der in Anführungszeichen eingeschlossene Wert
2.3 - Schlüssel anhand eines Präfixes abrufen
Anleitung zum Abrufen von etcd-Schlüsseln anhand ihres Präfixes
$ etcdctl --endpoints=$ENDPOINTS get PREFIX --prefix
Globale Optionen
--endpoints=[127.0.0.1:2379], gRPC endpoints
Optionen
--prefix, get a range of keys with matching prefix
Beispiel
etcdctl --endpoints=$ENDPOINTS put web1 value1
etcdctl --endpoints=$ENDPOINTS put web2 value2
etcdctl --endpoints=$ENDPOINTS put web3 value3
etcdctl --endpoints=$ENDPOINTS get web --prefix
del zum Entfernen des angegebenen Schlüssels oder Schlüsselbereichs:
etcdctl del $KEY[$END_KEY]
Optionen
--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
Von übergeordneten Befehlen geerbte Optionen
--endpoints="127.0.0.1:2379": gRPC endpoints
Beispiele
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
2.5 - Mehrere Schreibvorgänge in einer Transaktion ausführen
Der Befehl txn ist eine Abkürzung für „transaction“ (Transaktion). Er liest mehrere etcd-Anfragen von der Standardeingabe und wendet sie als eine einzige atomare Transaktion an. Eine Transaktion besteht aus einer Liste von Bedingungen, einer Liste von Anfragen für den Fall, dass alle Bedingungen erfüllt sind, und einer Liste von Anfragen für den Fall, dass mindestens eine Bedingung nicht erfüllt ist. Weitere Informationen unter etcdctl-Befehle für Schlüssel-Wert-Paare
.
compare
Die Klausel compare innerhalb einer Transaktion (txn) prüft eine Bedingung und entscheidet dadurch, ob die Operationen der Transaktion ausgeführt werden sollen. Änderungen werden nur angewendet, wenn der aktuelle Zustand des Schlüssel-Wert-Speichers den erwarteten Bedingungen entspricht. Dies erhält die Datenkonsistenz und verhindert Konflikte bei nebenläufigen Zugriffen. Der Aufbau des Befehls wird im folgenden Abschnitt Eine Transaktion ausführen
gezeigt.
Transaktionen
txn zum Verarbeiten aller Anfragen in einer Transaktion:
etcdctl txn --help
Mit Transaktionen in etcd lassen sich mehrere Operationen atomar ausführen: Entweder werden alle Operationen angewendet oder keine. Das ist entscheidend, um bei zusammengehörigen Aktualisierungen die Datenkonsistenz zu wahren. Weitere Informationen zu Transaktionen enthält die API-Dokumentation
.
Beispiel
Angenommen, die E-Mail-Adresse und Telefonnummer eines Benutzers sollen in einer einzigen Transaktion aktualisiert werden. So werden beide Änderungen gemeinsam angewendet.
0. Verwendete Variablen und Optionen
Variablen
/users/{<user_id>/email : etcd-Schlüssel für die E-Mail-Adresse eines Benutzers.
/users/<user_id>/phone : etcd-Schlüssel für die Telefonnummer eines Benutzers.
Optionen
--interactive
: Option zur manuellen Eingabe von Transaktionsdaten
1. Anfangsdaten einrichten
Zunächst einen Benutzer mit einigen Anfangsdaten erstellen.
etcdctl put /users/12345/email "old.address@johndoe.com"etcdctl put /users/12345/phone "123-456-7890"
2. Eine Transaktion ausführen
Die E-Mail-Adresse und Telefonnummer des Benutzers in einer einzigen Transaktion aktualisieren.
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
Vergleich: Prüfen, ob die aktuelle E-Mail-Adresse “old.address@johndoe.com
” lautet. So wird die Transaktion nur fortgesetzt, wenn die Daten dem erwarteten Zustand entsprechen.
Erfolg: Bei erfolgreichem Vergleich sowohl die E-Mail-Adresse als auch die Telefonnummer aktualisieren.
Fehlschlag: Schlägt der Vergleich fehl, die aktuelle E-Mail-Adresse abrufen, um zu verstehen, warum die Transaktion nicht fortgesetzt wurde.
Wichtige Hinweise
Atomarität: Die Transaktion stellt sicher, dass E-Mail-Adresse und Telefonnummer gemeinsam aktualisiert werden. Ist die Anfangsbedingung (der Vergleich) nicht erfüllt, wird keine der beiden Änderungen angewendet.
Konsistenz: Transaktionen erhalten die Datenkonsistenz, insbesondere bei mehreren zusammengehörigen Aktualisierungen.
Mehrere put-Operationen für denselben Schlüssel vermeiden: Innerhalb einer einzigen Transaktion nicht mehrere Werte für denselben Schlüssel schreiben, da dies zu unerwarteten Ergebnissen führen kann. Jeder Schlüssel sollte pro Transaktion nur einmal aktualisiert werden.
watch für Benachrichtigungen über künftige Änderungen:
etcdctl watch $KEY[$END_KEY]
Optionen
-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
Von übergeordneten Befehlen geerbte Optionen
--endpoints="127.0.0.1:2379": gRPC endpoints
Beispiele
etcdctl --endpoints=$ENDPOINTS watch stock1
etcdctl --endpoints=$ENDPOINTS put stock1 1000etcdctl --endpoints=$ENDPOINTS watch stock --prefix
etcdctl --endpoints=$ENDPOINTS put stock1 10etcdctl --endpoints=$ENDPOINTS put stock2 20
2.7 - Eine Lease erstellen
Anleitung zum Erstellen einer Lease in etcd
lease zum Schreiben mit TTL:
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 secondsetcdctl --endpoints=$ENDPOINTS get sample
2.8 - Sperren erstellen
Anleitung zum Erstellen verteilter Sperren in etcd
LOCK erwirbt einen verteilten Mutex mit einem bestimmten Namen. Sobald die Sperre erworben wurde, bleibt sie bis zum Beenden von etcdctl bestehen.
