Sincronizzare gli elementi OCI da Artifact Registry

Questa pagina mostra come creare e pubblicare l'immagine in un repository in Artifact Registry con crane e oras.

Puoi configurare Config Sync per eseguire la sincronizzazione dalle immagini OCI utilizzando Artifact Registry. Per utilizzare questa funzionalità, devi abilitare le API RootSync e RepoSync.

Informazioni su Artifact Registry

Artifact Registry è un servizio completamente gestito che supporta sia le immagini container sia gli artefatti non container. Ti consigliamo Artifact Registry per l'archiviazione e la gestione delle immagini container su Google Cloud. Esistono molti strumenti disponibili per spingere gli elementi in Artifact Registry. Ad esempio, puoi eseguire il push di un'immagine Docker, il push di un grafico Helm o utilizzare la libreria go-containerregistry per lavorare con i registry dei container. Scegli lo strumento più adatto alle tue esigenze.

Attenzione: non aggiungere immagini di base ai file OCI archiviati in Artifact Registry. Poiché le immagini OCI fungono da spazio di archiviazione dei file, l'aggiunta di immagini di base può causare problemi di autorizzazione durante la sincronizzazione.

Prima di iniziare

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. To use a federated identity with the gcloud CLI, you must first configure the tool to use a federated identity.

   For more information, see Browser-based sign-in with the gcloud CLI.

4. To initialize the gcloud CLI, run the following command:

   gcloud init

   Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

5. Create or select a Google Cloud project.

   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.

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the GKE Enterprise, Config Sync, Artifact Registry APIs:

   gcloud services enable anthos.googleapis.com  anthosconfigmanagement.googleapis.com  artifactregistry.googleapis.com

8. Install the Google Cloud CLI.

9. To use a federated identity with the gcloud CLI, you must first configure the tool to use a federated identity.

   For more information, see Browser-based sign-in with the gcloud CLI.

10. To initialize the gcloud CLI, run the following command:

    gcloud init

    Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

11. Create or select a Google Cloud project.

    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.

12. Make sure that billing is enabled for your Google Cloud project.

13. Enable the GKE Enterprise, Config Sync, Artifact Registry APIs:

    gcloud services enable anthos.googleapis.com  anthosconfigmanagement.googleapis.com  artifactregistry.googleapis.com

14. Crea o accedi a un cluster che soddisfi i requisiti per Config Sync e sia in uso la versione più recente di Config Sync.
15. Installa l'interfaccia a riga di comando nomos o esegui l'upgrade all'ultima versione.
16. (Facoltativo) Se vuoi utilizzare Cosign per verificare le firme delle immagini OCI, installa quanto segue:
• Cosign per firmare le immagini OCI.
• OpenSSL per generare le credenziali per il server webhook.
• Docker per creare ed eseguire il push dell'immagine del server webhook di ammissione.

Costi

In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:

• GKE Enterprise
• Artifact Registry

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud potrebbero essere idonei per una prova gratuita.

Crea un repository Artifact Registry

In questa sezione viene creato un repository Artifact Registry. Per scoprire di più sulla creazione di repository Artifact Registry, consulta Creare repository.

1. Crea un repository Artifact Registry:

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

Sostituisci quanto segue:

• PROJECT_ID: l'ID progetto dell'organizzazione.
• AR_REPO_NAME: l'ID del repository.
• AR_REGION: la posizione regionale o su più regioni del repository.

Variabili utilizzate nelle seguenti sezioni:

• FLEET_HOST_PROJECT_ID: se utilizzi Workload Identity Federation for GKE, è lo stesso valore di PROJECT_ID. Se utilizzi la federazione delle identità per i carichi di lavoro del parco risorse per GKE, questo è l'ID progetto del parco risorse a cui è registrato il tuo cluster.
• GSA_NAME: il nome dell'account di servizio Google personalizzato che vuoi utilizzare per connetterti ad Artifact Registry.
• KSA_NAME: l'account di servizio Kubernetes per il Mediator.
  • Per i repository principali, se il nome RootSync è root-sync, aggiungi root-reconciler. In caso contrario, aggiungi root-reconciler-ROOT_SYNC_NAME.
  • Per i repository dello spazio dei nomi, se il nome RepoSync è repo-sync, aggiungi ns-reconciler-NAMESPACE. In caso contrario, aggiungi ns-reconciler-NAMESPACE-REPO_SYNC_NAME-REPO_SYNC_NAME_LENGTH dove REPO_SYNC_NAME_LENGTH è il numero di caratteri in REPO_SYNC_NAME.

