Usar la comprobación de la actualización de imágenes

En esta página se muestra cómo usar la comprobación de la actualización de imágenes de la validación continua (VC) de la autorización binaria para comprobar la actualización de las imágenes asociadas a los pods que se ejecutan en clústeres de Google Kubernetes Engine (GKE) en los que la VC está habilitada. Para ello, CV comprueba cuándo se subió la imagen al registro de imágenes.

Esta comprobación solo admite repositorios de Artifact Registry y Container Registry.

Costes

En esta guía se utilizan los siguientes servicios de Google Cloud :

  • Autorización binaria, pero CV está disponible de forma gratuita durante la fase de vista previa
  • Google Kubernetes Engine

Para generar una estimación de costes basada en el uso previsto, utiliza la calculadora de precios.

Antes de empezar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. Install the Google Cloud CLI.

  3. Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  4. Para inicializar gcloud CLI, ejecuta el siguiente comando:

    gcloud init
  5. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Artifact Registry, Binary Authorization, Google Kubernetes Engine APIs:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    gcloud services enable artifactregistry.googleapis.com binaryauthorization.googleapis.com cloudbuild.googleapis.com container.googleapis.com
  8. Install the Google Cloud CLI.

  9. Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  10. Para inicializar gcloud CLI, ejecuta el siguiente comando:

    gcloud init
  11. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  12. Verify that billing is enabled for your Google Cloud project.

  13. Enable the Artifact Registry, Binary Authorization, Google Kubernetes Engine APIs:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    gcloud services enable artifactregistry.googleapis.com binaryauthorization.googleapis.com cloudbuild.googleapis.com container.googleapis.com
  14. Asegúrate de que la CLI de gcloud esté actualizada a la última versión.
  15. Instala la herramienta de línea de comandos kubectl.
  16. Si tus políticas de autorización binaria y tus clústeres de GKE están en proyectos diferentes, asegúrate de que la autorización binaria esté habilitada en ambos proyectos.
  17. Roles obligatorios

    En esta sección se explica cómo definir roles para esta comprobación.

    Información general

    Si ejecutas todos los productos que se mencionan en esta guía en el mismo proyecto, no tienes que definir ningún permiso. Autorización binaria configura los roles correctamente cuando la habilitas. Si ejecuta los productos en proyectos diferentes, debe asignar roles tal como se describe en esta sección.

    Para asegurarte de que el agente de servicio de autorización binaria del proyecto de la política tenga los permisos necesarios para evaluar la comprobación de la actualización de la imagen de CV, pide a tu administrador que conceda al agente de servicio de autorización binaria del proyecto de la política los siguientes roles de gestión de identidades y accesos:

    • Si el proyecto del clúster es diferente del proyecto de la política, haz lo siguiente: Evaluador de políticas de autorización binaria (roles/binaryauthorization.policyEvaluator) en el agente de servicio de autorización binaria del proyecto del clúster para que pueda acceder al proyecto de la política.
    • Si tu proyecto de Artifact Registry (el proyecto que almacena tus imágenes) es diferente del proyecto de la política: Lector de Artifact Registry (roles/artifactregistry.reader) en el agente de servicio de Binary Authorization del proyecto de la política para que pueda acceder al proyecto de la certificación
    • Si tu proyecto de Artifact Registry es diferente del proyecto de tu clúster, haz lo siguiente: Lector de Artifact Registry (roles/artifactregistry.reader) en el agente de servicio de autorización binaria del proyecto del clúster para que pueda acceder a los metadatos de la imagen en el proyecto de Artifact Registry.

    Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

    Es posible que tu administrador también pueda conceder al agente de servicio de Autorización Binaria del proyecto de la política los permisos necesarios a través de roles personalizados u otros roles predefinidos.

    Otorgar roles con la CLI de gcloud

    Para asegurarte de que el agente de servicio de Autorización binaria de cada proyecto tiene los permisos necesarios para evaluar esta comprobación, concede los siguientes roles de gestión de identidades y accesos al agente de servicio de Autorización binaria de cada proyecto.

    El proyecto del clúster es diferente del proyecto de la política

    Asigna al agente de servicio de autorización binaria del proyecto del clúster el rol Evaluador de políticas de autorización binaria (roles/binaryauthorization.policyEvaluator) en el proyecto de la política.

    gcloud projects add-iam-policy-binding POLICY_PROJECT_ID \
      --member="serviceAccount:service-$(gcloud projects describe CLUSTER_PROJECT_ID --format='value(projectNumber)')@gcp-sa-binaryauthorization.iam.gserviceaccount.com" \
      --role=roles/binaryauthorization.policyEvaluator

    Haz los cambios siguientes:

    • POLICY_PROJECT_ID: el ID del proyecto que contiene tu política.
    • CLUSTER_PROJECT_ID: el ID de proyecto del clúster.

    El proyecto de la política es diferente al del artefacto

    Asigna al agente de servicio de Autorización binaria del proyecto de la política el rol Lector de Artifact Registry (roles/artifactregistry.reader) en el proyecto de artefacto.

    gcloud projects add-iam-policy-binding ARTIFACT_PROJECT_ID \
        --member="serviceAccount:service-$(gcloud projects describe POLICY_PROJECT_ID --format='value(projectNumber)')@gcp-sa-binaryauthorization.iam.gserviceaccount.com" \
        --role=roles/artifactregistry.reader

    Sustituye ARTIFACT_PROJECT_ID por el ID del proyecto que contiene tu repositorio de Artifact Registry.

    El proyecto del clúster es diferente del proyecto del artefacto

    Asigna al agente de servicio de Autorización binaria del proyecto del clúster el rol Lector de Artifact Registry (roles/artifactregistry.reader) en el proyecto del artefacto.

    gcloud projects add-iam-policy-binding ARTIFACT_PROJECT_ID \
        --member="serviceAccount:service-$(gcloud projects describe CLUSTER_PROJECT_ID --format='value(projectNumber)')@gcp-sa-binaryauthorization.iam.gserviceaccount.com" \
        --role=roles/artifactregistry.reader

    Haz los cambios siguientes:

    • ARTIFACT_PROJECT_ID: el ID del proyecto que contiene tu repositorio de Artifact Registry.
    • CLUSTER_PROJECT_ID: el ID del proyecto que ejecuta tus clústeres de GKE.

    Crear una política de la plataforma

    Para crear una política de plataforma de CV con la comprobación de la actualización de la imagen, siga estos pasos:

    1. Crea el archivo YAML de la política de la plataforma:

      cat << EOF > /tmp/my-policy.yaml
      gkePolicy:
        checkSets:
        - checks:
          - imageFreshnessCheck:
              maxUploadAgeDays: MAX_UPLOAD_AGE_DAYS
            displayName: CHECK_DISPLAY_NAME
          displayName: CHECK_SET_DISPLAY_NAME
      EOF
      

      Haz los cambios siguientes:

      • MAX_UPLOAD_AGE_DAYS: tiempo máximo transcurrido desde que se subió la imagen al registro, en días.
      • CHECK_SET_DISPLAY_NAME: nombre visible opcional que elijas para el conjunto de comprobaciones
      • CHECK_DISPLAY_NAME: un nombre visible opcional que elijas para la comprobación
    2. Crea la política de la plataforma:

      Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

      • POLICY_ID: ID de política de plataforma que elijas. Si la política está en otro proyecto, puedes usar el nombre de recurso completo: projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID.
      • POLICY_PATH: ruta al archivo de la política.
      • POLICY_PROJECT_ID: ID del proyecto de la política.

      Ejecuta el siguiente comando:

      Linux, macOS o Cloud Shell

      gcloud beta container binauthz policy create POLICY_ID \
          --platform=gke \
          --policy-file=POLICY_PATH \
          --project=POLICY_PROJECT_ID

      Windows (PowerShell)

      gcloud beta container binauthz policy create POLICY_ID `
          --platform=gke `
          --policy-file=POLICY_PATH `
          --project=POLICY_PROJECT_ID

      Windows (cmd.exe)

      gcloud beta container binauthz policy create POLICY_ID ^
          --platform=gke ^
          --policy-file=POLICY_PATH ^
          --project=POLICY_PROJECT_ID

    Habilitar CV

    Puedes crear un clúster o actualizar uno que ya tengas para usar la monitorización de CV con políticas de plataforma basadas en comprobaciones.

    Crear un clúster que use la monitorización de CV

    En esta sección, crearás un clúster que solo use la monitorización de CV con políticas de plataforma basadas en comprobaciones.

    Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

    • CLUSTER_NAME: nombre del clúster.
    • LOCATION: la ubicación (por ejemplo, us-central1 o asia-south1).
    • POLICY_PROJECT_ID: el ID del proyecto en el que se almacena la política.
    • POLICY_ID: el ID de la política.
    • CLUSTER_PROJECT_ID: el ID del proyecto del clúster.

    Ejecuta el siguiente comando:

    Linux, macOS o Cloud Shell

    gcloud beta container clusters create CLUSTER_NAME \
        --location=LOCATION \
        --binauthz-evaluation-mode=POLICY_BINDINGS \
        --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID \
        --project=CLUSTER_PROJECT_ID

    Windows (PowerShell)

    gcloud beta container clusters create CLUSTER_NAME `
        --location=LOCATION `
        --binauthz-evaluation-mode=POLICY_BINDINGS `
        --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID `
        --project=CLUSTER_PROJECT_ID

    Windows (cmd.exe)

    gcloud beta container clusters create CLUSTER_NAME ^
        --location=LOCATION ^
        --binauthz-evaluation-mode=POLICY_BINDINGS ^
        --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID ^
        --project=CLUSTER_PROJECT_ID

    Crear un clúster que use la monitorización de cumplimiento y de CV

    En esta sección, crearás un clúster que utilice tanto la aplicación de la política project-singleton como la monitorización de CV con políticas de plataforma basadas en comprobaciones:

    Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

    • CLUSTER_NAME: nombre del clúster.
    • LOCATION: la ubicación (por ejemplo, us-central1 o asia-south1).
    • POLICY_PROJECT_ID: el ID del proyecto en el que se almacena la política.
    • POLICY_ID: el ID de la política.
    • CLUSTER_PROJECT_ID: el ID del proyecto del clúster.

    Ejecuta el siguiente comando:

    Linux, macOS o Cloud Shell

    gcloud beta container clusters create CLUSTER_NAME \
        --location=LOCATION \
        --binauthz-evaluation-mode=POLICY_BINDINGS_AND_PROJECT_SINGLETON_POLICY_ENFORCE \
        --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID \
        --project=CLUSTER_PROJECT_ID

    Windows (PowerShell)

    gcloud beta container clusters create CLUSTER_NAME `
        --location=LOCATION `
        --binauthz-evaluation-mode=POLICY_BINDINGS_AND_PROJECT_SINGLETON_POLICY_ENFORCE `
        --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID `
        --project=CLUSTER_PROJECT_ID

    Windows (cmd.exe)

    gcloud beta container clusters create CLUSTER_NAME ^
        --location=LOCATION ^
        --binauthz-evaluation-mode=POLICY_BINDINGS_AND_PROJECT_SINGLETON_POLICY_ENFORCE ^
        --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID ^
        --project=CLUSTER_PROJECT_ID

    Actualizar un clúster para usar la monitorización de CV

    En esta sección, actualizarás un clúster para que use la monitorización de CV solo con políticas de plataforma basadas en comprobaciones. Si el clúster ya tiene habilitada la aplicación de la política de proyecto único, al ejecutar este comando se inhabilitará. En su lugar, actualiza el clúster con la monitorización de CV y la aplicación habilitadas.

    Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

    • CLUSTER_NAME: el nombre del clúster
    • LOCATION: la ubicación (por ejemplo, us-central1 o asia-south1)
    • POLICY_PROJECT_ID: ID del proyecto en el que se almacena la política
    • POLICY_ID: el ID de la política
    • CLUSTER_PROJECT_ID: el ID del proyecto del clúster

    Ejecuta el siguiente comando:

    Linux, macOS o Cloud Shell

    gcloud beta container clusters update CLUSTER_NAME \
        --location=LOCATION \
        --binauthz-evaluation-mode=POLICY_BINDINGS \
        --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID \
        --project=CLUSTER_PROJECT_ID

    Windows (PowerShell)

    gcloud beta container clusters update CLUSTER_NAME `
        --location=LOCATION `
        --binauthz-evaluation-mode=POLICY_BINDINGS `
        --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID `
        --project=CLUSTER_PROJECT_ID

    Windows (cmd.exe)

    gcloud beta container clusters update CLUSTER_NAME ^
        --location=LOCATION ^
        --binauthz-evaluation-mode=POLICY_BINDINGS ^
        --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID ^
        --project=CLUSTER_PROJECT_ID

    Actualizar un clúster para usar la monitorización de cumplimiento y de CV

    En esta sección, actualizarás un clúster para que use tanto la aplicación de la política de un solo proyecto como la monitorización de versiones con políticas de plataforma basadas en comprobaciones.

    Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

    • CLUSTER_NAME: nombre de un clúster
    • LOCATION: la ubicación (por ejemplo, us-central1 o asia-south1)
    • POLICY_PROJECT_ID: ID del proyecto en el que se almacena la política
    • POLICY_ID: el ID de la política
    • CLUSTER_PROJECT_ID: el ID del proyecto del clúster

    Ejecuta el siguiente comando:

    Linux, macOS o Cloud Shell

    gcloud beta container clusters update CLUSTER_NAME \
        --location=LOCATION \
        --binauthz-evaluation-mode=POLICY_BINDINGS_AND_PROJECT_SINGLETON_POLICY_ENFORCE \
        --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID \
        --project=CLUSTER_PROJECT_ID

    Windows (PowerShell)

    gcloud beta container clusters update CLUSTER_NAME `
        --location=LOCATION `
        --binauthz-evaluation-mode=POLICY_BINDINGS_AND_PROJECT_SINGLETON_POLICY_ENFORCE `
        --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID `
        --project=CLUSTER_PROJECT_ID

    Windows (cmd.exe)

    gcloud beta container clusters update CLUSTER_NAME ^
        --location=LOCATION ^
        --binauthz-evaluation-mode=POLICY_BINDINGS_AND_PROJECT_SINGLETON_POLICY_ENFORCE ^
        --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID ^
        --project=CLUSTER_PROJECT_ID

    Ver registros de entradas de CV

    Puedes buscar entradas de Cloud Logging para encontrar errores de configuración de CV y infracciones de validación de la política de la plataforma de CV.

    CV registra los errores y las infracciones en Cloud Logging en un plazo de 24 horas. Normalmente, las entradas se muestran al cabo de unas horas.

    Ver los registros de errores de configuración de la verificación

    Para ver los registros de errores de configuración de CV, ejecuta el siguiente comando:

    gcloud logging read \
         --order="desc" \
         --freshness=7d \
         --project=CLUSTER_PROJECT_ID \
        'logName:"binaryauthorization.googleapis.com%2Fcontinuous_validation" "configErrorEvent"'
    

    En el siguiente resultado se muestra un error de configuración en el que no se encuentra una política de plataforma de CV:

    {
      "insertId": "141d4f10-72ea-4a43-b3ec-a03da623de42",
      "jsonPayload": {
        "@type": "type.googleapis.com/google.cloud.binaryauthorization.v1beta1.ContinuousValidationEvent",
        "configErrorEvent": {
          "description": "Cannot monitor cluster 'us-central1-c.my-cluster': Resource projects/123456789/platforms/gke/policies/my-policy does not exist."
        }
      },
      "resource": {
        "type": "k8s_cluster",
        "labels": {
          "cluster_name": "my-cluster",
          "location": "us-central1-c",
          "project_id": "my-project"
        }
      },
      "timestamp": "2024-05-28T15:31:03.999566Z",
      "severity": "WARNING",
      "logName": "projects/my-project/logs/binaryauthorization.googleapis.com%2Fcontinuous_validation",
      "receiveTimestamp": "2024-05-28T16:30:56.304108670Z"
    }
    

    Ver las infracciones de validación de las políticas de la plataforma de CV

    Si ninguna imagen infringe las políticas de la plataforma que has habilitado, no aparecerá ninguna entrada en los registros.

    Para ver las entradas de registro de CV de los últimos siete días, ejecuta el siguiente comando:

    gcloud logging read \
         --order="desc" \
         --freshness=7d \
         --project=CLUSTER_PROJECT_ID \
        'logName:"binaryauthorization.googleapis.com%2Fcontinuous_validation" "policyName"'
    

    Sustituye CLUSTER_PROJECT_ID por el ID del proyecto del clúster.

    Tipos de comprobación

    Los registros de CV comprueban la información de las infracciones en checkResults. En la entrada, el valor checkType indica la comprobación. Los valores de cada comprobación son los siguientes:

    • ImageFreshnessCheck
    • SigstoreSignatureCheck
    • SimpleSigningAttestationCheck
    • SlsaCheck
    • TrustedDirectoryCheck
    • VulnerabilityCheck

    Registro de ejemplo

    La siguiente entrada de registro de CV describe una imagen no conforme que infringe una comprobación de directorio de confianza:

    {
      "insertId": "637c2de7-0000-2b64-b671-24058876bb74",
      "jsonPayload": {
        "podEvent": {
          "endTime": "2022-11-22T01:14:30.430151Z",
          "policyName": "projects/123456789/platforms/gke/policies/my-policy",
          "images": [
            {
              "result": "DENY",
              "checkResults": [
                {
                  "explanation": "TrustedDirectoryCheck at index 0 with display name \"My trusted directory check\" has verdict NOT_CONFORMANT. Image is not in a trusted directory",
                  "checkSetName": "My check set",
                  "checkSetIndex": "0",
                  "checkName": "My trusted directory check",
                  "verdict": "NON_CONFORMANT",
                  "checkType": "TrustedDirectoryCheck",
                  "checkIndex": "0"
                }
              ],
              "image": "gcr.io/my-project/hello-app:latest"
            }
          ],
          "verdict": "VIOLATES_POLICY",
          "podNamespace": "default",
          "deployTime": "2022-11-22T01:06:53Z",
          "pod": "hello-app"
        },
        "@type": "type.googleapis.com/google.cloud.binaryauthorization.v1beta1.ContinuousValidationEvent"
      },
      "resource": {
        "type": "k8s_cluster",
        "labels": {
          "project_id": "my-project",
          "location": "us-central1-a",
          "cluster_name": "my-test-cluster"
        }
      },
      "timestamp": "2022-11-22T01:44:28.729881832Z",
      "severity": "WARNING",
      "logName": "projects/my-project/logs/binaryauthorization.googleapis.com%2Fcontinuous_validation",
      "receiveTimestamp": "2022-11-22T03:35:47.171905337Z"
    }
    

    Limpieza

    En esta sección se describe cómo limpiar la monitorización de CV que has configurado anteriormente en esta guía.

    Puedes inhabilitar la monitorización de CV o tanto Binary Authorization como CV en tu clúster.

    Inhabilitar la autorización binaria en un clúster

    Para inhabilitar la aplicación de CV y de autorización binaria en tu clúster, ejecuta el siguiente comando:

    gcloud beta container clusters update CLUSTER_NAME \
        --binauthz-evaluation-mode=DISABLED \
        --location=LOCATION \
        --project=CLUSTER_PROJECT_ID
    

    Haz los cambios siguientes:

    • CLUSTER_NAME: el nombre del clúster
    • LOCATION: la ubicación del clúster
    • CLUSTER_PROJECT_ID: el ID del proyecto del clúster

    Inhabilitar la monitorización de políticas basada en comprobaciones en un clúster

    Para inhabilitar la verificación de versiones con políticas basadas en comprobaciones en el clúster y volver a habilitar la aplicación mediante la política de aplicación de la autorización binaria, ejecuta el siguiente comando:

    gcloud beta container clusters update CLUSTER_NAME  \
        --binauthz-evaluation-mode=PROJECT_SINGLETON_POLICY_ENFORCE \
        --location=LOCATION \
        --project="CLUSTER_PROJECT_ID"
    

    Haz los cambios siguientes:

    • CLUSTER_NAME: el nombre del clúster
    • LOCATION: la ubicación del clúster
    • CLUSTER_PROJECT_ID: el ID del proyecto del clúster

    Ten en cuenta que --binauthz-evaluation-mode=PROJECT_SINGLETON_POLICY_ENFORCE es equivalente a la marca anterior --enable-binauthz.

    Eliminar la política

    Para eliminar la política, ejecuta el siguiente comando. No es necesario eliminar la política de plataforma basada en comprobaciones para inhabilitar la auditoría de políticas basada en comprobaciones.

    gcloud beta container binauthz policy delete POLICY_ID \
        --platform=gke \
        --project="POLICY_PROJECT_ID"
    

    Haz los cambios siguientes:

    • POLICY_ID: el ID de la política
    • POLICY_PROJECT_ID: el ID del proyecto de la política

    Siguientes pasos