Première session CLI

Ce que vous construisez

Vous installez le client en ligne de commande kyvernon sur une machine à vous, vous vous connectez au contrôleur, vous listez des objets de l'inventaire et vous lancez une tâche que vous attendez.

Avant de commencer

• Un contrôleur en fonctionnement dont vous connaissez l'adresse, par exemple https://controller.example.com:8443. Installer depuis un dépôt hors ligne en met un en place.
• Un nom d'utilisateur et un mot de passe. Après Première connexion, l'utilisateur admin a aussi besoin de son code à six chiffres.
• Une machine Debian ou Ubuntu, le répertoire du dépôt et la clé publique de version, comme dans la leçon d'installation.

1. Installer le client

Sur la machine qui doit exécuter le client :

sudo ./kyvernon-install --role cli --pubkey /path/to/release-signing.minisign.pub

Le programme d'installation vérifie le dépôt comme dans la leçon d'installation, puis installe uniquement le paquet kyvernon-cli.

2. Indiquer où se trouve le contrôleur

Le client lit l'adresse du contrôleur dans --server ou dans la variable KYVERNON_SERVER :

export KYVERNON_SERVER=https://controller.example.com:8443

Un contrôleur qui a encore son certificat d'amorçage n'est pas approuvé par la machine. Ajoutez --insecure à chaque commande jusqu'à ce que le contrôleur ait un certificat que la machine approuve, et seulement sur un réseau que vous maîtrisez. Les exemples ci-dessous l'omettent.

3. Se connecter

Le client lit le mot de passe dans la variable KYVERNON_PASSWORD ou sur l'entrée standard, jamais sur la ligne de commande :

read -rs KYVERNON_PASSWORD
export KYVERNON_PASSWORD
kyvernon login admin --save --code <code>

Remplacez <code> par le code à six chiffres actuel de votre application d'authentification, ou omettez --code pour un utilisateur sans validation en deux étapes. La commande affiche le jeton. --save l'écrit aussi dans le fichier d'identifiants, de sorte que les commandes suivantes n'ont pas besoin de --token. Le fichier est $XDG_CONFIG_HOME/kyvernon/credentials.json, écrit avec le mode 0600 dans un répertoire de mode 0700. Le jeton enregistré appartient au contrôleur auquel vous vous êtes connecté : avec un autre --server, le client refuse de l'envoyer et se termine avec le code 3.

4. Vérifier la connexion

kyvernon whoami
kyvernon about

whoami affiche l'identité de la session en cours. about affiche les informations de service du contrôleur.

5. Lister l'inventaire

kyvernon inventory roots
kyvernon inventory vms
kyvernon inventory hosts
kyvernon inventory datastores
kyvernon inventory search <name>

Les listes apparaissent sous forme de tableau. Ajoutez --json pour la réponse brute, que les scripts peuvent lire :

kyvernon inventory vms --json

Chaque objet a un identifiant tel que vm-42. Les commandes qui agissent sur un objet le prennent en argument.

6. Lancer une tâche et l'attendre

Choisissez une machine virtuelle hors tension, par exemple celle de Première machine virtuelle, et mettez-la sous tension :

kyvernon vm power-on <id>

La commande revient aussitôt avec la tâche que Kyvernon a créée. Attendez la fin de la tâche avec l'identifiant affiché :

kyvernon tasks wait <task-id>

La commande d'attente s'arrête après 60 secondes par défaut ; --timeout change cette durée. La plupart des commandes qui lancent une tâche acceptent --wait, qui fait les deux étapes :

kyvernon vm shutdown <id> --wait

Le code de sortie indique à un script ce qui s'est passé : 0 pour un succès, 1 pour un échec, 2 pour une erreur d'utilisation ou de connexion, 3 lorsque la session n'est pas authentifiée ou pas autorisée, et 4 lorsque l'objet est introuvable.

7. Garder un jeton pour les scripts

Un script ne doit pas détenir votre mot de passe. Créez un jeton d'API et donnez-le au script sous forme de fichier :

kyvernon auth api-tokens create ci-build --ttl <seconds>
kyvernon --token-file /etc/ci/kyvernon.token inventory vms

Le secret est affiché une seule fois ; enregistrez-le sur la première ligne du fichier. Le client lit aussi --token et les variables KYVERNON_TOKEN et KYVERNON_TOKEN_FILE.

8. Terminer la session

kyvernon logout

Cela révoque la session sur le contrôleur. Pour la complétion par tabulation dans votre shell, kyvernon completion bash affiche un script pour Bash. Zsh, Fish, PowerShell et Elvish sont disponibles sous la même commande, par exemple source <(kyvernon completion bash).

Résultat

Vous avez un client qui se connecte au contrôleur, liste l'inventaire, exécute une tâche et l'attend. La liste complète des commandes se trouve dans la référence de la CLI.

Étapes suivantes

• Vue d'ensemble explique les objets que les commandes nomment.
• Opérations d'alimentation liste les commandes d'alimentation d'une machine virtuelle.
• Connecter des outils vSphere dirige les outils écrits pour l'API vSphere vers le contrôleur.