Extensions

Table des matières

Les extensions peuvent être utilisées pour rendre votre fichier Compose plus efficace et plus facile à maintenir.

Utilisez le préfixe x- comme élément de niveau supérieur pour modulariser les configurations que vous souhaitez réutiliser. Compose ignore tous les champs qui commencent par x-, c'est la seule exception où Compose ignore silencieusement les champs non reconnus.

Les extensions peuvent aussi être utilisées avec anchors et aliases.

Elles peuvent aussi être utilisées dans toute structure d'un fichier Compose où les clés définies par l'utilisateur ne sont pas attendues. Compose les utilise pour activer des fonctionnalités expérimentales, de la même façon que les navigateurs ajoutent le support pour fonctionnalités CSS personnalisées

Exemple 1

x-custom:
  foo:
    - bar
    - zot

services:
  webapp:
    image: example/webapp
    x-foo: bar

service:
  backend:
    deploy:
      placement:
        x-aws-role: "arn:aws:iam::XXXXXXXXXXXX:role/foo"
        x-aws-region: "eu-west-3"
        x-azure-region: "france-central"

Exemple 2

x-env: &env
  environment:
    - CONFIG_KEY
    - EXAMPLE_KEY
 
services:
  first:
    <<: *env
    image: my-image:latest
  second:
    <<: *env
    image: another-image:latest

Dans cet exemple, les variables d'environnement n'appartiennent à aucun des services. Elles ont été complètement extraites dans le champ d'extension x-env. Cela définit un nouveau nœud qui contient le champ environment. L'ancre YAML &env est utilisée pour que les deux services puissent référencer la valeur du champ d'extension comme *env.

Exemple 3

x-function: &function
 labels:
   function: "true"
 depends_on:
   - gateway
 networks:
   - functions
 deploy:
   placement:
     constraints:
       - 'node.platform.os == linux'
services:
 # Node.js donne des infos OS sur le nœud (Hôte)
 nodeinfo:
   <<: *function
   image: functions/nodeinfo:latest
   environment:
     no_proxy: "gateway"
     https_proxy: $https_proxy
 # Utilise `cat` pour renvoyer la réponse, fonction la plus rapide à exécuter.
 echoit:
   <<: *function
   image: functions/alpine:health
   environment:
     fprocess: "cat"
     no_proxy: "gateway"
     https_proxy: $https_proxy

Les services nodeinfo et echoit incluent tous deux l'extension x-function via l'ancre &function, puis définissent leur image et environnement spécifiques.

Exemple 4

En utilisant YAML merge il est aussi possible d'utiliser plusieurs extensions et de partager et remplacer des attributs supplémentaires pour des besoins spécifiques :

x-environment: &default-environment
  FOO: BAR
  ZOT: QUIX
x-keys: &keys
  KEY: VALUE
services:
  frontend:
    image: example/webapp
    environment: 
      << : [*default-environment, *keys]
      YET_ANOTHER: VARIABLE

Note

YAML merge s'applique seulement aux mappages, et ne peut pas être utilisé avec les séquences.

Dans l'exemple ci-dessus, les variables d'environnement sont déclarées en utilisant la syntaxe de mappage FOO: BAR, tandis que la syntaxe de séquence - FOO=BAR n'est valide que quand aucun fragment n'est impliqué.

Notes historiques informatives

Cette section est informative. Au moment de l'écriture, les préfixes suivants sont connus pour exister :

Préfixe	Fournisseur/Organisation
docker	Docker
kubernetes	Kubernetes

Spécifier les valeurs d'octets

Les valeurs expriment une valeur d'octet comme une chaîne au format {quantité}{unité d'octet} : Les unités supportées sont b (octets), k ou kb (kilo octets), m ou mb (méga octets) et g ou gb (giga octets).

Spécifier les durées

Les valeurs expriment une durée comme une chaîne sous la forme {valeur}{unité}. Les unités supportées sont us (microsecondes), ms (millisecondes), s (secondes), m (minutes) et h (heures). Les valeurs peuvent combiner plusieurs valeurs sans séparateur.

  10ms
  40s
  1m30s
  1h5m30s20ms