Concedere l'accesso a Config Sync al tuo repository Git

Questa pagina descrive come autenticare Config Sync nel repository Git. Config Sync richiede l'accesso di sola lettura alla tua fonte di riferimento in modo da poter leggere le configurazioni, applicarle ai cluster e mantenerle sincronizzate.

Scegliere un metodo di autenticazione

Il metodo di autenticazione che utilizzi dipende da ciò che è supportato per il tuo tipo di origine.

La seguente tabella riassume i metodi di autenticazione che puoi utilizzare con Config Sync:

Metodo Origini supportate Descrizione Limitazioni
Nessuna autenticazione Git, OCI, Helm Non è richiesta alcuna configurazione aggiuntiva. Funziona solo se la fonte attendibile è pubblica.
Coppia di chiavi SSH Git Supportato dalla maggior parte dei provider Git. Richiede la gestione delle chiavi. Non supportato per OCI o Helm.
token Git, Helm Supportato dalla maggior parte dei provider Git. Una buona alternativa se la tua organizzazione non consente l'uso di chiavi SSH. Supporta nome utente e password per Helm. Richiede la gestione dei token. I token possono scadere. Non supportato per OCI.
Service account Kubernetes OCI, Helm Utilizza IAM per concedere l'accesso ad Artifact Registry direttamente a un account di servizio Kubernetes. Richiede l'abilitazione di Workload Identity Federation for GKE sul cluster. Non supportato per Git.
Account di servizio Google Git Utilizza IAM, che evita di archiviare le credenziali nei secret di Kubernetes. Consigliato per Secure Source Manager e Cloud Source Repositories. Richiede l'abilitazione di Workload Identity Federation for GKE sul cluster. Richiede la configurazione prima e dopo l'installazione di Config Sync sui cluster. Non supportato per i repository ospitati al di fuori di Secure Source Manager o Cloud Source Repositories.
App GitHub Git Integrazione diretta con GitHub. Consente autorizzazioni granulari. Supportato solo per i repository ospitati in GitHub. Supportato solo in Config Sync versione 1.19.1 e successive.

Config Sync supporta anche i seguenti metodi di autenticazione; tuttavia, questi metodi sono consigliati solo se non puoi utilizzare una delle opzioni elencate nella tabella precedente:

  • cookiefile: potrebbe non essere supportato per tutti i provider Git. Non supportato per OCI o Helm.
  • Service account predefinito di Compute Engine (gcenode): non consigliato perché questo metodo funziona solo se Workload Identity Federation for GKE è disattivato. Supportato per Git, OCI e Helm.
  • Service account di servizio per Helm e OCI:supportato, ma non consigliato perché il metodo account di servizio Kubernetes richiede meno configurazione.

Autenticazione con i pacchetti del parco risorse

Se utilizzi i pacchetti per flotte, non devi completare le istruzioni di questa pagina. I pacchetti del parco risorse utilizzano Cloud Build per l'autenticazione a Git, il che consente di eseguire l'autenticazione una sola volta per progetto, in modo da non dover concedere l'accesso ogni volta che installi Config Sync su un cluster.

Prima di iniziare

Prima di concedere a Config Sync l'accesso di sola lettura al tuo repository Git, completa le seguenti attività:

Utilizzare una coppia di chiavi SSH

Una coppia di chiavi SSH è costituita da due file: una chiave pubblica e una chiave privata. Config Sync non supporta la creazione di passphrase. A seconda dei requisiti di sicurezza e conformità, puoi utilizzare una singola coppia di chiavi per tutti i cluster oppure una coppia di chiavi per cluster.

Per concedere a Config Sync l'accesso di sola lettura al tuo repository Git utilizzando una coppia di chiavi SSH, completa i seguenti passaggi:

  1. Crea o chiedi all'amministratore della sicurezza di fornire una coppia di chiavi SSH. Se devi creare una coppia di chiavi SSH, crea una chiave RSA a 4096 bit eseguendo questo comando:

    ssh-keygen -t rsa -b 4096 \
  -C "GIT_REPOSITORY_USERNAME" \
  -N '' \
  -f /path/to/KEYPAIR_FILENAME

    Sostituisci quanto segue:

    • GIT_REPOSITORY_USERNAME: il nome utente che vuoi che Config Sync utilizzi per l'autenticazione al repository. Se utilizzi un host di repository Git di terze parti come GitHub o vuoi utilizzare unaccount di serviziont con Secure Source Manager, ti consigliamo di utilizzare un account separato per l'autenticazione.
    • /path/to/KEYPAIR_FILENAME: il percorso del file della coppia di chiavi.

  2. Configura il repository per riconoscere la chiave pubblica appena creata. Fai riferimento alla documentazione del tuo provider host Git. Puoi trovare le istruzioni per alcuni provider di hosting Git comuni nel seguente elenco:

  3. Crea il secret git-creds con la chiave privata:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-file=ssh=/path/to/KEYPAIR_PRIVATE_KEY_FILENAME

    Sostituisci /path/to/KEYPAIR_PRIVATE_KEY_FILENAME con il nome della chiave privata.

  4. (Facoltativo, ma consigliato) Per configurare il controllo degli host noti quando utilizzi l'autenticazione SSH, aggiungi la chiave degli host noti al campo data.known_hosts nel secret git_creds.

    1. Per aggiungere la chiave known_hosts, esegui questo comando:

      kubectl edit secret git-creds --namespace=config-management-system

    2. Per aggiungere la voce known_hosts in data, esegui questo comando:

        known_hosts: KNOWN_HOSTS_KEY

      Sostituisci KNOWN_HOSTS_KEY con la chiave degli host noti.

    Per disattivare il controllo known_hosts, rimuovi il campo known_hosts dal segreto.

