Automatiser les applications

Créer, configurer, déployer et supprimer des applications depuis un terminal ou un script, avec chaque option expliquée.

Tout ce que la console fait pour une application, la CLI le fait avec des options. Cette page explique comment en créer une, la modifier ensuite, et présente les commandes que vous utiliserez au quotidien. Pour le pipeline qui les entoure, voir Déployer depuis la CI/CD.

Désigner les éléments

Une application se désigne par son slug, son nom ou son identifiant. Un préfixe unique du slug ou de l'identifiant fonctionne aussi, ce qui est pratique dans un terminal et risqué dans un script : api correspondrait à api-gateway si c'était la seule. Les scripts doivent utiliser apps get --exact pour vérifier si quelque chose existe.

Les options peuvent venir avant ou après le nom : isogrid apps deploy shop --wait et isogrid apps deploy --wait shop sont la même commande.

Les régions, tailles, réseaux, coffres, groupes et membres se résolvent de la même façon : par identifiant, par slug ou par le nom affiché dans la console. Quand un nom ne correspond à rien, ou à plusieurs éléments, l'erreur liste les choix valides.

Créer une application

isogrid apps create --name NAME --provider github|gitlab|registry --url REPO_URL|IMAGE_REF
    [--cluster REGION] [--tier SIZE] [--network NETWORK] [--organization ORG]
    [--branch main] [--dockerfile Dockerfile] [--context .] [--port N] [--replicas N] [--public]
    [--env KEY=VALUE]... [--env-file PATH] [--secret KEY=VALUE]... [--secrets-file PATH]
    [--vault-secret VAULT/KEY[:TARGET]]... [--slug SLUG] [--wait] [--follow] [--timeout 20m] [--json]

Seuls --name et --url sont obligatoires. Tout le reste a une valeur par défaut raisonnable.

D'où vient le code

--provider vaut github, gitlab ou registry. Vous pouvez l'omettre quand l'URL suffit : un hôte github.com signifie GitHub, et un hôte contenant gitlab signifie GitLab. Un GitLab auto-hébergé sous un autre nom, ou un simple owner/repo, en a besoin.

--url accepte ce que vous colleriez naturellement. Pour GitHub, toutes ces formes désignent le même dépôt :

acme/api
https://github.com/acme/api
https://github.com/acme/api.git
git@github.com:acme/api.git

Pour GitLab, y compris les instances auto-hébergées et les projets dans des groupes imbriqués :

https://gitlab.com/acme/api
https://gitlab.example.com/platform/backend/api
git@gitlab.example.com:platform/backend/api.git

Une URL copiée depuis la page d'une branche construit cette branche : https://github.com/acme/api/tree/release/2.0 et https://gitlab.com/acme/api/-/tree/staging fixent la branche, sauf si --branch indique autre chose. Sans l'un ni l'autre, la branche est main.

Le dépôt doit être connecté à votre organisation, et vous devez y avoir reçu l'accès. isogrid repos list montre les deux ; voir Dépôts Git.

Depuis le registre, --url est une référence d'image :

api:1.2
acme/api:1.2
registry.example.com:5000/acme/api:1.2

Le tag vaut latest par défaut, et --tag remplace celui de la référence. --image acme/api:1.2 est un raccourci pour --provider registry --url acme/api:1.2. L'image doit déjà avoir été poussée, dans un namespace depuis lequel vous pouvez déployer.

Comment elle est construite

Pour un dépôt :

Où elle s'exécute, et avec quelle taille

--cluster est la région. Vous pouvez l'omettre si une seule région vous est ouverte ; sinon, l'erreur liste celles que vous pouvez choisir.

--tier est le type d'instance. Par défaut, c'est le plus petit de la région. isogrid apps tiers <app> les liste une fois l'application créée ; avant cela, le formulaire de création de la console affiche la même liste.

--network vaut par défaut le réseau propre à votre organisation dans cette région. Indiquez-en un autre pour placer l'application à côté d'un élément qu'elle doit joindre en privé.

Ces trois options acceptent un slug, un nom ou un identifiant.

--port est le port sur lequel le conteneur écoute. Sans lui, c'est le port déclaré par l'image qui est utilisé, et 8080 si elle n'en déclare aucun.

