Sincronizar artefactos OCI de Artifact Registry

En esta página se muestra cómo crear y publicar una imagen en un repositorio de Artifact Registry con crane y oras.

Puedes configurar Config Sync para que sincronice imágenes de OCI mediante Artifact Registry. Para usar esta función, debes habilitar las APIs RootSync y RepoSync.

Acerca de Artifact Registry

Artifact Registry es un servicio totalmente gestionado que admite tanto imágenes de contenedor como artefactos que no son de contenedor. Te recomendamos que uses Artifact Registry para almacenar y gestionar tus imágenes de contenedor en Google Cloud. Hay muchas herramientas disponibles para enviar artefactos a Artifact Registry. Por ejemplo, puedes insertar una imagen Docker o usar la biblioteca go-containerregistry para trabajar con registros de contenedores. Elige la herramienta que mejor se adapte a tus necesidades.

Precaución: No añadas imágenes base a tus archivos OCI almacenados en Artifact Registry. Como las imágenes de OCI actúan como almacenamiento de archivos, añadir imágenes base puede provocar problemas de permisos al sincronizar.

Antes de empezar

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.

Install the Google Cloud CLI.

Nota: Si ya has instalado la CLI de gcloud, asegúrate de que tienes la versión más reciente ejecutando gcloud components update.

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

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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

Verify that billing is enabled for your Google Cloud project.

Enable the GKE, Config Sync, Artifact Registry 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 container.googleapis.com  anthosconfigmanagement.googleapis.com  artifactregistry.googleapis.com

Install the Google Cloud CLI.

Nota: Si ya has instalado la CLI de gcloud, asegúrate de que tienes la versión más reciente ejecutando gcloud components update.

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

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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

Verify that billing is enabled for your Google Cloud project.

Enable the GKE, Config Sync, Artifact Registry 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 container.googleapis.com  anthosconfigmanagement.googleapis.com  artifactregistry.googleapis.com

1. Crea un clúster o ten acceso a uno que cumpla los requisitos de Config Sync y que tenga la versión más reciente de Config Sync.
2. Instala la CLI de nomos o actualízala a la versión más reciente.
3. (Opcional) Si quieres usar Cosign para verificar las firmas de imágenes de OCI, instala lo siguiente:
• Cosign para firmar imágenes OCI.
• OpenSSL para generar credenciales para el servidor webhook.
• Docker para compilar y enviar la imagen del servidor de webhook de admisión.

Costes

En este documento, se utilizan los siguientes componentes facturables de Google Cloud:

• GKE
• Artifact Registry

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

Los usuarios nuevos Google Cloud pueden disfrutar de una prueba gratuita.

Crear un repositorio de Artifact Registry

En esta sección, crearás un repositorio de Artifact Registry. Para obtener más información sobre cómo crear repositorios de Artifact Registry, consulta el artículo Crear repositorios.

1. Crea un repositorio de Artifact Registry:

   gcloud artifacts repositories create AR_REPO_NAME \
      --repository-format=docker \
      --location=AR_REGION \
      --description="Config Sync repo" \
      --project=PROJECT_ID
   

Haz los cambios siguientes:

• PROJECT_ID: el ID del proyecto de la organización.
• AR_REPO_NAME: el ID del repositorio.
• AR_REGION: la ubicación regional o multirregional del repositorio.

Variables usadas en las siguientes secciones:

• FLEET_HOST_PROJECT_ID: si usas GKE Workload Identity Federation for GKE, es lo mismo que PROJECT_ID. Si usas la federación de identidades de carga de trabajo de flota para GKE, este es el ID del proyecto de la flota en la que está registrado tu clúster.
• GSA_NAME: el nombre de la cuenta de servicio de Google personalizada que quieras usar para conectarte a Artifact Registry.
• KSA_NAME: la cuenta de servicio de Kubernetes del reconciliador.
  • En el caso de los repositorios raíz, si el nombre de RootSync es root-sync, añade root-reconciler. De lo contrario, añade root-reconciler-ROOT_SYNC_NAME.
  • En el caso de los repositorios de espacios de nombres, si el nombre de RepoSync es repo-sync, añade ns-reconciler-NAMESPACE. De lo contrario, añade ns-reconciler-NAMESPACE-REPO_SYNC_NAME-REPO_SYNC_NAME_LENGTH, donde REPO_SYNC_NAME_LENGTH es el número de caracteres de REPO_SYNC_NAME.

