Secrets de construction

Table des matières

Un secret de construction est toute information sensible, comme un mot de passe ou un jeton d'API, consommée dans le cadre du processus de construction de votre application.

Les arguments de construction et les variables d'environnement ne sont pas appropriés pour transmettre des secrets à votre construction, car ils persistent dans l'image finale. Au lieu de cela, vous devriez utiliser des montages de secrets ou des montages SSH, qui exposent les secrets à vos constructions en toute sécurité.

Types de secrets de construction

Les montages de secrets sont des montages à usage général pour transmettre des secrets à votre construction. Un montage de secret prend un secret du client de construction et le rend temporairement disponible à l'intérieur du conteneur de construction, pour la durée de l'instruction de construction. C'est utile si, par exemple, votre construction doit communiquer avec un serveur d'artefacts privé ou une API.
Les montages SSH sont des montages à usage spécial pour rendre les sockets ou les clés SSH disponibles à l'intérieur des constructions. Ils sont couramment utilisés lorsque vous devez récupérer des référentiels Git privés dans vos constructions.
L'authentification Git pour les contextes distants est un ensemble de secrets prédéfinis pour lorsque vous construisez avec un contexte Git distant qui est également un référentiel privé. Ces secrets sont des secrets "de pré-vol" : ils ne sont pas consommés dans votre instruction de construction, mais ils sont utilisés pour fournir au constructeur les informations d'identification nécessaires pour récupérer le contexte.

Utilisation des secrets de construction

Pour les montages de secrets et les montages SSH, l'utilisation des secrets de construction est un processus en deux étapes. Vous devez d'abord transmettre le secret à la commande docker build, puis vous devez consommer le secret dans votre Dockerfile.

Pour transmettre un secret à une construction, utilisez l'indicateur docker build --secret , ou les options équivalentes pour Bake.

$ docker build --secret id=aws,src=$HOME/.aws/credentials .

variable "HOME" {
  default = null
}

target "default" {
  secret = [
    "id=aws,src=${HOME}/.aws/credentials"
  ]
}

Pour consommer un secret dans une construction et le rendre accessible à l'instruction RUN, utilisez l'indicateur --mount=type=secret dans le Dockerfile.

RUN --mount=type=secret,id=aws \
    AWS_SHARED_CREDENTIALS_FILE=/run/secrets/aws \
    aws s3 cp ...

Montages de secrets

Les montages de secrets exposent les secrets aux conteneurs de construction, sous forme de fichiers ou de variables d'environnement . Vous pouvez utiliser les montages de secrets pour transmettre des informations sensibles à vos constructions, telles que des jetons d'API, des mots de passe ou des clés SSH.

Sources

La source d'un secret peut être soit un fichier soit une variable d'environnement. Lorsque vous utilisez la CLI ou Bake, le type peut être détecté automatiquement. Vous pouvez également le spécifier explicitement avec type=file ou type=env.

L'exemple suivant monte la variable d'environnement KUBECONFIG sur l'ID de secret kube, en tant que fichier dans le conteneur de construction à /run/secrets/kube.

$ docker build --secret id=kube,env=KUBECONFIG .

Lorsque vous utilisez des secrets à partir de variables d'environnement, vous pouvez omettre le paramètre env pour lier le secret à un fichier portant le même nom que la variable. Dans l'exemple suivant, la valeur de la variable API_TOKEN est montée sur /run/secrets/API_TOKEN dans le conteneur de construction.

$ docker build --secret id=API_TOKEN .

Cible

Lors de la consommation d'un secret dans un Dockerfile, le secret est monté sur un fichier par défaut. Le chemin de fichier par défaut du secret, à l'intérieur du conteneur de construction, est /run/secrets/<id>. Vous pouvez personnaliser la façon dont les secrets sont montés dans le conteneur de construction à l'aide des options target et env pour l'indicateur RUN --mount dans le Dockerfile.

L'exemple suivant prend l'ID de secret aws et le monte sur un fichier à /run/secrets/aws dans le conteneur de construction.

RUN --mount=type=secret,id=aws \
    AWS_SHARED_CREDENTIALS_FILE=/run/secrets/aws \
    aws s3 cp ...

Pour monter un secret en tant que fichier avec un nom différent, utilisez l'option target dans l'indicateur --mount.

RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
    aws s3 cp ...

Pour monter un secret en tant que variable d'environnement au lieu d'un fichier, utilisez l'option env dans l'indicateur --mount.

