⚠️ Traduction non officielle - Cette documentation est une traduction communautaire non officielle de Docker.

Surcharger les configurations

Table des matières

Bake prend en charge le chargement des définitions de build à partir de fichiers, mais parfois vous avez besoin d'encore plus de flexibilité pour configurer ces définitions. Par exemple, vous pourriez vouloir surcharger un attribut lors de la construction dans un environnement particulier ou pour une cible spécifique.

La liste suivante d'attributs peut être surchargée :

  • args
  • attest
  • cache-from
  • cache-to
  • context
  • contexts
  • dockerfile
  • entitlements
  • labels
  • network
  • no-cache
  • output
  • platform
  • pull
  • secrets
  • ssh
  • tags
  • target

Pour surcharger ces attributs, vous pouvez utiliser les méthodes suivantes :

Surcharges de fichiers

Vous pouvez charger plusieurs fichiers Bake qui définissent des configurations de build pour vos cibles. C'est utile lorsque vous souhaitez séparer les configurations dans différents fichiers pour une meilleure organisation, ou pour surcharger conditionnellement les configurations en fonction des fichiers chargés.

Recherche de fichiers par défaut

Vous pouvez utiliser l'indicateur --file ou -f pour spécifier les fichiers à charger. Si vous ne spécifiez aucun fichier, Bake utilisera l'ordre de recherche suivant :

  1. compose.yaml
  2. compose.yml
  3. docker-compose.yml
  4. docker-compose.yaml
  5. docker-bake.json
  6. docker-bake.hcl
  7. docker-bake.override.json
  8. docker-bake.override.hcl

Si plus d'un fichier Bake est trouvé, tous les fichiers sont chargés et fusionnés en une seule définition. Les fichiers sont fusionnés selon l'ordre de recherche.

$ docker buildx bake --print
[+] Building 0.0s (1/1) FINISHED                                                                                                                                                                                            
 => [internal] load local bake definitions                                                                                                                                                                             0.0s
 => => reading compose.yaml 45B / 45B                                                                                                                                                                                  0.0s
 => => reading docker-bake.hcl 113B / 113B                                                                                                                                                                             0.0s
 => => reading docker-bake.override.hcl 65B / 65B

Si les fichiers fusionnés contiennent des définitions d'attributs en double, ces définitions sont soit fusionnées, soit surchargées par la dernière occurrence, en fonction de l'attribut.

Bake tentera de charger tous les fichiers dans l'ordre où ils sont trouvés. Si plusieurs fichiers définissent la même cible, les attributs sont soit fusionnés, soit surchargés. Dans le cas de surcharges, la dernière chargée prévaut.

Par exemple, étant donné les fichiers suivants :

docker-bake.hcl 
variable "TAG" {
  default = "foo"
}

target "default" {
  tags = ["username/my-app:${TAG}"]
}
docker-bake.override.hcl 
variable "TAG" {
  default = "bar"
}

Puisque docker-bake.override.hcl est chargé en dernier dans l'ordre de recherche par défaut, la variable TAG est surchargée avec la valeur bar.

$ docker buildx bake --print
{
  "target": {
    "default": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": ["username/my-app:bar"]
    }
  }
}

Surcharges de fichiers manuelles

Vous pouvez utiliser l'indicateur --file pour spécifier explicitement quels fichiers charger, et l'utiliser comme un moyen d'appliquer conditionnellement des fichiers de surcharge.

Par exemple, vous pouvez créer un fichier qui définit un ensemble de configurations pour un environnement spécifique, et le charger uniquement lors de la construction pour cet environnement. L'exemple suivant montre comment charger un fichier override.hcl qui définit la variable TAG sur bar. La variable TAG est ensuite utilisée dans la cible default.

docker-bake.hcl 
variable "TAG" {
  default = "foo"
}

target "default" {
  tags = ["username/my-app:${TAG}"]
}
overrides.hcl 
variable "TAG" {
  default = "bar"
}

L'impression de la configuration de build sans l'indicateur --file montre que la variable TAG est définie sur la valeur par défaut foo.

