Interaction avec etcd

Les utilisateurs interagissent généralement avec etcd en définissant ou en récupérant la valeur d’une clé. Cette section décrit comment effectuer ces opérations à l’aide d’etcdctl, un outil en ligne de commande pour interagir avec le serveur etcd. Les concepts décrits ici s’appliquent également aux API gRPC ou aux API des bibliothèques clientes.

La version de l’API utilisée par etcdctl pour communiquer avec etcd peut être définie à 2 ou 3 via la variable d’environnement ETCDCTL_API. Par défaut, etcdctl sur la branche master (3.4) utilise l’API v3, tandis que les versions antérieures (3.3 et antérieures) utilisent par défaut l’API v2.

Notez qu’une clé créée à l’aide de l’API v2 ne pourra pas être interrogée via l’API v3. Une requête v3 etcdctl get d’une clé v2 se terminera avec le code 0 et sans données de clé ; il s’agit du comportement attendu.

export ETCDCTL_API=3

Rechercher les versions

La version d’etcdctl et la version de l’API serveur peuvent être utiles pour identifier les commandes appropriées à utiliser pour effectuer diverses opérations sur etcd.

Voici la commande permettant de trouver les versions :

$ etcdctl version
etcdctl version: 3.1.0-alpha.0+git
API version: 3.1

Écrire une clé

Les applications stockent des clés dans le cluster etcd en écrivant sur des clés. Chaque clé stockée est répliquée sur tous les membres du cluster etcd via le protocole Raft afin d’assurer la cohérence et la fiabilité.

Voici la commande permettant de définir la valeur de la clé foo à bar :

$ etcdctl put foo bar
OK

Un clé peut également être définie pour une durée déterminée en lui associant un bail.

Voici la commande permettant de définir la valeur de la clé foo1 à bar1 pendant 10 s.

$ etcdctl put foo1 bar1 --lease=1234abcd
OK

Lire les clés

Les applications peuvent lire les valeurs des clés d’un cluster etcd. Les requêtes peuvent lire une seule clé ou une plage de clés.

Supposons que le cluster etcd ait stocké les clés suivantes :

foo = bar
foo1 = bar1
foo2 = bar2
foo3 = bar3

Voici la commande pour lire la valeur de la clé foo :

$ etcdctl get foo
foo
bar

Voici la commande pour lire la valeur de la clé foo au format hexadécimal :

$ etcdctl get foo --hex
\x66\x6f\x6f          # Key
\x62\x61\x72          # Value

Voici la commande pour lire uniquement la valeur de la clé foo :

$ etcdctl get foo --print-value-only
bar

Voici la commande pour parcourir les clés allant de foo à foo3 :

$ etcdctl get foo foo3
foo
bar
foo1
bar1
foo2
bar2

Voici la commande permettant de parcourir toutes les clés ayant pour préfixe foo :

$ etcdctl get --prefix foo
foo
bar
foo1
bar1
foo2
bar2
foo3
bar3

Voici la commande pour parcourir toutes les clés ayant pour préfixe foo, en limitant le nombre de résultats à 2 :

$ etcdctl get --prefix --limit=2 foo
foo
bar
foo1
bar1

Voici la commande permettant de parcourir toutes les clés préfixées par foo en utilisant l’API RPC RangeStream . Le résultat est identique à un appel unaire Range :

$ etcdctl get --stream --prefix foo
foo
bar
foo1
bar1
foo2
bar2
foo3
bar3

--stream ne prend pas en charge --order, --sort-by ni les filtres de révision.

Lire les versions antérieures des clés

Les applications peuvent souhaiter lire des versions obsolètes d’une clé. Par exemple, une application peut souhaiter revenir à une configuration ancienne en accédant à une version antérieure d’une clé. En outre, une application peut souhaiter obtenir une vue cohérente sur plusieurs clés au fil de plusieurs requêtes en accédant à l’historique des clés.

Étant donné qu’une modification apportée au magasin clé-valeur d’un cluster etcd incrémente la révision globale du cluster etcd, une application peut lire des clés obsolètes en fournissant une révision etcd antérieure.

Supposons qu’un cluster etcd dispose déjà des clés suivantes :

foo = bar         # revision = 2
foo1 = bar1       # revision = 3
foo = bar_new     # revision = 4
foo1 = bar1_new   # revision = 5

Voici un exemple pour accéder aux versions antérieures des clés :

$ etcdctl get --prefix foo # access the most recent versions of keys
foo
bar_new
foo1
bar1_new

$ etcdctl get --prefix --rev=4 foo # access the versions of keys at revision 4
foo
bar_new
foo1
bar1

$ etcdctl get --prefix --rev=3 foo # access the versions of keys at revision 3
foo
bar
foo1
bar1

$ etcdctl get --prefix --rev=2 foo # access the versions of keys at revision 2
foo
bar

$ etcdctl get --prefix --rev=1 foo # access the versions of keys at revision 1