RUN --mount=type=secret,id=aws-key-id,env=AWS_ACCESS_KEY_ID \
    --mount=type=secret,id=aws-secret-key,env=AWS_SECRET_ACCESS_KEY \
    --mount=type=secret,id=aws-session-token,env=AWS_SESSION_TOKEN \
    aws s3 cp ...

Il est possible d'utiliser les options target et env ensemble pour monter un secret à la fois en tant que fichier et en tant que variable d'environnement.

Montages SSH

Si les informations d'identification que vous souhaitez utiliser dans votre construction sont un socket d'agent SSH ou une clé, vous pouvez utiliser le montage SSH au lieu d'un montage de secret. Le clonage de référentiels Git privés est un cas d'utilisation courant pour les montages SSH.

L'exemple suivant clone un référentiel GitHub privé à l'aide d'un montage SSH Dockerfile .

# syntax=docker/dockerfile:1
FROM alpine
ADD [email protected]:me/myprivaterepo.git /src/

Pour transmettre une socket SSH à la construction, vous utilisez l'indicateur docker build --ssh , ou les options équivalentes pour Bake.

$ docker buildx build --ssh default .

Authentification Git pour les contextes distants

BuildKit prend en charge deux secrets de construction prédéfinis, GIT_AUTH_TOKEN et GIT_AUTH_HEADER. Utilisez-les pour spécifier les paramètres d'authentification HTTP lors de la construction avec des référentiels Git distants et privés, y compris :

Construire avec un référentiel Git privé comme contexte de construction
Récupérer des référentiels Git privés dans une construction avec ADD

Par exemple, supposons que vous ayez un projet GitLab privé à https://gitlab.com/example/todo-app.git, et que vous souhaitiez exécuter une construction en utilisant ce référentiel comme contexte de construction. Une commande docker build non authentifiée échoue car le constructeur n'est pas autorisé à extraire le référentiel :

$ docker build https://gitlab.com/example/todo-app.git
[+] Building 0.4s (1/1) FINISHED
 => ERROR [internal] load git source https://gitlab.com/example/todo-app.git
------
 > [internal] load git source https://gitlab.com/example/todo-app.git:
0.313 fatal: could not read Username for 'https://gitlab.com': terminal prompts disabled
------

Pour authentifier le constructeur auprès du serveur Git, définissez la variable d'environnement GIT_AUTH_TOKEN pour qu'elle contienne un jeton d'accès GitLab valide, et transmettez-la en tant que secret à la construction :

$ GIT_AUTH_TOKEN=$(cat gitlab-token.txt) docker build \
  --secret id=GIT_AUTH_TOKEN \
  https://gitlab.com/example/todo-app.git

Le GIT_AUTH_TOKEN fonctionne également avec ADD pour récupérer des référentiels Git privés dans le cadre de votre construction :

FROM alpine
ADD https://gitlab.com/example/todo-app.git /src

Schéma d'authentification HTTP

Par défaut, l'authentification Git sur HTTP utilise le schéma d'authentification Bearer :

Authorization: Bearer <GIT_AUTH_TOKEN>

Si vous devez utiliser un schéma Basic, avec un nom d'utilisateur et un mot de passe, vous pouvez définir le secret de construction GIT_AUTH_HEADER :

$ export GIT_AUTH_TOKEN=$(cat gitlab-token.txt)
$ export GIT_AUTH_HEADER=basic
$ docker build \
  --secret id=GIT_AUTH_TOKEN \
  --secret id=GIT_AUTH_HEADER \
  https://gitlab.com/example/todo-app.git

BuildKit ne prend actuellement en charge que les schémas Bearer et Basic.

Plusieurs hôtes

Vous pouvez définir les secrets GIT_AUTH_TOKEN et GIT_AUTH_HEADER par hôte , ce qui vous permet d'utiliser différents paramètres d'authentification pour différents noms d'hôte. Pour spécifier un nom d'hôte, ajoutez le nom d'hôte en tant que suffixe à l'ID du secret :

$ export GITLAB_TOKEN=$(cat gitlab-token.txt)
$ export GERRIT_TOKEN=$(cat gerrit-username-password.txt)
$ export GERRIT_SCHEME=basic
$ docker build \
  --secret id=GIT_AUTH_TOKEN.gitlab.com,env=GITLAB_TOKEN \
  --secret id=GIT_AUTH_TOKEN.gerrit.internal.example,env=GERRIT_TOKEN \
  --secret id=GIT_AUTH_HEADER.gerrit.internal.example,env=GERRIT_SCHEME \
  https://gitlab.com/example/todo-app.git