Concedi l'autorizzazione di lettore

Se la versione di Config Sync è 1.17.2 o successiva nel tuo cluster, puoi utilizzare l'account di servizio Kubernetes per autenticarti in Artifact Registry. In caso contrario, utilizza l'account di servizio Google per l'autenticazione.

Utilizzo dell'account di servizio Kubernetes

Concedi il ruolo IAM Lettore del registry di elementi (roles/artifactregistry.reader) all'account di servizio Kubernetes con il pool della federazione delle identità per i carichi di lavoro per 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

Utilizzo dell'account di servizio Google

1. Concedi il ruolo IAM Artifact Registry Reader (roles/artifactregistry.reader) all'account di servizio Google:

   gcloud artifacts repositories add-iam-policy-binding AR_REPO_NAME \
      --location=AR_REGION \
      --member=serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
      --role=roles/artifactregistry.reader \
      --project=PROJECT_ID
   

2. Crea un'associazione dei criteri IAM tra l'account di servizio Kubernetes e l'account di servizio Google:

   gcloud iam service-accounts add-iam-policy-binding \
      --role roles/iam.workloadIdentityUser \
      --member "serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
      GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
      --project=PROJECT_ID
   

Eseguire il push di un'immagine nel repository Artifact Registry

In questa sezione, crei un'immagine OCI ed esegui il push in Artifact Registry.

1. Crea un file manifest Namespace:

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

2. Accedi ad Artifact Registry:

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

3. Impacchetta e esegui il push dell'immagine in Artifact Registry:

   crane

   I comandi in questa sezione utilizzano crane per interagire con immagini e registri remoti.

   1. Impacchetta il file:

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

   2. Installa lo strumento crane.

   3. Esegui il push dell'immagine ad Artifact Registry:

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

   oras

   I comandi in questa sezione utilizzano oras per interagire con immagini e registri remoti.

   1. Impacchetta il file:

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

   2. Installa lo strumento oras.

   3. Esegui il push dell'immagine ad Artifact Registry:

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

   Attenzione: Config Sync richiede che il livello OCI sia compresso nel formato tar o tar+gzip. Altri formati (ad esempio tar+bz2) non sono riconosciuti da Config Sync. Il passaggio da un REPO valido a un'immagine OCI con un formato non supportato comporterà la potatura delle risorse gestite senza errori.

Configura Config Sync per la sincronizzazione dall'immagine

In questa sezione, creerai un oggetto RootSync e configurerai Config Sync per la sincronizzazione dall'immagine OCI.

1. Crea un oggetto RootSync con un nome univoco:

   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: .
       # The k8sserviceaccount auth type is available in version 1.17.2 and
       # later. Use `gcpserviceaccount` if using an older version.
       # auth: gcpserviceaccount
       # gcpServiceAccountEmail: GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
       auth: k8sserviceaccount
   EOF
   

   Sostituisci ROOT_SYNC_NAME con il nome dell'oggetto RootSync. Il nome deve essere univoco nel cluster e non deve contenere più di 26 caratteri. Per l'elenco completo delle opzioni per la configurazione degli oggetti RootSync, consulta Campi RootSync e RepoSync.

2. Applica l'oggetto RootSync:

   kubectl apply -f ROOT_SYNC_NAME.yaml
   

3. Verifica che Config Sync stia sincronizzando dall'immagine:

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

   Dovresti vedere un output simile al seguente esempio:

   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
   

   Hai sincronizzato correttamente un'immagine con il tuo cluster.

(Facoltativo) Verifica le firme dell'origine OCI

A partire dalla versione 1.20.0, Config Sync supporta la verifica dell'autenticità delle immagini di origine OCI prima dell'applicazione delle configurazioni ai cluster. Questo metodo utilizza un oggetto ValidatingWebhookConfiguration e un server webhook di convalida per intercettare le richieste di aggiornamento per gli oggetti RootSync e RepoSync. Config Sync aggiorna l'annotazione configsync.gke.io/image-to-sync degli oggetti RootSync e RepoSync dopo aver recuperato correttamente un nuovo digest dell'immagine. Il server webhook di convalida confronta i valori tra la vecchia annotazione e la nuova e esegue la convalida con uno strumento di convalida come Cosign quando viene rilevata una modifica.

Configurare un server di verifica della firma

Per garantire l'autenticità delle origini OCI, devi disporre di un server HTTP per verificare le firme. Puoi utilizzare gli esempi nel repository di esempi di Config Sync o utilizzare la tua immagine Docker.