Lire les clés dont la valeur en octets est supérieure ou égale à celle de la clé spécifiée

Les applications peuvent souhaiter lire des clés dont la valeur en octets est supérieure ou égale à celle de la clé spécifiée.

Supposons qu’un cluster etcd dispose déjà des clés suivantes :

a = 123
b = 456
z = 789

Voici la commande permettant de lire les clés dont la valeur d’octet est supérieure ou égale à celle de la clé b :

$ etcdctl get --from-key b
b
456
z
789

Supprimer des clés

Les applications peuvent supprimer une clé ou une plage de clés d’un cluster etcd.

Supposons qu’un cluster etcd dispose déjà des clés suivantes :

foo = bar
foo1 = bar1
foo3 = bar3
zoo = val
zoo1 = val1
zoo2 = val2
a = 123
b = 456
z = 789

Voici la commande pour supprimer la clé foo :

$ etcdctl del foo
1 # one key is deleted

Voici la commande permettant de supprimer les clés comprises entre foo et foo9 :

$ etcdctl del foo foo9
2 # two keys are deleted

Voici la commande permettant de supprimer la clé zoo avec la paire clé-valeur supprimée renvoyée :

$ etcdctl del --prev-kv zoo
1   # one key is deleted
zoo # deleted key
val # the value of the deleted key

Voici la commande permettant de supprimer les clés dont le préfixe est zoo :

$ etcdctl del --prefix zoo
2 # two keys are deleted

Voici la commande permettant de supprimer les clés dont la valeur d’octet est supérieure ou égale à celle de la clé b :

$ etcdctl del --from-key b
2 # two keys are deleted

Surveillance des modifications de clé

Les applications peuvent surveiller une clé ou une plage de clés afin de détecter toute mise à jour.

Voici la commande pour surveiller la clé foo :

$ etcdctl watch foo
# in another terminal: etcdctl put foo bar
PUT
foo
bar

Voici la commande pour surveiller la clé foo au format hexadécimal :

$ etcdctl watch foo --hex
# in another terminal: etcdctl put foo bar
PUT
\x66\x6f\x6f          # Key
\x62\x61\x72          # Value

Voici la commande pour effectuer une surveillance sur une plage de clés de foo à foo9 :

$ etcdctl watch foo foo9
# in another terminal: etcdctl put foo bar
PUT
foo
bar
# in another terminal: etcdctl put foo1 bar1
PUT
foo1
bar1

Voici la commande pour surveiller les clés ayant le préfixe foo :

$ etcdctl watch --prefix foo
# in another terminal: etcdctl put foo bar
PUT
foo
bar
# in another terminal: etcdctl put fooz1 barz1
PUT
fooz1
barz1

Voici la commande pour effectuer une surveillance sur plusieurs clés foo et zoo :

$ etcdctl watch -i
$ watch foo
$ watch zoo
# in another terminal: etcdctl put foo bar
PUT
foo
bar
# in another terminal: etcdctl put zoo val
PUT
zoo
val

Surveillance des modifications historiques des clés

Les applications peuvent souhaiter surveiller les modifications historiques de clés dans etcd. Par exemple, une application peut souhaiter recevoir toutes les modifications d’une clé ; si l’application reste connectée à etcd, alors watch est suffisant. Toutefois, si l’application ou etcd échoue, une modification peut survenir pendant l’indisponibilité, et l’application ne recevra pas la mise à jour en temps réel. Pour garantir que la mise à jour soit livrée, l’application doit pouvoir surveiller les modifications historiques des clés. Pour cela, une application peut spécifier une révision historique lors d’une surveillance, tout comme lors de la lecture d’une version antérieure de clés.

Supposons que nous ayons terminé la séquence d’opérations suivante :

$ etcdctl put foo bar         # revision = 2
OK
$ etcdctl put foo1 bar1       # revision = 3
OK
$ etcdctl put foo bar_new     # revision = 4
OK
$ etcdctl put foo1 bar1_new   # revision = 5
OK

Voici un exemple de surveillance des modifications historiques :

# watch for changes on key `foo` since revision 2
$ etcdctl watch --rev=2 foo
PUT
foo
bar
PUT
foo
bar_new

# watch for changes on key `foo` since revision 3
$ etcdctl watch --rev=3 foo
PUT
foo
bar_new

Voici un exemple de surveillance uniquement à partir du dernier changement historique :

# watch for changes on key `foo` and return last revision value along with modified value
$ etcdctl watch --prev-kv foo
# in another terminal: etcdctl put foo bar_latest
PUT
foo         # key
bar_new     # last value of foo key before modification
foo         # key
bar_latest  # value of foo key after modification

Progression de la surveillance

Les applications peuvent souhaiter vérifier l’avancement d’une surveillance afin de déterminer à quel point le flux de surveillance est à jour. Par exemple, si une surveillance est utilisée pour mettre à jour un cache, il peut être utile de savoir si le cache est périmé par rapport à la révision obtenue à partir d’une lecture en quorum.