Conceder permiso de lectura

Para autenticarte en Artifact Registry con una cuenta de servicio de Kubernetes, sigue estos pasos:

Concede el rol de lector de Artifact Registry (roles/artifactregistry.reader) de gestión de identidades y accesos a la cuenta de servicio de Kubernetes que tenga el grupo de Workload Identity Federation para GKE:

gcloud artifacts repositories add-iam-policy-binding AR_REPO_NAME \
   --location=AR_REGION \
   --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   --role=roles/artifactregistry.reader \
   --project=PROJECT_ID

Enviar una imagen al repositorio de Artifact Registry

En esta sección, crearás una imagen OCI y la enviarás a Artifact Registry.

1. Crea un archivo de manifiesto Namespace:

   cat <<EOF> test-namespace.yaml
   apiVersion: v1
   kind: Namespace
   metadata:
     name: test
   EOF
   

2. Inicia sesión en Artifact Registry:

   gcloud auth configure-docker AR_REGION-docker.pkg.dev
   

3. Empaqueta la imagen y envíala a Artifact Registry:

   crane

   Los comandos de esta sección usan crane para interactuar con imágenes y registros remotos.

   1. Empaqueta el archivo:

      tar -cf test-namespace.tar test-namespace.yaml
      

   2. Instala la herramienta crane.

   3. Envía la imagen a Artifact Registry:

      crane append -f test-namespace.tar -t AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME/test-namespace:v1
      

   oras

   Los comandos de esta sección usan oras para interactuar con imágenes y registros remotos.

   1. Empaqueta el archivo:

      tar -czf test-namespace.tar.gz test-namespace.yaml
      

   2. Instala la herramienta oras.

   3. Envía la imagen a Artifact Registry:

      oras push AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME/test-namespace:v1 test-namespace.tar.gz
      

   Precaución: Config Sync requiere que la capa OCI esté comprimida en formato tar o tar+gzip. Config Sync no reconoce otros formatos (por ejemplo, tar+bz2). Si se cambia de un REPO válido a una imagen OCI con un formato no admitido, los recursos gestionados se eliminarán sin que se produzca ningún error.

Configurar Config Sync para sincronizar desde tu imagen

En esta sección, crearás un objeto RootSync y configurarás Config Sync para que se sincronice desde la imagen de OCI.

1. Crea un objeto RootSync con un nombre único:

   cat <<EOF>> ROOT_SYNC_NAME.yaml
   apiVersion: configsync.gke.io/v1beta1
   kind: RootSync
   metadata:
     name: ROOT_SYNC_NAME
     namespace: config-management-system
   spec:
     sourceFormat: unstructured
     sourceType: oci
     oci:
       image: AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME/test-namespace:v1
       dir: .
       auth: k8sserviceaccount
   EOF
   

   Sustituye ROOT_SYNC_NAME por el nombre de tu objeto RootSync. El nombre debe ser único en el clúster y no puede tener más de 26 caracteres. Para ver la lista completa de opciones al configurar objetos RootSync, consulta los campos RootSync y RepoSync.

2. Aplica el objeto RootSync:

   kubectl apply -f ROOT_SYNC_NAME.yaml
   

3. Verifica que Config Sync se esté sincronizando desde la imagen:

   nomos status --contexts=$(kubectl config current-context)
   

   Debería ver un resultado similar al siguiente ejemplo:

   Connecting to clusters...
   
   *publish-config-registry
      --------------------
      <root>:root-sync-test   AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME/test-namespace:v1   
      SYNCED                  05e6a6b77de7a62286387cfea833d45290105fe84383224938d7b3ab151a55a1
      Managed resources:
         NAMESPACE   NAME             STATUS    SOURCEHASH
                     namespace/test   Current   05e6a6b
   

   Ahora has sincronizado correctamente una imagen con tu clúster.

(Opcional) Verificar las firmas de origen de OCI

