Variables dans Bake

Vous pouvez définir et utiliser des variables dans un fichier Bake pour définir des valeurs d'attributs, les interpoler dans d'autres valeurs et effectuer des opérations arithmétiques. Les variables peuvent être définies avec des valeurs par défaut et peuvent être surchargées avec des variables d'environnement.

Utiliser des variables comme valeurs d'attributs

Utilisez le bloc variable pour définir une variable.

variable "TAG" {
  default = "docker.io/username/webapp:latest"
}

L'exemple suivant montre comment utiliser la variable TAG dans une cible.

target "webapp" {
  context = "."
  dockerfile = "Dockerfile"
  tags = [ TAG ]
}

Interpoler des variables dans des valeurs

Bake prend en charge l'interpolation de chaînes de variables dans des valeurs. Vous pouvez utiliser la syntaxe ${} pour interpoler une variable dans une valeur. L'exemple suivant définit une variable TAG avec la valeur latest.

variable "TAG" {
  default = "latest"
}

Pour interpoler la variable TAG dans la valeur d'un attribut, utilisez la syntaxe ${TAG}.

group "default" {
  targets = [ "webapp" ]
}

variable "TAG" {
  default = "latest"
}

target "webapp" {
  context = "."
  dockerfile = "Dockerfile"
  tags = ["docker.io/username/webapp:${TAG}"]
}

L'impression du fichier Bake avec l'indicateur --print affiche la valeur interpolée dans la configuration de build résolue.

$ docker buildx bake --print

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

Valider les variables

Pour vérifier que la valeur d'une variable est conforme à un type, une plage de valeurs ou une autre condition attendus, vous pouvez définir des règles de validation personnalisées à l'aide du bloc validation.

Dans l'exemple suivant, la validation est utilisée pour appliquer une contrainte numérique sur la valeur d'une variable ; la variable PORT doit être supérieure ou égale à 1024.

# Définir une variable `PORT` avec une valeur par défaut et une règle de validation
variable "PORT" {
  default = 3000  # Valeur par défaut attribuée à `PORT`

  # Bloc de validation pour s'assurer que `PORT` est un nombre valide dans la plage acceptable
  validation {
    condition = PORT >= 1024  # S'assurer que `PORT` est au moins 1024
    error_message = "La variable 'PORT' doit être supérieure ou égale à 1024."  # Message d'erreur pour les valeurs non valides
  }
}

Si l'expression condition est évaluée à false, la valeur de la variable est considérée comme non valide, ce qui entraîne l'échec de l'invocation de la construction et l'émission du message error_message. Par exemple, si PORT=443, la condition est évaluée à false, et l'erreur est levée.

Les valeurs sont converties dans le type attendu avant que la validation ne soit définie. Cela garantit que toutes les surcharges définies avec des variables d'environnement fonctionnent comme prévu.

Valider plusieurs conditions

Pour évaluer plus d'une condition, définissez plusieurs blocs validation pour la variable. Toutes les conditions doivent être true.

Voici un exemple :

# Définir une variable `VAR` avec plusieurs règles de validation
variable "VAR" {
  # Premier bloc de validation : S'assurer que la variable n'est pas vide
  validation {
    condition = VAR != ""
    error_message = "La variable 'VAR' ne doit pas être vide."
  }

  # Deuxième bloc de validation : S'assurer que la valeur ne contient que des caractères alphanumériques
  validation {
    # VAR et la correspondance de l'expression régulière doivent être identiques :
    condition = VAR == regex("[a-zA-Z0-9]+", VAR)
    error_message = "La variable 'VAR' ne peut contenir que des lettres et des chiffres."
  }
}

Cet exemple impose :

• La variable ne doit pas être vide.
• La variable doit correspondre à un jeu de caractères spécifique.

Pour les entrées non valides comme VAR="hello@world", la validation échouerait.

Valider les dépendances de variables

Vous pouvez référencer d'autres variables Bake dans votre expression de condition, ce qui permet des validations qui appliquent des dépendances entre les variables. Cela garantit que les variables dépendantes sont correctement définies avant de continuer.

Voici un exemple :

# Définir une variable `FOO`
variable "FOO" {}

# Définir une variable `BAR` avec une règle de validation qui référence `FOO`
variable "BAR" {
  # Bloc de validation pour s'assurer que `FOO` est défini si `BAR` est utilisé
  validation {
    condition = FOO != ""  # Vérifier si `FOO` n'est pas une chaîne vide
    error_message = "La variable 'BAR' nécessite que 'FOO' soit défini."
  }
}

Cette configuration garantit que la variable BAR ne peut être utilisée que si FOO a reçu une valeur non vide. Tenter de construire sans définir FOO déclenchera l'erreur de validation.

Échapper l'interpolation de variable

Si vous souhaitez contourner l'interpolation de variable lors de l'analyse de la définition Bake, utilisez des signes dollar doubles ($${VARIABLE}).

target "webapp" {
  dockerfile-inline = <<EOF
  FROM alpine
  ARG TARGETARCH
  RUN echo "Building for $${TARGETARCH/amd64/x64}"
  EOF
  platforms = ["linux/amd64", "linux/arm64"]
}

$ docker buildx bake --progress=plain
...
#8 [linux/arm64 2/2] RUN echo "Building for arm64"
#8 0.036 Building for arm64
#8 DONE 0.0s

#9 [linux/amd64 2/2] RUN echo "Building for x64"
#9 0.046 Building for x64
#9 DONE 0.1s
...

Utiliser des variables dans des variables à travers les fichiers

Lorsque plusieurs fichiers sont spécifiés, un fichier peut utiliser des variables définies dans un autre fichier. Dans l'exemple suivant, le fichier vars.hcl définit une variable BASE_IMAGE avec une valeur par défaut de docker.io/library/alpine.

variable "BASE_IMAGE" {
  default = "docker.io/library/alpine"
}

Le fichier docker-bake.hcl suivant définit une variable BASE_LATEST qui référence la variable BASE_IMAGE.

variable "BASE_LATEST" {
  default = "${BASE_IMAGE}:latest"
}

target "webapp" {
  contexts = {
    base = BASE_LATEST
  }
}

Lorsque vous imprimez la configuration de build résolue, en utilisant l'indicateur -f pour spécifier les fichiers vars.hcl et docker-bake.hcl, vous voyez que la variable BASE_LATEST est résolue en docker.io/library/alpine:latest.

$ docker buildx bake -f vars.hcl -f docker-bake.hcl --print app

{
  "target": {
    "webapp": {
      "context": ".",
      "contexts": {
        "base": "docker.io/library/alpine:latest"
      },
      "dockerfile": "Dockerfile"
    }
  }
}

Ressources supplémentaires

Voici quelques ressources supplémentaires qui montrent comment vous pouvez utiliser des variables dans Bake :

• Vous pouvez surcharger les valeurs de variable en utilisant des variables d'environnement. Voir Surcharger les configurations pour plus d'informations.
• Vous pouvez vous référer et utiliser des variables globales dans les fonctions. Voir Fonctions HCL
• Vous pouvez utiliser des valeurs de variables lors de l'évaluation d'expressions. Voir Évaluation d'expression