Les requêtes de progression peuvent être émises à l’aide de la commande « progress » dans une session de surveillance interactive afin de demander au serveur etcd d’envoyer une mise à jour de notification de progression dans le flux de surveillance :

$ etcdctl watch -i
$ watch a
$ progress
progress notify: 1
# in another terminal: etcdctl put x 0
# in another terminal: etcdctl put y 1
$ progress
progress notify: 3

Révisions compactées

Comme nous l’avons mentionné, etcd conserve des révisions afin que les applications puissent lire des versions antérieures des clés. Toutefois, afin d’éviter de accumuler une quantité illimitée d’historique, il est important de compacter les révisions passées. Une fois la compaction effectuée, etcd supprime les révisions historiques, libérant ainsi des ressources pour une utilisation future. Toutes les données obsolètes dont la révision est antérieure à la révision compactée deviendront indisponibles.

Voici la commande pour compacter les révisions :

$ etcdctl compact 5
compacted revision 5

# any revisions before the compacted one are not accessible
$ etcdctl get --rev=4 foo
Error:  rpc error: code = 11 desc = etcdserver: mvcc: required revision has been compacted

$ etcdctl get mykey -w=json
{"header":{"cluster_id":14841639068965178418,"member_id":10276657743932975437,"revision":15,"raft_term":4}}

Accorder des bails

Les applications peuvent accorder des bails pour des clés depuis un cluster etcd. Lorsqu’une clé est associée à un bail, sa durée de vie est liée à celle du bail, qui à son tour est régulée par une durée de vie (TTL). Chaque bail a une valeur minimale de durée de vie (TTL) spécifiée par l’application au moment de l’accord. La valeur réelle de TTL du bail est au moins égale à la durée minimale et est choisie par le cluster etcd. Dès qu’une durée de vie (TTL) d’un bail a expiré, le bail expire et toutes les clés associées sont supprimées.

Voici la commande pour accorder un bail :

# grant a lease with 60 second TTL
$ etcdctl lease grant 60
lease 32695410dcc0ca06 granted with TTL(60s)

# attach key foo to lease 32695410dcc0ca06
$ etcdctl put --lease=32695410dcc0ca06 foo bar
OK

Révoquer les bails

Les applications révoquent les bails par identifiant de bail. La révocation d’un bail supprime toutes les clés associées.

Supposons que nous ayons terminé la séquence d’opérations suivante :

$ etcdctl lease grant 60
lease 32695410dcc0ca06 granted with TTL(60s)
$ etcdctl put --lease=32695410dcc0ca06 foo bar
OK

Voici la commande pour révoquer le même bail :

$ etcdctl lease revoke 32695410dcc0ca06
lease 32695410dcc0ca06 revoked

$ etcdctl get foo
# empty response since foo is deleted due to lease revocation

Maintenir les bails actifs

Les applications peuvent maintenir un bail actif en actualisant périodiquement son TTL afin qu’il ne expire pas.

Supposons que nous ayons terminé la séquence d’opérations suivante :

$ etcdctl lease grant 60
lease 32695410dcc0ca06 granted with TTL(60s)

Voici la commande permettant de maintenir le bail actif :

$ etcdctl lease keep-alive 32695410dcc0ca06
lease 32695410dcc0ca06 keepalived with TTL(60)
lease 32695410dcc0ca06 keepalived with TTL(60)
lease 32695410dcc0ca06 keepalived with TTL(60)
...

Obtenir les informations sur le bail

Les applications peuvent souhaiter connaître les informations relatives aux bails, afin de les renouveler ou de vérifier s’ils existent encore ou ont expiré. Les applications peuvent également souhaiter connaître les clés auxquelles un bail particulier est associé.

Supposons que nous ayons terminé la séquence d’opérations suivante :

# grant a lease with 500 second TTL
$ etcdctl lease grant 500
lease 694d5765fc71500b granted with TTL(500s)

# attach key zoo1 to lease 694d5765fc71500b
$ etcdctl put zoo1 val1 --lease=694d5765fc71500b
OK

# attach key zoo2 to lease 694d5765fc71500b
$ etcdctl put zoo2 val2 --lease=694d5765fc71500b
OK

Voici la commande permettant d’obtenir des informations sur le bail :

$ etcdctl lease timetolive 694d5765fc71500b
lease 694d5765fc71500b granted with TTL(500s), remaining(258s)

Voici la commande permettant d’obtenir des informations sur le bail ainsi que les clés associées au bail :

$ etcdctl lease timetolive --keys 694d5765fc71500b
lease 694d5765fc71500b granted with TTL(500s), remaining(132s), attached keys([zoo2 zoo1])

# if the lease has expired or does not exist it will give the below response:
Error:  etcdserver: requested lease not found