Aplicación de atestaciones de artefactos con un controlador de admisión de Kubernetes

Use un controlador de admisión para aplicar atestaciones de artefactos en el clúster de Kubernetes.

Nota:

Antes de continuar, asegúrate de que has habilitado la procedencia de compilación para las imágenes de contenedor, incluida la configuración del atributo push-to-registry en la attest-build-provenance acción tal como se documenta en Generación de la procedencia de compilación para imágenes de contenedor. Esto es necesario para que el controlador de directivas compruebe la atestación.

Introducción al controlador de admisión de Kubernetes

Para configurar un controlador de admisión para aplicar atestaciones de artefactos de GitHub, debe:

  1. Implementar el Sigstore Policy Controller.
  2. Agregar el GitHub TrustRoot y un elemento ClusterImagePolicy al clúster.
  3. Habilitar la directiva en el espacio de nombres.

Implementación del Sigstore Policy Controller

Hemos empaquetado el Sigstore Policy Controller como un gráfico de Helm distribuido de GitHub. Asegúrese de que dispone de los siguientes requisitos previos:

  • Un clúster de Kubernetes con la versión 1.27 o posterior
  • Helm 3.0 o posterior
  • kubectl

En primer lugar, instale el gráfico de Helm que implementa el Sigstore Policy Controller:

Bash
helm upgrade policy-controller --install --atomic \
  --create-namespace --namespace artifact-attestations \
  oci://ghcr.io/github/artifact-attestations-helm-charts/policy-controller \
  --version v0.12.0-github12

Esto instala el controlador de directivas en el espacio de nombres artifact-attestations. En este momento, no se ha configurado ninguna directiva y no aplicará ninguna atestación.

Adición de GitHub TrustRoot y un ClusterImagePolicy

Una vez implementado el controlador de directivas, debe agregar GitHub TrustRoot y un elemento ClusterImagePolicy al clúster. Use el gráfico de Helm que proporcionamos para hacerlo. Asegúrese de reemplazar MY-ORGANIZATION por el nombre de la organización de GitHub (por ejemplo, github o octocat-inc).

Bash
helm upgrade trust-policies --install --atomic \
 --namespace artifact-attestations \
 oci://ghcr.io/github/artifact-attestations-helm-charts/trust-policies \
 --version v0.6.2 \
 --set policy.enabled=true \
 --set policy.organization=MY-ORGANIZATION

Ahora ha instalado la raíz de confianza de GitHub y una directiva de atestación de artefactos en el clúster. Esta directiva rechazará los artefactos que no se hayan originado en la organización de GitHub.

Habilitación de la directiva en el espacio de nombres

Advertencia

Esta directiva no se aplicará hasta que especifique los espacios de nombres a los que se debe aplicar.

Cada espacio de nombres del clúster puede aplicar directivas de forma independiente. Para habilitar la aplicación en un espacio de nombres, puede agregar la siguiente etiqueta al espacio de nombres:

metadata:
  labels:
    policy.sigstore.dev/include: "true"

Una vez agregada la etiqueta, la directiva de atestación de artefactos de GitHub se aplicará en el espacio de nombres.

Como alternativa, puede ejecutar:

Bash
kubectl label namespace MY-NAMESPACE policy.sigstore.dev/include=true

Imágenes coincidentes

De forma predeterminada, la directiva instalada con el gráfico de Helm trust-policies comprobará las atestaciones de todas las imágenes antes de admitirlas en el clúster. Si solo pretende aplicar atestaciones para un subconjunto de imágenes, puede usar los valores de Helm policy.images y policy.exemptImages especificar una lista de imágenes con las que debe coincidir. Estos valores se pueden establecer en una lista de patrones globales que coinciden con los nombres de imagen. La sintaxis global usa la semántica de Go filepath, con la adición de ** para que coincida con cualquier secuencia de caracteres, incluidas las barras diagonales.

Por ejemplo, para aplicar atestaciones para imágenes que coincidan con el patrón ghcr.io/MY-ORGANIZATION/* y admitan busybox sin una atestación válida, puede ejecutar:

Bash
helm upgrade trust-policies --install --atomic \
 --namespace artifact-attestations \
 oci://ghcr.io/github/artifact-attestations-helm-charts/trust-policies \
 --version v0.6.2 \
 --set policy.enabled=true \
 --set policy.organization=MY-ORGANIZATION \
 --set-json 'policy.exemptImages=["index.docker.io/library/busybox**"]' \
 --set-json 'policy.images=["ghcr.io/MY-ORGANIZATION/**"]'

Todos los modelos deben usar el nombre completo, incluso si las imágenes se originan en Docker Hub. En este ejemplo, si queremos excluir la imagen busybox, debemos proporcionar el nombre completo, incluido el dominio y el glob de doble estrella para que coincida con todas las versiones de la imagen: index.docker.io/library/busybox**.

Tenga en cuenta que cualquier imagen que quiera admitir debe tener un patrón global coincidente en la lista policy.images. Si una imagen no coincide con ningún patrón, se rechazará. Además, si una imagen coincide con policy.images y policy.exemptImages, se rechazará.

Si tu cuenta de GitHub Enterprise tiene un subdominio en GHE.com, debes especificar un valor para el dominio de confianza de GitHub. Este valor se usa para capturar los materiales de confianza asociados a la región de residencia de datos que hospeda la cuenta de GitHub Enterprise. Para encontrar este valor, inicie sesión en su cuenta empresarial con la herramienta CLI gh y ejecute el siguiente comando:

Bash
gh api meta --jq .domains.artifact_attestations.trust_domain

Este valor se debe agregar al instalar el gráfico trust-policies, de la siguiente manera:

Bash
--set-json 'policy.trust.githubTrustDomain="YOUR-GHEC-TRUST-DOMAIN"'

Uso avanzado

Para ver el conjunto completo de opciones que puede configurar con el gráfico de Helm, puede ejecutar cualquiera de los siguientes comandos. Para las opciones del controlador de directivas:

Bash
helm show values oci://ghcr.io/github/artifact-attestations-helm-charts/policy-controller --version v0.12.0-github12

Para opciones de directiva de confianza:

Bash
helm show values oci://ghcr.io/github/artifact-attestations-helm-charts/trust-policies --version v0.6.2

Para obtener más información sobre el Sigstore Policy Controller, consulte la documentación del Sigstore Policy Controller.