Compartir comentarios
Las respuestas se generan en base a la documentación.

Depuración de políticas de compilación

Tabla de contenidos

Cuando las políticas no funcionen como se espera, utiliza las herramientas disponibles para inspeccionar la evaluación de la política y comprender qué está sucediendo. Esta guía cubre las técnicas de depuración y las situaciones comunes (gotchas).

Referencia rápida

Comandos esenciales de depuración:

# Ver todos los datos de entrada durante las compilaciones (recomendado)
$ docker buildx build --progress=plain --policy log-level=debug .

# Ver las verificaciones y decisiones de políticas
$ docker buildx build --progress=plain .

# Explorar la estructura de entrada para diferentes fuentes
$ docker buildx policy eval --print .
$ docker buildx policy eval --print https://github.com/org/repo.git
$ docker buildx policy eval --print docker-image://alpine:3.19

# Probar si una política permite una fuente
$ docker buildx policy eval .

Salida de políticas con --progress=plain

Para ver la evaluación de políticas durante las compilaciones, utiliza --progress=plain:

$ docker buildx build --progress=plain .

Esto muestra todas las verificaciones de políticas, decisiones y la salida de print(). Sin --progress=plain, la evaluación de políticas es silenciosa a menos que ocurra un error.

#1 loading policies Dockerfile.rego
#1 0.010 checking policy for source docker-image://alpine:3.19 (linux/arm64)
#1 0.011 Dockerfile.rego:8: image: {"ref":"alpine:3.19","repo":"alpine","tag":"3.19"}
#1 0.012 policy decision for source docker-image://alpine:3.19: ALLOW

Si una política deniega una fuente, verás:

#1 0.012 policy decision for source docker-image://nginx:latest: DENY
ERROR: source "docker-image://nginx:latest" not allowed by policy

Logs de depuración

Para una depuración detallada, añade --policy log-level=debug para ver el JSON de entrada completo, los campos no resueltos y las respuestas de la política:

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

Esto muestra significativamente más información que el nivel por defecto, incluyendo la estructura de entrada completa para cada fuente sin necesidad de sentencias print() en tu política.

JSON de entrada completo:

#1 0.007 policy input: {
#1 0.007   "env": {
#1 0.007     "filename": "."
#1 0.007   },
#1 0.007   "image": {
#1 0.007     "ref": "docker.io/library/alpine:3.19",
#1 0.007     "host": "docker.io",
#1 0.007     "repo": "alpine",
#1 0.007     "fullRepo": "docker.io/library/alpine",
#1 0.007     "tag": "3.19",
#1 0.007     "platform": "linux/arm64",
#1 0.007     "os": "linux",
#1 0.007     "arch": "arm64"
#1 0.007   }
#1 0.007 }

Campos no resueltos:

#1 0.007 unknowns for policy evaluation: [input.image.checksum input.image.labels input.image.user input.image.volumes input.image.workingDir input.image.env input.image.hasProvenance input.image.signatures]

Respuesta de la política:

#1 0.008 policy response: map[allow:true]

Esta salida detallada es de gran valor para entender exactamente qué datos recibe tu política y qué campos aún no se han resuelto. Utiliza los logs de depuración al desarrollar políticas para evitar tener que recurrir a múltiples sentencias print().

Depuración condicional con print()

Aunque --policy log-level=debug muestra todos los datos de entrada automáticamente, la función print() es útil para depurar lógica de reglas específica y flujos condicionales:

allow if {
    input.image
    print("Checking image:", input.image.repo, "isCanonical:", input.image.isCanonical)
    input.image.repo == "alpine"
    input.image.isCanonical
}

Utiliza print() para depurar la lógica condicional dentro de las reglas o rastrear qué reglas se están evaluando. Para una inspección general de las entradas durante el desarrollo, utiliza --policy log-level=debug en su lugar; no requiere modificar la política.

Note

Las sentencias print solo se ejecutan cuando se evalúa la regla que las contiene. Una regla como allow if { input.image; print(...) } solo imprime para entradas de imágenes, no para repositorios Git, descargas HTTP o archivos locales.

Problemas comunes

Ruta completa del repositorio o nombre del repositorio

Síntoma: La verificación de los nombres de repositorio en la política no coincide como se esperaba.

Causa: Las imágenes de Docker Hub usan input.image.repo para el nombre corto ("alpine"), pero input.image.fullRepo incluye la ruta completa ("docker.io/library/alpine").

Solución:

# Coincidir solo con el nombre del repositorio (funciona para Docker Hub y otros registros)
allow if {
    input.image
    input.image.repo == "alpine"
}

# O coincidir con la ruta completa del repositorio
allow if {
    input.image
    input.image.fullRepo == "docker.io/library/alpine"
}

La evaluación de la política ocurre múltiples veces

Síntoma: La salida de la compilación muestra la misma fuente evaluada múltiples veces.

Causa: BuildKit puede evaluar políticas en diferentes etapas (resolución de referencias, descarga real) o para diferentes plataformas.

Este comportamiento es normal. Las políticas deben ser idempotentes (producir el mismo resultado cada vez para la misma entrada).

Faltan campos con policy eval --print

Síntoma: docker buildx policy eval --print no muestra los campos esperados como hasProvenance, labels o checksum.

Causa: --print muestra solo información de referencia por defecto, sin realizar consultas a los registros.

Solución: Utiliza --fields para obtener campos de metadatos específicos:

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

Consulta Uso de políticas de compilación para más detalles.

Siguientes pasos