--replicas est le nombre de copies à exécuter, 1 par défaut. Voir Déployer une application pour comprendre pourquoi une seule copie implique une courte interruption à chaque déploiement.

--public publie l'application sur une adresse publique. Sans cette option, elle n'en reçoit aucune ; vous pouvez la publier plus tard avec apps update --public.

--slug fixe l'identifiant utilisé dans les adresses et les commandes. Il est dérivé du nom si vous l'omettez.

Configuration et secrets

Il existe trois sortes de valeurs, et celle que vous choisissez détermine qui pourra la lire ensuite.

Variables d'environnement — --env KEY=VALUE (répétable) et --env-file PATH. De la configuration ordinaire, lisible par quiconque peut voir l'application. Quand une même clé figure dans les deux, l'option l'emporte : le fichier contient les valeurs par défaut, la ligne de commande l'exception.

Secrets de conteneur — --secret KEY=VALUE et --secrets-file PATH. Écrits dans le magasin de secrets avant le premier déploiement et plus jamais affichés, à personne, par aucune commande ni aucune API.

Secrets de coffre — --vault-secret VAULT/KEY[:TARGET]. Rend disponible dans l'application une clé qui existe déjà dans l'un de vos coffres. payments/stripe-key:STRIPE_KEY expose la clé stripe-key du coffre payments sous le nom STRIPE_KEY ; sans :TARGET, le nom est dérivé de la clé. Rien n'est copié : il suffit de changer la valeur dans le coffre.

Les fichiers utilisent le format dotenv habituel :

# comments and blank lines are ignored
LOG_LEVEL=info
export REGION=eu            # "export" is allowed, and so is an inline comment
GREETING='taken literally, $HOME included'
TLS_KEY="-----BEGIN PRIVATE KEY-----
spans several lines until the closing quote
-----END PRIVATE KEY-----"

Il n'y a pas d'expansion de variables : un $ dans une valeur reste un $. Les noms de variables se composent de lettres, de chiffres et de tirets bas, sans commencer par un chiffre, et les noms qui commencent par ISOGRID_ sont réservés à la plateforme. Les noms de secrets peuvent aussi contenir . et -, donc tls.key est valide. Une erreur est signalée avec le nom du fichier et le numéro de ligne avant que quoi que ce soit ne soit envoyé.

Attendre le résultat

Sans --wait, create rend la main dès que l'application existe et que sa première construction ou son premier déploiement est en file d'attente. Cela ne veut pas dire qu'elle fonctionne.

--wait bloque jusqu'à la fin de la construction (s'il y en a une) et du déploiement, et se termine avec un code non nul si l'un des deux a échoué. --follow fait de même en affichant les journaux de construction et de déploiement. --timeout limite l'attente ; il vaut 20m par défaut.

Une attente échoue — code de sortie 1 — lorsque :

• la construction échoue ;
• le déploiement échoue ;
• la nouvelle version n'est jamais devenue saine et a été annulée au profit de la précédente, même si l'application continue de répondre ;
• l'application est déployée mais reste en dessous de son nombre de copies pendant plus de trois minutes, ce qui signifie qu'elles plantent ;
• le délai expire. Le travail se poursuit sur la plateforme ; seule l'attente s'arrête. Vérifiez avec isogrid apps status.

--json affiche l'application telle que l'API l'a renvoyée, sur la sortie standard, une fois la commande terminée. La progression va sur la sortie d'erreur, les deux ne se mélangent donc jamais.

Exemples

Un dépôt, avec les valeurs par défaut pour tout ce qui en a une :

isogrid apps create --name shop --url https://github.com/acme/shop --wait

Un projet GitLab sur votre propre hôte, une branche précise, une taille et deux copies :

isogrid apps create \
  --name billing-api \
  --provider gitlab \
  --url https://git.acme.internal/platform/billing/api \
  --branch release \
  --cluster eu-west --tier medium --replicas 2 \
  --env-file deploy/production.env \
  --secrets-file deploy/production.secrets.env \
  --vault-secret payments/stripe-key:STRIPE_KEY \
  --public --wait