Quando installi Config Sync, utilizza la coppia di chiavi SSH (ssh) come tipo di autenticazione.

Quando inserisci l'URL del repository Git, l'URL deve utilizzare il formato del protocollo SSH. Il formato dell'URL varia a seconda del provider Git.

Utilizzare un cookiefile

La procedura per acquisire un cookiefile dipende dalla configurazione del tuo repository. In genere, le credenziali vengono archiviate in un file .gitcookies in una home directory oppure vengono fornite da un amministratore della sicurezza.

Per concedere a Config Sync l'accesso di sola lettura al tuo repository Git utilizzando un cookiefile, completa i seguenti passaggi:

Dopo aver creato o ottenuto il cookiefile, aggiungilo a un nuovo secret nel cluster. Per motivi di sicurezza, ti consigliamo di utilizzare il protocollo HTTPS:

kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-file=cookie_file=/path/to/COOKIEFILE

Sostituisci /path/to/COOKIEFILE con il percorso e il nome file.

Quando installi Config Sync, utilizza cookiefile (cookiefile) come tipo di autenticazione.

Utilizzare un token

Se la tua organizzazione non consente l'uso di chiavi SSH, potresti preferire l'utilizzo di un token.

Per concedere a Config Sync l'accesso di sola lettura al tuo repository Git utilizzando un token, completa i seguenti passaggi:

  1. Genera un token dal tuo provider Git. Per istruzioni, consulta la documentazione del tuo provider hostg Git. Puoi trovare le istruzioni per alcuni provider di hosting Git comuni nel seguente elenco:

  2. Dopo aver creato o ottenuto un token, aggiungilo a un nuovo secret nel cluster. Per motivi di sicurezza, ti consigliamo di utilizzare il protocollo HTTPS:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-literal=username=USERNAME \
  --from-literal=token=TOKEN

    Sostituisci quanto segue:

    • USERNAME: il nome utente che vuoi utilizzare.
    • TOKEN: il token creato nel passaggio precedente.

Quando installi Config Sync, utilizza il token (token) come tipo di autenticazione.

Utilizzare un account di servizio Google

Puoi concedere a Config Sync l'accesso a un repository nello stesso progetto del tuo cluster gestito utilizzando un account di servizio Google. Devi soddisfare i seguenti requisiti:

Per concedere a Config Sync l'accesso di sola lettura al tuo repository Git utilizzando un account di servizio Google, completa i seguenti passaggi:

  1. Per ottenere le autorizzazioni necessarie per creare un binding di policy, chiedi all'amministratore di concederti il ruolo IAM Service Account Admin (roles/iam.serviceAccountAdmin) sul account di servizio. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

    Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

  2. Se non hai ancora un account di servizio, creane uno.

  3. Concedi il ruolo IAM al account di servizio Google, a seconda del tipo di repository che utilizzi:

    Secure Source Manager

    Concedi i ruoli IAM Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor) e Secure Source Manager Repo Reader (roles/securesourcemanager.repoReader) alaccount di serviziot Google:

    • Concedi l'autorizzazione a livello di progetto se le stesse autorizzazioni si applicano a tutti i repository del progetto:

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/securesourcemanager.instanceAccessor \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/securesourcemanager.repoReader \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

      Sostituisci quanto segue:

      • PROJECT_ID: il tuo ID progetto.
      • GSA_NAME: il nome del account di servizio Google a cui vuoi connetterti a Secure Source Manager.

    • Per concedere l'autorizzazione specifica per il repository, consulta la documentazione di Secure Source Manager per Concedere agli utenti ruoli a livello di repository.

    Quando installi Config Sync, utilizza Workload Identity (gcpserviceaccount) come tipo di autenticazione. Devi anche aggiungere l'email del account di servizio.

    Secure Source Manager richiede un formato specifico per l'URL del repository: https://SSM_INSTANCE_ID-PROJECT_NUMBER-git.INSTANCE_LOCATION.sourcemanager.dev/PROJECT_ID/REPO_NAME.git.

    Cloud Source Repositories

    Concedi il ruolo IAM Cloud Source Repositories Reader (roles/source.reader) al account di servizio Google:

    • Concedi l'autorizzazione a livello di progetto se le stesse autorizzazioni si applicano a tutti i repository del progetto:

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

      Sostituisci quanto segue:

      • PROJECT_ID: il tuo ID progetto.
      • GSA_NAME: il nome del account di servizio Google a cui vuoi connetterti a Cloud Source Repositories.

    • Concedi l'autorizzazione specifica per il repository quando vuoi che gli account di servizio abbiano diversi livelli di accesso per ogni repository del tuo progetto:

      gcloud source repos set-iam-policy REPOSITORY POLICY_FILE --project=PROJECT_ID

      Sostituisci quanto segue:

      • PROJECT_ID: il tuo ID progetto.
      • REPOSITORY: il nome del repository.
      • POLICY_FILE: il file JSON o YAML che contiene la policy Identity and Access Management.

    Quando installi Config Sync, utilizza Workload Identity (gcpserviceaccount) come tipo di autenticazione. Devi anche aggiungere l'email del account di servizio.

