# Secretos de compilación Un secreto de compilación es cualquier fragmento de información sensible, como una contraseña o un token de API, que se consume como parte del proceso de compilación de tu aplicación. Los argumentos de compilación y las variables de entorno no son adecuados para pasar secretos a tu compilación porque persisten en la imagen final. En su lugar, debes utilizar montajes de secretos o montajes SSH, que exponen los secretos a tus compilaciones de forma segura. ## Tipos de secretos de compilación - Los [montajes de secretos](#montajes-de-secretos) son montajes de uso general para pasar secretos a tu compilación. Un montaje de secreto toma un secreto del cliente de compilación y lo hace disponible temporalmente dentro del contenedor de compilación, durante la duración de la instrucción de compilación. Esto es útil si, por ejemplo, tu compilación necesita comunicarse con un servidor de artefactos privado o una API. - Los [montajes SSH](#montajes-ssh) son montajes de propósito especial para hacer que los sockets o claves SSH estén disponibles dentro de las compilaciones. Se utilizan comúnmente cuando necesitas descargar repositorios Git privados en tus compilaciones. - La [autenticación Git para contextos remotos](#autenticación-git-para-contextos-remotos) es un conjunto de secretos predefinidos para cuando compilas con un contexto Git remoto que también es un repositorio privado. Estos secretos son secretos previos (pre-flight): no se consumen dentro de tu instrucción de compilación, sino que se utilizan para proporcionar al builder las credenciales necesarias para descargar el contexto. ## Usar secretos de compilación Para los montajes de secretos y los montajes SSH, el uso de secretos de compilación es un proceso de dos pasos. Primero debes pasar el secreto al comando `docker build`, y luego debes consumir el secreto en tu Dockerfile. Para pasar un secreto a una compilación, utiliza la [opción `docker build --secret`](/reference/cli/docker/buildx/build/#secret), o las opciones equivalentes para [Bake](/build/bake/reference/#targetsecret). **CLI** ```console $ docker build --secret id=aws,src=$HOME/.aws/credentials . ``` **Bake** ```hcl variable "HOME" { default = null } target "default" { secret = [ "id=aws,src=${HOME}/.aws/credentials" ] } ``` Para consumir un secreto en una compilación y hacerlo accesible para la instrucción `RUN`, utiliza la opción [`--mount=type=secret`](/reference/dockerfile/#run---mounttypesecret) en el Dockerfile. ```dockerfile RUN --mount=type=secret,id=aws \ AWS_SHARED_CREDENTIALS_FILE=/run/secrets/aws \ aws s3 cp ... ``` ## Montajes de secretos Los montajes de secretos exponen secretos a los contenedores de compilación, como archivos o variables de entorno. Puedes usar montajes de secretos para pasar información confidencial a tus compilaciones, como tokens de API, contraseñas o claves SSH. ### Orígenes El origen de un secreto puede ser un [archivo](/reference/cli/docker/buildx/build/#file) o una [variable de entorno](/reference/cli/docker/buildx/build/#typeenv). Cuando utilizas la CLI o Bake, el tipo se puede detectar automáticamente. También puedes especificarlo explícitamente con `type=file` o `type=env`. El siguiente ejemplo monta la variable de entorno `KUBECONFIG` con el ID de secreto `kube`, como un archivo en el contenedor de compilación en `/run/secrets/kube`. ```console $ docker build --secret id=kube,env=KUBECONFIG . ``` Cuando utilizas secretos de variables de entorno, puedes omitir el parámetro `env` para vincular el secreto a un archivo con el mismo nombre que la variable. En el siguiente ejemplo, el valor de la variable `API_TOKEN` se monta en `/run/secrets/API_TOKEN` en el contenedor de compilación. ```console $ docker build --secret id=API_TOKEN . ``` ### Destino Al consumir un secreto en un Dockerfile, el secreto se monta en un archivo por defecto. La ruta de archivo predeterminada del secreto, dentro del contenedor de compilación, es `/run/secrets/`. Puedes personalizar cómo se montan los secretos en el contenedor de compilación utilizando las opciones `target` y `env` para la opción `RUN --mount` en el Dockerfile. El siguiente ejemplo toma el ID de secreto `aws` y lo monta en un archivo en `/run/secrets/aws` en el contenedor de compilación. ```dockerfile RUN --mount=type=secret,id=aws \ AWS_SHARED_CREDENTIALS_FILE=/run/secrets/aws \ aws s3 cp ... ``` Para montar un secreto como un archivo con un nombre diferente, utiliza la opción `target` en la opción `--mount`. ```dockerfile RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \ aws s3 cp ... ``` Para montar un secreto como una variable de entorno en lugar de un archivo, utiliza la opción `env` en la opción `--mount`. ```dockerfile 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 ... ``` Es posible utilizar las opciones `target` y `env` juntas para montar un secreto tanto como archivo como variable de entorno. ## Montajes SSH Si la credencial que deseas utilizar en tu compilación es un socket de agente SSH o una clave, puedes utilizar el montaje SSH en lugar de un montaje de secreto. Clonar repositorios Git privados es un caso de uso común para los montajes SSH. El siguiente ejemplo clona un repositorio privado de GitHub utilizando un [montaje SSH de Dockerfile](/reference/dockerfile/#run---mounttypessh). ```dockerfile # syntax=docker/dockerfile:1 FROM alpine ADD git@github.com:me/myprivaterepo.git /src/ ``` Para pasar un socket SSH a la compilación, utilizas la [opción `docker build --ssh`](/reference/cli/docker/buildx/build/#ssh), o las opciones equivalentes para [Bake](/build/bake/reference/#targetssh). ```console $ docker buildx build --ssh default . ``` ## Autenticación Git para contextos remotos BuildKit admite dos secretos de compilación predefinidos, `GIT_AUTH_TOKEN` y `GIT_AUTH_HEADER`. Úsalos para especificar parámetros de autenticación HTTP al compilar con repositorios Git privados y remotos, incluyendo: - Compilar con un repositorio Git privado como contexto de compilación - Obtener repositorios Git privados en una compilación con `ADD` Por ejemplo, supongamos que tienes un repositorio privado de GitHub en `https://github.com/example/todo-app.git` y deseas ejecutar una compilación utilizando ese repositorio como contexto de compilación. Un comando `docker build` sin autenticación fallará porque el builder no está autorizado para descargar el repositorio: ```console $ docker build https://github.com/example/todo-app.git [+] Building 0.4s (1/1) FINISHED => ERROR [internal] load git source https://github.com/example/todo-app.git ------ > [internal] load git source https://github.com/example/todo-app.git: 0.313 fatal: could not read Username for 'https://github.com': terminal prompts disabled ------ ``` Para autenticar el builder en GitHub, establece la variable de entorno `GIT_AUTH_TOKEN` para que contenga un token de acceso válido de GitHub y pásala como un secreto a la compilación: ```console $ GIT_AUTH_TOKEN=$(gh auth token) docker build \ --secret id=GIT_AUTH_TOKEN \ https://github.com/example/todo-app.git ``` El secreto `GIT_AUTH_TOKEN` también funciona con `ADD` para obtener repositorios Git privados como parte de tu compilación: ```dockerfile FROM alpine ADD https://github.com/example/todo-app.git /src ``` ### Esquema de autenticación HTTP BuildKit admite dos secretos de autenticación Git: - **`GIT_AUTH_TOKEN`**: Utiliza autenticación básica (Basic auth) con un nombre de usuario fijo de `x-access-token` (el valor predeterminado al estilo de GitHub) - **`GIT_AUTH_HEADER`**: Utiliza el valor de cabecera de autorización sin procesar que proporciones (funciona con cualquier proveedor de Git) #### Uso de GIT_AUTH_TOKEN (por ejemplo, GitHub) Cuando usas `GIT_AUTH_TOKEN`, BuildKit construye una cabecera de autenticación básica utilizando `x-access-token` como usuario: ```http Authorization: Basic ")> ``` Este método funciona para proveedores que aceptan el patrón de autenticación básica `x-access-token`, como GitHub. Ejemplo de uso: ```console $ export GIT_AUTH_TOKEN=$(gh auth token) $ docker build \ --secret id=GIT_AUTH_TOKEN \ https://github.com/example/todo-app.git ``` #### Uso de GIT_AUTH_HEADER (cabecera de autorización personalizada) Cuando usas `GIT_AUTH_HEADER`, BuildKit utiliza el valor exacto que proporcionas como cabecera `Authorization`: ```http Authorization: ``` Ejemplo de uso con el token de GitLab CI/CD: ```console $ export GIT_AUTH_HEADER="Basic $(echo -n "gitlab-ci-token:${CI_JOB_TOKEN}" | base64)" $ docker build \ --secret id=GIT_AUTH_HEADER \ https://gitlab.com/example/todo-app.git ``` ### Múltiples hosts Puedes configurar los secretos `GIT_AUTH_TOKEN` y `GIT_AUTH_HEADER` en función de cada host, lo que te permite usar diferentes parámetros de autenticación para diferentes nombres de host. Para especificar un nombre de host, añade el nombre de host como sufijo al ID del secreto: ```console $ export GITHUB_TOKEN=$(gh auth token) $ export GITLAB_AUTH_HEADER="Basic $(echo -n "gitlab-ci-token:${CI_JOB_TOKEN}" | base64)" $ docker build \ --secret id=GIT_AUTH_TOKEN.github.com,env=GITHUB_TOKEN \ --secret id=GIT_AUTH_HEADER.gitlab.com,env=GITLAB_AUTH_HEADER \ https://github.com/example/todo-app.git ``` ## Autenticación HTTP para `COPY` y `ADD` Para usar secretos en los comandos `COPY` o `ADD`, puedes crear secretos `HTTP_AUTH_TOKEN_` o `HTTP_AUTH_HEADER_` para usarlos cuando accedas al host especificado. Por ejemplo, `HTTP_AUTH_TOKEN_127.0.0.1=token` hará que las solicitudes a `127.0.0.1` añadan una cabecera `Authorization: Bearer token`. Estas variables siguen la misma convención que el manejo del [esquema de autenticación Git HTTP](#esquema-de-autenticación-http).