Une image que vous avez déjà poussée :

isogrid apps create --name worker --image acme/worker:2024.10.1 --cluster eu-west --wait

Modifier une application

isogrid apps update <app> [--name N] [--branch B] [--dockerfile P] [--context D] [--url URL|IMAGE] [--tag T]
    [--port N] [--replicas N] [--tier SIZE] [--cluster REGION] [--network NETWORK]
    [--env KEY=VALUE]... [--unset-env KEY]... [--env-file PATH] [--replace-env]
    [--secret KEY=VALUE]... [--secrets-file PATH] [--unset-secret KEY]... [--replace-secrets]
    [--public | --private] [--deploy [--ref REF]] [--wait] [--follow] [--json]

Seul ce que vous indiquez change. Une commande qui ne changerait rien le signale et se termine avec le code 0, ce qui permet d'exécuter update sans risque dans chaque pipeline.

Variables d'environnement : fusionnées sauf indication contraire

--replace-env sans aucune valeur vide l'environnement. À utiliser en connaissance de cause.

isogrid apps env <app> affiche l'environnement actuel sous forme de fichier dotenv, l'aller-retour se fait donc ainsi :

isogrid apps env shop > shop.env
# edit shop.env
isogrid apps update shop --env-file shop.env --replace-env

Secrets : même principe, sans jamais afficher les valeurs

isogrid apps secrets <app> liste les noms. Aucune commande ne renvoie de valeur.

Quand la modification prend effet

Une application en cours d'exécution est redéployée par la plateforme quand son environnement change, ou quand elle est redimensionnée (--tier, --replicas). Vous n'avez rien à demander.

Tout le reste prend effet au prochain déploiement. Passez --deploy pour que ce soit immédiat :

• Pour une application construite depuis git, --deploy construit la branche à son dernier commit et déploie le résultat. --ref construit, pour cette fois seulement, une branche, un tag ou un SHA de commit précis ; les constructions suivantes suivent toujours la branche de l'application.
• Pour une image, --deploy redéploie l'image et le tag configurés.

--wait, --follow et --timeout fonctionnent comme pour create. Avec --wait et rien à déployer, la commande indique qu'il n'y a rien à attendre.

Images et dépôts

Sur une application issue d'une image, --tag passe à un autre tag de la même image et --url à une autre image de votre registre. C'est ainsi qu'un pipeline qui construit ses propres images déploie chacune d'elles :

isogrid apps update worker --tag "$GIT_SHA" --deploy --wait

Le dépôt d'une application ne peut pas être changé. Sur une application construite depuis git, --url ne peut que reprendre le même dépôt, par exemple pour récupérer une branche depuis une URL /tree/BRANCH. Pour construire depuis un autre dépôt, créez une nouvelle application.

Exemples

Activer les journaux de débogage ; la plateforme redéploie l'application :

isogrid apps update shop --env LOG_LEVEL=debug --wait

Remplacer un identifiant et en supprimer un ancien :

isogrid apps update shop --secret DATABASE_PASSWORD="$NEW_PASSWORD" --unset-secret LEGACY_TOKEN

Suivre une nouvelle branche et la construire tout de suite :

isogrid apps update shop --branch release/3.0 --deploy --wait

Construire un commit précis, comme le fait un pipeline :

isogrid apps update shop --deploy --ref 3f2c1ab --wait

Déployer un fichier de stack

Un fichier docker-compose.yml ou docker stack se déploie tel quel. Chaque service devient une application, nommée <stack>-<service> :

isogrid stack preview SOURCE [--stack NAME] [--region REGION] [--var KEY=VALUE]... [--var-file PATH] [--json]
isogrid stack apply   SOURCE [--stack NAME] [--region REGION] [--var KEY=VALUE]... [--var-file PATH]
    [--size [FILE:]SERVICE=TIER]... [--registry [FILE:]SERVICE=NAME]... [--network [FILE:]SERVICE=NAME]...
    [--placement [FILE:]SERVICE=CONSTRAINT]... [--port [FILE:]SERVICE=N]... [--skip [FILE:]SERVICE]...
    [--no-deploy] [--wait] [--follow] [--timeout 20m] [--json]