Il passaggio successivo deve essere completato dopo la configurazione di Config Sync perché il account di servizio Kubernetes non viene creato finché non configuri Config Sync per la prima volta. Devi eseguire questa operazione una sola volta per flotta. Per creare l'associazione che consente al account di servizio Kubernetes di agire comeaccount di serviziot Google, esegui questo comando:

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

Sostituisci quanto segue:

  • FLEET_HOST_PROJECT_ID: se utilizzi Workload Identity Federation for GKE, il valore è lo stesso di PROJECT_ID. Se utilizzi la federazione delle identità per i carichi di lavoro del parco risorse per GKE, utilizza l'ID progetto del parco risorse a cui è registrato il cluster come valore.
  • GSA_NAME: l'account di servizio Google personalizzato che vuoi utilizzare per connetterti a Secure Source Manager o Cloud Source Repositories.
  • KSA_NAME: il account di servizio Kubernetes per il reconciler. Nella maggior parte dei casi, il valore è root-sync perché Config Sync crea automaticamente un oggetto RootSync denominato root-sync quando viene installato con la console Google Cloud o Google Cloud CLI. In caso contrario, utilizza root-reconciler-ROOT_SYNC_NAME come valore.

Se hai problemi di connessione a Config Sync con un account di servizio Google, consulta Risoluzione dei problemi di autorizzazione con un account di servizio Google.

Utilizzare un account di servizio Compute Engine predefinito

In alternativa a un account di servizio Google, se non hai attivato la federazione delle identità per i workload per GKE, puoi utilizzare un account di servizio Compute Engine per l'autenticazione. Questo metodo è supportato solo per i repository in Secure Source Manager e Cloud Source Repositories.

Per concedere a Config Sync l'accesso in sola lettura al tuo repository utilizzando un account di servizio predefinito di Compute Engine, concedi a quest'ultimo il ruolo roles/source.reader:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com"

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto
  • PROJECT_NUMBER: con il numero di progetto.

Quando installi Config Sync, utilizza Google Cloud Repository (gcenode) come tipo di autenticazione.

Utilizzare un'app GitHub

Se il tuo repository si trova su GitHub, puoi utilizzare l'app GitHub per connettere il tuo repository a Config Sync:

  1. Segui le istruzioni su GitHub per eseguire il provisioning di un'app GitHub e concederle l'autorizzazione a leggere dal tuo repository.

  2. Aggiungi la configurazione dell'app GitHub a un nuovo secret nel cluster utilizzando l'ID client o l'ID applicazione:

    ID client 

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-literal=github-app-client-id=CLIENT_ID \
  --from-literal=github-app-installation-id=INSTALLATION_ID \
  --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
  --from-literal=github-app-base-url=BASE_URL
    • Sostituisci CLIENT_ID con l'ID client dell'app GitHub.
    • Sostituisci INSTALLATION_ID con l'ID installazione dell'app GitHub.
    • Sostituisci /path/to/GITHUB_PRIVATE_KEY con il nome del file contenente la chiave privata.
    • Sostituisci BASE_URL con l'URL di base dell'endpoint API GitHub. Questo valore è necessario solo quando il repository non è ospitato su www.github.com. L'argomento può essere omesso e il valore predefinito è https://api.github.com/.

    ID applicazione 

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-literal=github-app-application-id=APPLICATION_ID \
    --from-literal=github-app-installation-id=INSTALLATION_ID \
    --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
    --from-literal=github-app-base-url=BASE_URL
    • Sostituisci APPLICATION_ID con l'ID applicazione per l'app GitHub.
    • Sostituisci INSTALLATION_ID con l'ID installazione dell'app GitHub.
    • Sostituisci /path/to/GITHUB_PRIVATE_KEY con il nome del file contenente la chiave privata.
    • Sostituisci BASE_URL con l'URL di base dell'endpoint API GitHub. Questo valore è obbligatorio solo se il repository non è ospitato su www.github.com. In caso contrario, l'argomento può essere omesso e il valore predefinito è https://api.github.com/.

Quando installi Config Sync, utilizza l'app GitHub (githubapp) come tipo di autenticazione.

Risoluzione dei problemi

Per assistenza nella risoluzione dei problemi relativi alla connessione di Config Sync alla tua origine attendibile, consulta i seguenti argomenti sulla risoluzione dei problemi:

Passaggi successivi