# Depuración de políticas de compilación


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:

```console
# 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`:

```console
$ 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.

```plaintext
#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:

```text
#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:

```console
$ 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:

```text
#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:

```text
#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:

```text
#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:

```rego
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:

```rego
# 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:

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

Consulta [Uso de políticas de compilación](/build/policies/usage/#probar-políticas-con-policy-eval)
para más detalles.

## Siguientes pasos

- Ver la referencia de campos completa: [Referencia de inputs](/build/policies/inputs/)
- Revisar ejemplos de políticas: [Ejemplos](/build/policies/examples/)
- Aprender patrones de uso de políticas: [Uso de políticas de compilación](/build/policies/usage/)