SOURCE:  -f FILE|DIR ...                        (repeatable; - reads standard input)
         --repo REPO [--provider github|gitlab] [--ref REF] --path PATH ...   (--path repeatable)

Un court exemple, avec un bloc de journalisation partagé et une mise à jour progressive :

x-logging: &logging
  driver: json-file
  options:
    max-size: "20m"
    max-file: "5"

services:
  api:
    image: registry.gitlab.com/fraus/api:${IMAGE_TAG}
    env_file: [api.env]
    ports: ["8000:8000"]
    logging: *logging
    deploy:
      replicas: 2
      update_config:
        parallelism: 1
        delay: 10s
        order: start-first
        failure_action: rollback
        monitor: 30s
      restart_policy:
        condition: on-failure
      placement:
        constraints: ["node.labels.zone == a"]

  worker:
    image: registry.gitlab.com/fraus/worker:${IMAGE_TAG}
    logging: *logging

Déployez-le, et attendez que chaque service tourne :

isogrid stack apply -f stack.yml --stack fraus --var IMAGE_TAG=1.4.2 --wait

Cela crée fraus-api et fraus-worker. Appliquer à nouveau le même fichier avec le même --stack met à jour ces applications et les redéploie : le fichier peut donc vivre dans votre dépôt et être appliqué depuis un pipeline. Le nom de stack est un slug en minuscules de 40 caractères au plus.

Lancez d'abord isogrid stack preview. Elle ne change rien et montre, pour chaque service, si son application serait créée, mise à jour ou ignorée, l'image et le registre qui la récupère, la taille, le réseau, le placement qui serait appliqué à côté de celui que demande le fichier, les réglages de déploiement et de journaux, et les avertissements. -f - lit le fichier sur l'entrée standard.

Les ${VAR} du fichier sont remplies par --var KEY=VALUE et --var-file (un fichier dotenv) ; l'option l'emporte. ${VAR:-default} fonctionne comme dans compose. Une variable utilisée par le fichier et que personne n'a fournie arrête apply avant tout changement.

Depuis un dépôt connecté

Le fichier n'a pas besoin d'être sur votre machine. --repo et --path désignent un fichier d'un dépôt GitHub ou GitLab que votre organisation a connecté, et la plateforme le lit avec l'accès de cette connexion : rien n'est cloné en local et aucun jeton ne passe par la CLI :

isogrid stack apply --repo gitlab:global_fraus/deployment-config \
  --path stacks/prod/login.yml --stack prod-login

--repo s'écrit owner/name (GitHub, par défaut) ou group/project ; écrivez gitlab:group/project, ou ajoutez --provider gitlab, pour GitLab. Une URL de dépôt fonctionne aussi. --ref lit une branche, une étiquette ou un commit au lieu de la branche par défaut. L'aperçu indique la référence lue, et apply lit cette même référence : un push entre les deux ne change pas ce que vous avez relu. -f et --repo ne se combinent pas.

Un dossier entier

-f accepte aussi un dossier, et déploie chaque fichier *.yml et *.yaml qu'il contient directement, par ordre de nom (les sous-dossiers ne sont pas lus). -f peut être répété, tout comme --path. Chaque fichier est sa propre stack :

isogrid stack apply -f stacks/prod --stack prod --var IMAGE_TAG=1.4.2 --wait

