# Funciones integradas


Buildx proporciona funciones integradas, además de las [funciones integradas de
Rego](#funciones-integradas-de-rego), para extender las políticas de Rego con
operaciones específicas de Docker, como cargar archivos locales, verificar firmas
de Git y fijar (pin) digests de imágenes.

## Funciones integradas de Rego

Las funciones [documentadas en esta página](#funciones-integradas-de-buildx) son
funciones específicas de Buildx, distintas de las [funciones integradas estándar de
Rego](https://www.openpolicyagent.org/docs/policy-language#built-in-functions).

Buildx también admite funciones integradas estándar de Rego, pero solo un
subconjunto. Para ver la lista exacta de funciones compatibles, consulta el
[código fuente](https://github.com/docker/buildx/blob/master/policy/builtins.go)
de Buildx.

## Funciones integradas de Buildx

Buildx proporciona las siguientes funciones integradas personalizadas para el
desarrollo de políticas:

- [`print`](#print)
- [`load_json`](#load_json)
- [`verify_git_signature`](#verify_git_signature)
- [`pin_image`](#pin_image)

### `print`

Muestra información de depuración durante la evaluación de la política.

Parámetros:

- Cualquier número de valores a imprimir

Retorna: Los valores (como paso directo / pass-through)

Ejemplo:

```rego
allow if {
    input.image.repo == "alpine"
    print("Permitiendo la imagen alpine:", input.image.tag)
}
```

La salida de depuración aparece al realizar la compilación con `--progress=plain`.

### `load_json`

Carga y analiza (parsea) datos JSON de archivos locales en el contexto de
compilación.

Parámetros:

- `filename` (string) - Ruta al archivo JSON relativa al directorio de la política

Retorna: Datos JSON analizados como valor de Rego

Ejemplo:

```rego
# Cargar versiones aprobadas desde un archivo externo
approved_versions = load_json("versions.json")

allow if {
    input.image.repo == "alpine"
    some version in approved_versions.alpine
    input.image.tag == version
}
```

Estructura de archivos:

```text
project/
├── Dockerfile
├── Dockerfile.rego
└── versions.json
```

versions.json:

```json
{
  "alpine": ["3.19", "3.20"],
  "golang": ["1.21", "1.22"]
}
```

El archivo JSON debe estar en el mismo directorio que la política o en un
subdirectorio accesible desde la ubicación de la política.

### `verify_git_signature`

Verifica firmas PGP en commits o etiquetas (tags) de Git.

Parámetros:

- `git_object` (objeto) - Puede ser `input.git.commit` o `input.git.tag`
- `keyfile` (string) - Ruta al archivo de clave pública PGP (relativa al directorio de la política)

Retorna: Booleano - `true` si la firma es válida, `false` en caso contrario

Ejemplo:

```rego
# Requerir etiquetas Git firmadas
allow if {
    input.git.tagName != ""
    verify_git_signature(input.git.tag, "maintainer.asc")
}

# Requerir commits firmados
allow if {
    input.git.commit
    verify_git_signature(input.git.commit, "keys/team.asc")
}
```

Estructura de directorios:

```text
project/
├── Dockerfile.rego
└── maintainer.asc          # Clave pública PGP
```

O con subdirectorio:

```text
project/
├── Dockerfile.rego
└── keys/
    ├── maintainer.asc
    └── team.asc
```

Obtención de claves públicas:

```console
$ gpg --export --armor user@example.com > maintainer.asc
```

### `pin_image`

Fija (pins) una imagen a un digest específico, anulando la referencia basada en
etiquetas. Utiliza esto para forzar que las compilaciones usen versiones de imagen
específicas.

Parámetros:

- `image_object` (objeto) - Debe ser `input.image` (la imagen actual que se está evaluando)
- `digest` (string) - Digest de destino en formato `sha256:...`

Retorna: Booleano - `true` si la fijación se realiza con éxito

Ejemplo:

```rego
# Fijar alpine 3.19 a un digest específico
alpine_3_19_digest = "sha256:4b7ce07002c69e8f3d704a9c5d6fd3053be500b7f1c69fc0d80990c2ad8dd412"

allow if {
    input.image.repo == "alpine"
    input.image.tag == "3.19"
    pin_image(input.image, alpine_3_19_digest)
}
```

Reemplazo automático de digest:

```rego
# Reemplazar digests antiguos con versiones parcheadas
replace_map = {
  "3.22.0": "3.22.2",
  "3.22.1": "3.22.2",
}

alpine_digests = {
  "3.22.0": "sha256:8a1f59ffb675680d47db6337b49d22281a139e9d709335b492be023728e11715",
  "3.22.2": "sha256:4b7ce07002c69e8f3d704a9c5d6fd3053be500b7f1c69fc0d80990c2ad8dd412",
}

allow if {
    input.image.repo == "alpine"
    some old_version, new_version in replace_map
    input.image.checksum == alpine_digests[old_version]
    print("Reemplazando", old_version, "con", new_version)
    pin_image(input.image, alpine_digests[new_version])
}
```

Este patrón actualiza automáticamente las versiones antiguas de imágenes a
versiones parcheadas.

## Siguientes pasos

- Explora ejemplos completos: [Ejemplos de políticas](/build/policies/examples/)
- Aprende el flujo de trabajo para el desarrollo de políticas: [Uso de políticas de compilación](/build/policies/usage/)
- Referencia de campos de entrada: [Referencia de inputs](/build/policies/inputs/)