# 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](#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:

1. Comienza con una política básica que deniegue todo.
2. Compila con logs de depuración para ver qué entradas utiliza tu Dockerfile.
3. Añade reglas para permitir fuentes específicas basadas en la salida de depuración.
4. 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:

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

Ejemplo de salida para una fuente de imagen:

```text
#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](/build/policies/inputs/)
para conocer todos los campos disponibles.

### Probar políticas con policy eval

Utiliza [`docker buildx policy eval`](/reference/cli/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](#ver-las-entradas-de-tu-dockerfile).

Prueba si tu política permite el contexto local:

```console
$ docker buildx policy eval .
```

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

```console
ERROR: policy denied
```

Probar otras fuentes:

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

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

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

   ```rego {title="Dockerfile.rego"}
   package docker

   default allow := false

   allow if input.local

   decision := {"allow": allow}
   ```

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

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

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

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

3. Añade una regla que permita la imagen alpine:

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

4. Compila de nuevo para verificar que la política funcione:

   ```console
   $ docker buildx build .
   ```

Si falla, consulta [Depuración](/build/policies/debugging/) 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 {title="Dockerfile"}
FROM alpine:3.19
RUN echo "hello"
```

```rego {title="Dockerfile.rego"}
package docker

default allow := false

allow if input.local

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

decision := {"allow": allow}
```

Compila normalmente:

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

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

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

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

## Uso de políticas con bake

[Bake](/build/bake/) admite la carga automática de políticas al igual que
`docker buildx build`. Coloca `Dockerfile.rego` junto a tu Dockerfile y ejecuta:

```console
$ docker buildx bake
```

### Política manual en archivos bake

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

```hcl {title="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

```hcl {title="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:

```hcl {title="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:

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

```console
$ 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](/build/policies/testing/).

Probar políticas durante las compilaciones de CI:

```yaml {title=".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

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

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

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

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

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

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

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

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

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

Probar diferentes tipos de fuentes:

```console
# 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-políticas-con-policy-eval)).

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

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

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

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

```console
$ 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](/build/policies/testing/)
- Depurar fallas de políticas: [Depuración](/build/policies/debugging/)
- Explorar ejemplos prácticos: [Ejemplos de políticas](/build/policies/examples/)
- Consultar todos los campos de entrada: [Referencia de inputs](/build/policies/inputs/)