$ docker buildx bake --print
{
  "target": {
    "default": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": [
        "username/my-app:foo"
      ]
    }
  }
}

L'utilisation de l'indicateur --file pour charger le fichier overrides.hcl surcharge la variable TAG avec la valeur bar.

$ docker buildx bake -f docker-bake.hcl -f overrides.hcl --print
{
  "target": {
    "default": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": [
        "username/my-app:bar"
      ]
    }
  }
}

Ligne de commande

Vous pouvez également surcharger les configurations de cible depuis la ligne de commande avec l'indicateur --set :

# docker-bake.hcl
target "app" {
  args = {
    mybuildarg = "foo"
  }
}
$ docker buildx bake --set app.args.mybuildarg=bar --set app.platform=linux/arm64 app --print

{
  "group": {
    "default": {
      "targets": ["app"]
    }
  },
  "target": {
    "app": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "mybuildarg": "bar"
      },
      "platforms": ["linux/arm64"]
    }
  }
}

La syntaxe de correspondance de motifs définie dans https://golang.org/pkg/path/#Match est également prise en charge :

$ docker buildx bake --set foo*.args.mybuildarg=value  # surcharge l'argument de build pour toutes les cibles commençant par "foo"
$ docker buildx bake --set *.platform=linux/arm64      # surcharge la plateforme pour toutes les cibles
$ docker buildx bake --set foo*.no-cache               # contourne la mise en cache uniquement pour les cibles commençant par "foo"

La liste complète des attributs qui peuvent être surchargés avec --set est :

  • args
  • attest
  • cache-from
  • cache-to
  • context
  • contexts
  • dockerfile
  • entitlements
  • labels
  • network
  • no-cache
  • output
  • platform
  • pull
  • secrets
  • ssh
  • tags
  • target

Variables d'environnement

Vous pouvez également utiliser des variables d'environnement pour surcharger les configurations.

Bake vous permet d'utiliser des variables d'environnement pour surcharger la valeur d'un bloc variable. Seuls les blocs variable peuvent être surchargés avec des variables d'environnement. Cela signifie que vous devez définir les variables dans le fichier bake, puis définir la variable d'environnement avec le même nom pour la surcharger.

L'exemple suivant montre comment vous pouvez définir une variable TAG avec une valeur par défaut dans le fichier Bake, et la surcharger avec une variable d'environnement.

variable "TAG" {
  default = "latest"
}

target "default" {
  context = "."
  dockerfile = "Dockerfile"
  tags = ["docker.io/username/webapp:${TAG}"]
}
$ export TAG=$(git rev-parse --short HEAD)
$ docker buildx bake --print webapp

La variable TAG est surchargée avec la valeur de la variable d'environnement, qui est le hachage de commit court généré par git rev-parse --short HEAD.

{
  "group": {
    "default": {
      "targets": ["webapp"]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": ["docker.io/username/webapp:985e9e9"]
    }
  }
}

Coercition de type

La surcharge de variables non-chaînes avec des variables d'environnement est prise en charge. Les valeurs passées en tant que variables d'environnement sont d'abord converties en types appropriés.

L'exemple suivant définit une variable PORT. La cible backend utilise la variable PORT telle quelle, et la cible frontend utilise la valeur de PORT incrémentée de un.

variable "PORT" {
  default = 3000
}

group "default" {
  targets = ["backend", "frontend"]
}

target "backend" {
  args = {
    PORT = PORT
  }
}

target "frontend" {
  args = {
    PORT = add(PORT, 1)
  }
}

Surcharger PORT en utilisant une variable d'environnement forcera d'abord la valeur dans le type attendu, un entier, avant que l'expression dans la cible frontend ne s'exécute.

$ PORT=7070 docker buildx bake --print

{
  "group": {
    "default": {
      "targets": [
        "backend",
        "frontend"
      ]
    }
  },
  "target": {
    "backend": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "PORT": "7070"
      }
    },
    "frontend": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "PORT": "7071"
      }
    }
  }
}