Uso de políticas de compilación

Las políticas de compilación validan las entradas antes de que se ejecuten las compilaciones. Esta guía cubre cómo desarrollar políticas de forma iterativa y aplicarlas a compilaciones reales con docker buildx build y docker buildx bake.

Requisitos previos

Buildx 0.31.0 o posterior - Check your version: docker buildx version
BuildKit 0.26.0 o posterior - Verify with: docker buildx inspect --bootstrap

Si usas Docker Desktop, asegúrate de estar en una versión que incluya estas actualizaciones.

Flujo de trabajo para el desarrollo de políticas

Buildx carga automáticamente las políticas que coinciden con el nombre de tu Dockerfile. Cuando compilas con Dockerfile, Buildx busca Dockerfile.rego en el mismo directorio. Para un archivo llamado app.Dockerfile, busca app.Dockerfile.rego. Consulta la sección Avanzado: Configuración de políticas para conocer las opciones de configuración y la carga manual de políticas.

Escribir políticas es un proceso iterativo:

Comienza con una política básica que deniegue todo.
Compila con logs de depuración para ver qué entradas utiliza tu Dockerfile.
Añade reglas para permitir fuentes específicas basadas en la salida de depuración.
Prueba y ajusta.

Ver las entradas de tu Dockerfile

Para ver las entradas a las que hace referencia tu Dockerfile (imágenes, repositorios Git, descargas HTTP), realiza la compilación con logs de depuración:

$ docker buildx build --progress=plain --policy log-level=debug .

Ejemplo de salida para una fuente de imagen:

#1 0.010 checking policy for source docker-image://alpine:3.19 (linux/arm64)
#1 0.011 policy input: {
#1 0.011   "env": {
#1 0.011     "filename": "."
#1 0.011   },
#1 0.011   "image": {
#1 0.011     "ref": "docker.io/library/alpine:3.19",
#1 0.011     "host": "docker.io",
#1 0.011     "repo": "alpine",
#1 0.011     "tag": "3.19",
#1 0.011     "platform": "linux/arm64"
#1 0.011   }
#1 0.011 }
#1 0.011 unknowns for policy evaluation: [input.image.checksum input.image.labels ...]
#1 0.012 policy decision for source docker-image://alpine:3.19: ALLOW

Esto muestra la estructura de entrada completa, qué campos no se han resuelto y la decisión de la política para cada fuente. Consulta la Referencia de inputs para conocer todos los campos disponibles.

Probar políticas con policy eval

Utiliza docker buildx policy eval para probar si tu política permite una fuente específica sin necesidad de ejecutar una compilación completa.

Nota: docker buildx policy eval prueba la fuente especificada como argumento. No analiza tu Dockerfile para evaluar todas las entradas; para eso, compila con --progress=plain.

Prueba si tu política permite el contexto local:

$ docker buildx policy eval .

Si no hay salida, significa que la política permitió la fuente. Si se deniega, verás:

ERROR: policy denied

Probar otras fuentes:

$ docker buildx policy eval https://example.com              # Probar HTTP
$ docker buildx policy eval https://github.com/org/repo.git  # Probar Git

Por defecto, --print muestra la información de referencia analizada a partir de la cadena de texto de la fuente (como repo, tag, host) sin realizar consultas a los registros. Para inspeccionar metadatos que requieren consultar la fuente (como labels, checksum o hasProvenance), especifica qué campos obtener con --fields:

$ docker buildx policy eval --print --fields image.labels docker-image://alpine:3.19

Se pueden especificar múltiples campos en una lista separada por comas.

Ejemplo de desarrollo iterativo

A continuación se muestra un flujo de trabajo práctico para desarrollar políticas:

Comienza con una política básica que deniegue todo:

Dockerfile.rego

package docker

default allow := false

allow if input.local

decision := {"allow": allow}

Compila con logs de depuración para ver qué entradas utiliza tu Dockerfile:

$ docker buildx build --progress=plain --policy log-level=debug .

La salida muestra la imagen denegada y su estructura de entrada:

#1 0.026 checking policy for source docker-image://docker.io/library/alpine:3.19
#1 0.027 policy input: {
#1 0.027   "image": {
#1 0.027     "repo": "alpine",
#1 0.027     "tag": "3.19",
#1 0.027     ...
#1 0.027   }
#1 0.027 }
#1 0.028 policy decision for source docker-image://alpine:3.19: DENY
#1 ERROR: source "docker-image://alpine:3.19" not allowed by policy