A partir de la versión 1.20.0 de Config Sync, Config Sync admite la verificación de la autenticidad de las imágenes de origen de OCI antes de que se apliquen las configuraciones a tus clústeres. Este método usa un objeto ValidatingWebhookConfiguration y un servidor webhook de validación para interceptar las solicitudes de actualización de los objetos RootSync y RepoSync. Config Sync actualiza la anotación configsync.gke.io/image-to-sync de los objetos RootSync y RepoSync después de obtener correctamente un nuevo resumen de imagen. El servidor webhook de validación compara los valores de la anotación antigua y la nueva, y ejecuta la validación con una herramienta de validación como Cosign cuando se detecta un cambio.

Configurar un servidor de verificación de firmas

Para asegurar la autenticidad de tus fuentes de OCI, necesitas un servidor HTTP para verificar las firmas. Puedes usar los ejemplos del repositorio de ejemplos de Config Sync o tu propia imagen de Docker.

1. Si quieres usar la muestra proporcionada, sigue estos pasos:

   1. Clona el repositorio de muestra:

      git clone https://github.com/GoogleCloudPlatform/anthos-config-management-samples/
      

   2. Cambia al directorio que contiene los ejemplos del servidor de verificación de firmas:

      cd anthos-config-management-samples/tree/main/pre-sync/oci-image-verification
      

2. Para crear una imagen de Docker para el servidor de verificación de firmas y enviarla a un registro de imágenes, ejecuta el siguiente comando:

   docker build -t SIGNATURE_VERIFICATION_SERVER_IMAGE_URL:latest . && docker push SIGNATURE_VERIFICATION_SERVER_IMAGE_URL:latest
   

   Sustituye SIGNATURE_VERIFICATION_SERVER_IMAGE_URL por la URL de la imagen de tu servidor de verificación de firmas.

Autenticarse en servicios

Para configurar tu servidor de verificación de firmas, debes autenticarte en Artifact Registry, el cliente de Cosign y el servidor webhook.

1. Crea un espacio de nombres:

   kubectl create ns signature-verification
   

2. Para autenticarte en Artifact Registry con una cuenta de servicio de Kubernetes, sigue estos pasos:

   1. Crea una cuenta de servicio de Kubernetes en el espacio de nombres que has creado:

      kubectl create sa signature-verification-sa -n signature-verification
      

   2. Añade el enlace de la política de gestión de identidades y accesos para el rol Lector de Artifact Registry (roles/artifactregistry.reader):

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY_NAME \
         --location=REPOSITORY_LOCATION \
         --member="serviceAccount:PROJECT_ID.svc.id.goog[signature-verification/signature-verification-sa]" \
         --role=roles/artifactregistry.reader \
         --project=PROJECT_ID
      

      Haz los cambios siguientes:

      • REPOSITORY_NAME: el nombre del repositorio de Artifact Registry en el que almacenas tus imágenes OCI.
      • REPOSITORY_LOCATION: la ubicación de tu repositorio de Artifact Registry.

3. Para autenticarte en el cliente de Cosign, sigue estos pasos:

   1. Genera un par de claves de Cosign. Este comando genera una clave pública y una privada:

      cosign generate-key-pair
      

   2. Almacena la clave pública en un secreto de Kubernetes en el espacio de nombres que has creado:

      kubectl create secret generic cosign-key --from-file=cosign.pub -n signature-verification
      

4. Para autenticar el servidor de verificación de firmas, sigue estos pasos:

   1. Para cifrar la comunicación en el servidor de verificación de firmas, genera un certificado TLS y una clave privada con OpenSSL:

      openssl req -nodes -x509 -sha256 -newkey rsa:4096 \
      -keyout tls.key \
      -out tls.crt \
      -days 356 \
      -subj "/CN=signature-verification-service.signature-verification.svc"  \
      -addext "subjectAltName = DNS:signature-verification-service,DNS:signature-verification-service.signature-verification.svc,DNS:signature-verification-service.signature-verification"
      

   2. Almacena las credenciales que has generado en un secreto de Kubernetes:

      kubectl create secret tls webhook-tls --cert=tls.crt --key=tls.key -n signature-verification
      

   3. Obtén el contenido codificado en Base64 de tls.cert. Esto es necesario para la configuración del webhook de validación que creará en la siguiente sección:

      cat tls.crt | base64 -w 0.
      

Desplegar el webhook de admisión