1. Se vuoi utilizzare il Sample fornito, completa i seguenti passaggi:

   1. Clona il repository di esempio:

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

   2. Passa alla directory che contiene i campioni del server di verifica della firma:

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

2. Per creare un'immagine Docker per il server di verifica delle firme e spingerla in un registry delle immagini, esegui il seguente comando:

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

   Sostituisci SIGNATURE_VERIFICATION_SERVER_IMAGE_URL con l'URL dell'immagine del server di verifica della firma.

Effettuare l'autenticazione ai servizi

Per configurare il server di verifica delle firme, devi autenticarti in Artifact Registry, nel client Cosign e nel server webhook.

1. Crea uno spazio dei nomi:

   kubectl create ns signature-verification
   

2. Per autenticarti ad Artifact Registry con un account di servizio Kubernetes, completa i seguenti passaggi:

   1. Crea un account di servizio Kubernetes nello spazio dei nomi che hai creato:

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

   2. Aggiungi l'associazione del criterio IAM per il ruolo Artifact Registry Reader (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
      

      Sostituisci quanto segue:

      • REPOSITORY_NAME: il nome del repository Artifact Registry in cui vengono archiviate le immagini OCI.
      • REPOSITORY_LOCATION: la posizione del repository Artifact Registry.

3. Per autenticarti al client Cosign:

   1. Genera una coppia di chiavi Cosign. Questo comando genera una chiave pubblica e una chiave privata:

      cosign generate-key-pair
      

   2. Memorizza la chiave pubblica in un secret Kubernetes nello spazio dei nomi che hai creato:

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

4. Per autenticare il server di verifica della firma, completa i seguenti passaggi:

   1. Per criptare le comunicazioni all'interno del server di verifica della firma, genera un certificato TLS e una chiave privata 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. Memorizza le credenziali generate in un secret Kubernetes:

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

   3. Recupera i contenuti codificati in base64 del tls.cert. Questo è necessario per la configurazione del webhook di convalida che crei nella sezione successiva:

      cat tls.crt | base64 -w 0.
      

Esegui il deployment del webhook di ammissione

Puoi utilizzare i seguenti esempi per creare un deployment per il server di verifica della firma e una configurazione del webhook di convalida.

1. Crea un deployment per il server di verifica delle firme salvando il seguente file:

   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

   Sostituisci SIGNATURE_VERIFICATION_SERVER_IMAGE_URL con l'URL completo dell'immagine del server di verifica delle firme.

2. Applica il deployment al cluster:

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

3. Crea una configurazione webhook di convalida salvando il seguente file:

   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

   Sostituisci CA_BUNDLE con i contenuti codificati in base64 del tls.cert.

4. Applica la configurazione dell'webhook di convalida al cluster:

   kubectl apply -f signature-verification-validatingwebhookconfiguration.yaml
   

Controlla i log per verificare la presenza di errori di verifica delle immagini

Dopo aver configurato il server di verifica delle immagini, tutti i tentativi di sincronizzazione da immagini OCI non firmate dovrebbero non andare a buon fine.

Per verificare la presenza di errori di verifica della firma, visualizza i log del server di verifica della firma eseguendo i seguenti comandi:

1. Controlla i log di kubectl:

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

   Gli errori di kubectl relativi alla verifica della firma sono simili ai seguenti:

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

2. Controlla i log di Config Sync:

   nomos status
   

   Gli errori di Config Sync relativi alla verifica della firma sono simili ai seguenti:

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

Se non vengono visualizzati errori, puoi verificare che l'immagine firmata sia l'oggetto in fase di sincronizzazione controllando la configurazione di RootSync o RepoSync:

RootSync

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

Sostituisci ROOTSYNC_NAME con il nome del tuo RootSync.

RepoSync

 kubectl get reposync REPOSYNC_NAME -n REPOSYNC_NAMESPACE -oyaml

Sostituisci quanto segue:

• REPOSYNC_NAME: il nome del tuo RepoSync.
• REPOSYNC_NAMESPACE: il nome dello spazio dei nomi associato al tuo RepoSync.

Dovresti vedere l'annotazione configsync.gke.io/image-to-sync aggiunta all'oggetto RootSync o RepoSync. L'annotazione contiene l'URL dell'immagine OCI di origine e l'ultimo digest recuperato da Config Sync.

Passaggi successivi

• Scopri di più sull'installazione di Config Sync.
• Risolvi i problemi di Config Sync.