Añade una regla que permita la imagen alpine:

allow if {
    input.image.repo == "alpine"
}

Compila de nuevo para verificar que la política funcione:
$ docker buildx build .

Si falla, consulta Depuración para obtener ayuda en la resolución de problemas.

Uso de políticas con `docker build`

Una vez que hayas desarrollado y probado tu política, aplícala a compilaciones reales.

Uso básico

Crea una política junto a tu Dockerfile:

Dockerfile

FROM alpine:3.19
RUN echo "hello"

Dockerfile.rego

package docker

default allow := false

allow if input.local

allow if {
    input.image.repo == "alpine"
}

decision := {"allow": allow}

Compila normalmente:

$ docker buildx build .

Buildx carga la política automáticamente y valida la imagen alpine:3.19 antes de compilar.

Compilar con diferentes nombres de Dockerfile

Especifica el Dockerfile con -f:

$ docker buildx build -f app.Dockerfile .

Buildx buscará app.Dockerfile.rego en el mismo directorio.

Compilar con política manual

Añade una política adicional a la automática:

$ docker buildx build --policy filename=extra-checks.rego .

Tanto Dockerfile.rego (automática) como extra-checks.rego (manual) deben cumplirse.

Compilar sin política automática

Utiliza únicamente la política que especifiques:

$ docker buildx build --policy reset=true,filename=strict.rego .

Uso de políticas con bake

Bake admite la carga automática de políticas al igual que docker buildx build. Coloca Dockerfile.rego junto a tu Dockerfile y ejecuta:

$ docker buildx bake

Política manual en archivos bake

Especifica políticas adicionales en tu docker-bake.hcl:

docker-bake.hcl

target "default" {
  dockerfile = "Dockerfile"
  policy = ["extra.rego"]
}

El atributo policy acepta una lista de archivos de políticas. Bake carga estos archivos además de la política automática Dockerfile.rego (si existe).

Múltiples políticas en bake

docker-bake.hcl

target "webapp" {
  dockerfile = "Dockerfile"
  policy = [
    "shared/base-policy.rego",
    "security/image-signing.rego"
  ]
}

Todas las políticas deben cumplirse para que el objetivo se compile correctamente.

Diferentes políticas por target

Aplica diferentes reglas de validación a diferentes objetivos:

docker-bake.hcl

target "development" {
  dockerfile = "dev.Dockerfile"
  policy = ["policies/permissive.rego"]
}

target "production" {
  dockerfile = "prod.Dockerfile"
  policy = ["policies/strict.rego", "policies/signing-required.rego"]
}

Compila con el objetivo correspondiente:

$ docker buildx bake development  # Utiliza la política permisiva
$ docker buildx bake production   # Utiliza las políticas estrictas

Bake con opciones de política

Actualmente, bake no admite opciones de política (reset, strict, disabled) en el archivo HCL. Utiliza banderas de línea de comandos en su lugar:

$ docker buildx bake --policy disabled=true production

Pruebas en CI/CD

Valida las políticas en la integración continua ejecutando compilaciones con la bandera --policy. Para realizar pruebas unitarias de las políticas antes de ejecutar las compilaciones, consulta Probar políticas de compilación.

Probar políticas durante las compilaciones de CI:

.github/workflows/test-policies.yml

name: Test Build Policies
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: docker/setup-buildx-action@v4
      - name: Test build with policy
        run: docker buildx build --policy strict=true .

Esto garantiza que los cambios en las políticas no rompan las compilaciones y que las nuevas reglas funcionen como se espera. La bandera strict=true hace que la compilación falle si las políticas no se cargan (por ejemplo, si la instancia de BuildKit utilizada por la compilación es demasiado antigua y no admite políticas).

Avanzado: Configuración de políticas

Esta sección cubre mecanismos avanzados de carga y opciones de configuración de políticas.

Carga automática de políticas

project/
├── Dockerfile
├── Dockerfile.rego          # Se carga automáticamente para Dockerfile
├── app.Dockerfile
├── app.Dockerfile.rego      # Se carga automáticamente para app.Dockerfile
└── src/

Esta carga automática significa que no necesitas banderas de línea de comandos en la mayoría de los casos. Crea el archivo de política junto a tu Dockerfile y compila:

$ docker buildx build .

Buildx detecta Dockerfile.rego y lo evalúa antes de ejecutar la compilación.