Puedes usar los siguientes ejemplos para crear una implementación del servidor de verificación de firmas y una configuración de webhook de validación.

1. Crea una implementación para el servidor de verificación de firmas guardando el siguiente archivo:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: signature-verification-server
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: signature-verification-server
     template:
       metadata:
         labels:
           app: signature-verification-server
       spec:
         serviceAccountName: signature-verification-sa
         containers:
         - name: signature-verification-server
           command:
           - /signature-verification-server
           image: SIGNATURE_VERIFICATION_SERVER_IMAGE_URL
           imagePullPolicy: Always
           ports:
           - containerPort: 10250
           volumeMounts:
           - name: tls-certs
             mountPath: "/tls"
           - name: cosign-key
             mountPath: "/cosign-key"
         volumes:
         - name: cosign-key
           secret:
             secretName: cosign-key
         - name: tls-certs
           secret:
             secretName: webhook-tls
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: signature-verification-service
   spec:
     ports:
     - port: 10250
       targetPort: 10250
     selector:
       app: signature-verification-server

   Sustituye SIGNATURE_VERIFICATION_SERVER_IMAGE_URL por la URL completa de la imagen del servidor de verificación de firmas.

2. Aplica el despliegue al clúster:

   kubectl apply -f signature-verification-deployment.yaml -n signature-verification
   

3. Crea una configuración de webhook de validación guardando el siguiente archivo:

   apiVersion: admissionregistration.k8s.io/v1
   kind: ValidatingWebhookConfiguration
   metadata:
     name: image-verification-webhook
   webhooks:
   - name: imageverification.webhook.com
     clientConfig:
       service:
         name: signature-verification-service
         namespace: signature-verification
         path: "/validate"
         port: 10250
       caBundle: CA_BUNDLE
     rules:
     - apiGroups:
       - configsync.gke.io
       apiVersions:
       - v1beta1
       - v1alpha1
       operations:
       - UPDATE
       resources:
       - 'rootsyncs'
       - 'reposyncs'
       scope: '*'
     admissionReviewVersions: ["v1", "v1beta1"]
     sideEffects: None

   Sustituye CA_BUNDLE por el contenido codificado en Base64 de tls.cert.

4. Aplica la configuración de webhook de validación al clúster:

   kubectl apply -f signature-verification-validatingwebhookconfiguration.yaml
   

Consultar los registros para ver si hay errores de verificación de imágenes

Una vez que hayas configurado tu servidor de verificación de imágenes, no se podrá sincronizar ninguna imagen OCI sin firmar.

Para comprobar si hay errores de verificación de firmas, consulta los registros del servidor de verificación de firmas ejecutando los siguientes comandos:

1. Consulta los registros de kubectl:

   kubectl logs deployment  signature-verification-server -n  signature-verification
   

   Los errores de kubectl relacionados con la verificación de firmas son similares a los siguientes:

   main.go:69: error during command execution: no signatures found
   

2. Consulta los registros de Config Sync:

   nomos status
   

   Los errores de Config Sync relacionados con la verificación de firmas son similares a los siguientes:

   Error:   KNV2002: admission webhook "imageverification.webhook.com" denied the request: Image validation failed: cosign verification failed: exit status 10, output: Error: no signatures found
   

Si no aparece ningún error, puedes confirmar que la imagen firmada es el objeto que se está sincronizando inspeccionando tu configuración de RootSync o RepoSync:

RootSync

 kubectl get rootsync ROOTSYNC_NAME -n config-management-system -oyaml

Sustituye ROOTSYNC_NAME por el nombre de tu RootSync.

RepoSync

 kubectl get reposync REPOSYNC_NAME -n REPOSYNC_NAMESPACE -oyaml

Haz los cambios siguientes:

• REPOSYNC_NAME: el nombre de tu RepoSync.
• REPOSYNC_NAMESPACE: el nombre del espacio de nombres asociado a tu RepoSync.

Debería ver la anotación configsync.gke.io/image-to-sync añadida a su objeto RootSync o RepoSync. La anotación contiene la URL de la imagen OCI de origen y el último digest obtenido por Config Sync.

Siguientes pasos

• Más información sobre cómo instalar Config Sync
• Soluciona problemas de Config Sync.