Avec plusieurs fichiers, --stack est un préfixe : stacks/prod/login.yml devient la stack prod-login, stacks/prod/billing.yml la stack prod-billing (le nom du fichier est mis en minuscules, tout ce qui n'est ni lettre ni chiffre devient -, et le nom complet est limité à 40 caractères). Sans --stack, le préfixe est le nom du dossier qui contient le fichier, ce qui donne ici les mêmes noms. Avec un seul fichier, --stack est le nom de la stack, comme avant.

Les fichiers sont d'abord prévisualisés, puis appliqués l'un après l'autre, chacun sous son propre en-tête. Un fichier qui échoue (une variable manquante, un service en échec) n'arrête pas les autres ; la commande affiche combien ont été appliqués et sort avec 1 si l'un d'eux a échoué. --wait attend les applications de tous les fichiers, dans le seul --timeout.

Ce qui est appliqué, et ce qui ne l'est pas

Un service avec build: et sans image est ignoré : construisez-le depuis son dépôt comme une application à part, ou poussez l'image et nommez-la. Les services sont placés sur le réseau de votre organisation dans la région, où ils se joignent par leur nom de service ; --network en place un ailleurs.

Choix par service

Une option qui désigne un service absent du fichier, ou un choix que la région ne propose pas, échoue avant tout envoi et liste ce qui aurait été valide.

Avec plusieurs fichiers, --size web=Large s'applique au service web de chaque fichier qui en a un. Préfixez-le d'un nom de fichier, avec ou sans son extension, pour ne viser qu'un fichier : --size login:web=Large, --skip billing.yml:worker.

--wait attend chaque application créée ou mise à jour, dans un seul --timeout pour l'ensemble, et sort avec 1 si un déploiement a échoué ou a été annulé, exactement comme apps deploy --wait. apply sort aussi avec 1 quand un service n'a pas pu être appliqué ; les autres le sont quand même, et la raison de chaque échec est affichée. --no-deploy enregistre les applications sans les déployer.

Autres registres de conteneurs

En plus du registre de la plateforme, les applications peuvent déployer des images depuis GitLab, GitHub, Docker Hub, Azure, Google, AWS, Quay ou tout registre qui parle l'API standard. Enregistrez les identifiants une fois par organisation :

isogrid registries list
isogrid registries add --name NAME --kind KIND [--host HOST] --username USER --password-stdin [--no-verify]
isogrid registries update <registry> [--name NAME] [--username USER] [--password-stdin]
isogrid registries test <registry>
isogrid registries remove <registry> [--yes]

--kind vaut dockerhub, gitlab, github, azure, google, aws, quay ou generic. --host peut être omis pour les types qui ont un hôte bien connu.

Le mot de passe ou le jeton n'est jamais une option. Il est lu sur l'entrée standard avec --password-stdin, ou à défaut dans la variable d'environnement ISOGRID_REGISTRY_PASSWORD, pour ne pas finir dans l'historique du shell ni dans un journal de CI. Utilisez un jeton en lecture sur les images plutôt que le mot de passe d'un compte :

# GitLab: a deploy token with read_registry
echo "$GITLAB_DEPLOY_TOKEN" | isogrid registries add --name gitlab --kind gitlab \
  --username gitlab+deploy-token-1 --password-stdin

# A self-hosted GitLab
echo "$TOKEN" | isogrid registries add --name gitlab-acme --kind gitlab \
  --host registry.git.acme.internal --username deployer --password-stdin

# GitHub Container Registry: a token with read:packages
echo "$GHCR_TOKEN" | isogrid registries add --name ghcr --kind github --username acme-bot --password-stdin

# Docker Hub: an access token
echo "$DOCKERHUB_TOKEN" | isogrid registries add --name hub --kind dockerhub --username acme --password-stdin

# Azure Container Registry
echo "$ACR_PASSWORD" | isogrid registries add --name acr --kind azure \
  --host acme.azurecr.io --username acme-pull --password-stdin

Les identifiants sont vérifiés auprès du registre avant d'être enregistrés, sauf avec --no-verify. test les vérifie à nouveau et sort avec 1 quand le registre les refuse. Un registre ne peut pas être supprimé tant que des applications déploient depuis lui.

Déployez ensuite une image depuis ce registre par sa référence complète :

isogrid apps create --name web --external-image registry.gitlab.com/acme/web:1.4 --registry gitlab --wait
isogrid apps update web --external-image registry.gitlab.com/acme/web:1.5 --registry gitlab --deploy --wait

Une image publique n'a besoin d'aucun registre : --external-image nginx:1.27. --image et --url restent réservés aux images du registre de la plateforme. Un fichier de stack choisit seul le registre d'après l'hôte de l'image, et ne demande --registry que lorsque plusieurs des vôtres servent cet hôte.

Commandes du quotidien

isogrid apps list                          # source, status, size and address of each
isogrid apps get <app> [--exact]           # one application in detail
isogrid apps status <app>                  # copies running and wanted, and why they differ
isogrid apps build <app> [--ref REF]       # build from git and deploy the result
isogrid apps deploy <app>                  # redeploy the current image, without building
isogrid apps stop <app>                    # scale to zero
isogrid apps start <app>                   # and back
isogrid apps scale <app> [--replicas N] [--tier SIZE]
isogrid apps tiers <app>                   # sizes its region offers, with prices
isogrid apps logs <app> [--follow]         # the deployment log
isogrid apps logs <app> --search QUERY     # search what the application printed
isogrid apps env <app>                     # environment variables, as a dotenv file
isogrid apps secrets <app>                 # secret names, never values
isogrid apps delete <app> [--yes]

build et deploy sont différentes. build récupère le nouveau code, le construit et déploie ce qu'elle a construit. deploy (ou redeploy) redémarre l'application à partir de l'image qu'elle a déjà, et ne récupère rien de nouveau depuis git. Les deux acceptent --wait, --follow et --timeout.

Un déploiement qui échoue revient à la version qui tournait : deploy peut donc être relancée sans risque, au pire l'application continue comme avant. Avec --wait, ce retour en arrière compte tout de même comme un échec.

status interroge le cluster maintenant, pas le dernier état enregistré par la plateforme. Quand des copies manquent, elle en donne la raison et liste les copies récentes avec leur nœud et leur erreur. C'est la première commande à lancer quand une application est en ligne mais pas en bonne santé.

get --exact ne correspond qu'à un slug, un nom ou un identifiant complet, et se termine avec le code 1 quand l'application n'existe pas. Les scripts l'utilisent comme test d'existence :

if isogrid apps get shop --exact --json > /dev/null 2>&1; then
  echo "shop exists"
fi

delete demande confirmation. Sans terminal pour la demander, comme dans un pipeline, elle refuse avec le code de sortie 2 sauf si vous passez --yes : une suppression sans surveillance est donc toujours écrite noir sur blanc par quelqu'un.

Rechercher dans les journaux

isogrid apps logs <app> affiche le journal de déploiement : ce que la plateforme a fait pour déployer l'application. Pour parcourir ce que l'application elle-même a écrit, faites une recherche :

isogrid apps logs <app> --search QUERY [--since 1h] [--limit 500] [--json]

Chaque résultat s'affiche sous la forme timestamp [replica] LEVEL message. Une requête est une liste de termes qui doivent tous être vrais :

isogrid apps logs api --search 'level:error -healthcheck' --since 1h
isogrid apps logs api --search '"payment failed" replica:2' --limit 50

--since accepte une durée (30m, 1h) ou une date RFC 3339. --limit est le nombre maximal de lignes renvoyées, jusqu'à 2000 ; quand davantage correspondent, les plus récentes sont gardées et la commande le signale. Les résultats vont sur la sortie standard et les remarques sur la sortie d'erreur, donc > errors.txt ne reçoit que des lignes.

Sans conservation des journaux, seul ce que les copies en cours détiennent encore peut être cherché, et un redéploiement repart de zéro. La commande indique quand la conservation est désactivée. Activez-la dans les réglages de l'application dans la console, ou avec un bloc logging json-file dans un fichier de stack.

Codes de sortie

Cas particuliers à connaître avant d'y être confronté

« is not a repository you have been given access to ». Le dépôt est connecté, mais via le compte de quelqu'un d'autre, qui ne vous l'a pas ouvert. Voir Dépôts Git.

La construction a réussi et --wait a quand même échoué. La nouvelle version a été construite puis n'est pas devenue saine, et la précédente a été remise en place. Le site est en ligne ; le nouveau code ne l'est pas. Consultez isogrid apps logs <app>.

--tag indique qu'il s'applique aux applications issues d'une image. L'application est construite depuis git, et ses images sont taguées par ses constructions. Utilisez plutôt --deploy --ref.

update --env-file n'a rien supprimé de ce que vous avez retiré du fichier. La fusion est le comportement par défaut. Ajoutez --replace-env lorsque le fichier doit constituer l'environnement complet.

Une valeur contenant $ est arrivée inchangée. C'est voulu. Rien n'est développé, car un mot de passe modifié à votre insu serait bien pire.