Note
Los archivos de políticas deben estar en el mismo directorio que el Dockerfile que validan. Buildx no busca en directorios principales ni en subdirectorios.

Cuando las políticas no se cargan

Si Buildx no puede encontrar un archivo .rego coincidente, la compilación continúa sin la evaluación de la política. Para exigir políticas y fallar si no se encuentra ninguna, utiliza el modo estricto:

$ docker buildx build --policy strict=true .

Esto hace que la compilación falle si no se carga ninguna política o si el demonio BuildKit no admite políticas.

Configuración manual de políticas

La bandera --policy te permite especificar políticas adicionales, anular la carga automática o controlar el comportamiento de las políticas.

Sintaxis básica:

$ docker buildx build --policy filename=custom.rego .

Esto carga custom.rego además de la política automática Dockerfile.rego (si existe).

Múltiples políticas:

$ docker buildx build --policy filename=policy1.rego --policy filename=policy2.rego .

Todas las políticas deben cumplirse para que la compilación tenga éxito. Utiliza esto para aplicar requisitos en capas (política base + reglas específicas del proyecto).

Opciones disponibles:

Opción	Descripción	Ejemplo
`filename=<path>`	Carga la política desde el archivo especificado	`filename=custom.rego`
`reset=true`	Ignora las políticas automáticas, usa solo las indicadas	`reset=true`
`disabled=true`	Deshabilita toda evaluación de políticas	`disabled=true`
`strict=true`	Falla si BuildKit no admite políticas	`strict=true`
`log-level=<level>`	Controla el registro de políticas (error, warn, info, debug, none). Usa `debug` para ver el JSON de entrada completo y los campos no resueltos	`log-level=debug`

Combina opciones separándolas con comas:

$ docker buildx build --policy filename=extra.rego,strict=true .

Explorar fuentes con policy eval

El comando docker buildx policy eval te permite explorar y probar fuentes rápidamente sin ejecutar una compilación.

Inspeccionar la estructura de entrada con --print

Utiliza --print para ver la estructura de entrada de cualquier fuente sin ejecutar la evaluación de políticas:

$ docker buildx policy eval --print https://github.com/moby/buildkit.git

{
  "git": {
    "schema": "https",
    "host": "github.com",
    "remote": "https://github.com/moby/buildkit.git"
  }
}

Probar diferentes tipos de fuentes:

# Descargas HTTP
$ docker buildx policy eval --print https://releases.hashicorp.com/terraform/1.5.0/terraform.zip

# Imágenes (requiere el prefijo docker-image://)
$ docker buildx policy eval --print docker-image://alpine:3.19

# Contexto local
$ docker buildx policy eval --print .

Muestra información analizada a partir de la fuente sin realizar descargas. Utiliza --fields para obtener metadatos específicos (ver arriba).

Probar con archivos de políticas específicos

La bandera --filename especifica qué archivo de política cargar proporcionando el nombre base del Dockerfile (sin la extensión .rego). Esto es útil para probar fuentes frente a políticas asociadas con diferentes Dockerfiles.

Por ejemplo, para probar una fuente frente a la política de app.Dockerfile:

$ docker buildx policy eval --filename app.Dockerfile .

Esto carga app.Dockerfile.rego y comprueba si permite la fuente . (el directorio local). La bandera tiene como valor predeterminado Dockerfile si no se especifica.

Probar diferentes fuentes frente a tu política:

$ docker buildx policy eval --filename app.Dockerfile https://github.com/org/repo.git
$ docker buildx policy eval --filename app.Dockerfile docker-image://alpine:3.19

Restablecer la carga automática

Para utilizar únicamente las políticas especificadas e ignorar los archivos .rego automáticos:

$ docker buildx build --policy reset=true,filename=custom.rego .

Esto omite Dockerfile.rego y carga únicamente custom.rego.

Deshabilitar políticas temporalmente

Deshabilita la evaluación de políticas para pruebas o emergencias:

$ docker buildx build --policy disabled=true .

La compilación continúa sin ninguna verificación de políticas. Utiliza esto con precaución: estás omitiendo los controles de seguridad.

Siguientes pasos

Escribe pruebas unitarias para tus políticas: Probar políticas de compilación
Depurar fallas de políticas: Depuración
Explorar ejemplos prácticos: Ejemplos de políticas
Consultar todos los campos de entrada: Referencia de inputs

¿En qué te puedo ayudar?

Uso de políticas de compilación