Accorder à Config Sync l'accès à votre dépôt Git

Cette page explique comment authentifier Config Sync auprès de votre dépôt Git. Config Sync a besoin d'un accès en lecture seule à votre source fiable pour pouvoir lire vos configurations, les appliquer à vos clusters et les synchroniser.

Choisir une méthode d'authentification

La méthode d'authentification que vous utilisez dépend de ce qui est pris en charge pour votre type de source.

Le tableau suivant récapitule les méthodes d'authentification que vous pouvez utiliser avec Config Sync :

Méthode Sources acceptées Description Limites
Pas d'authentification Git, OCI, Helm Aucune configuration supplémentaire n'est requise. Ne fonctionne que si votre source de vérité est publique.
Paire de clés SSH Git Compatible avec la plupart des fournisseurs Git. Nécessite la gestion des clés. Non compatible avec OCI ni Helm.
token Git, Helm Compatible avec la plupart des fournisseurs Git. Bonne alternative si votre organisation n'autorise pas l'utilisation de clés SSH. Compatible avec le nom d'utilisateur et le mot de passe pour Helm. Nécessite la gestion des jetons. Les jetons peuvent expirer. Non compatible avec l'importation des conversions hors connexion.
Compte de service Kubernetes OCI, Helm Utilise IAM pour accorder l'accès à Artifact Registry directement à un compte de service Kubernetes. La fédération d'identité de charge de travail pour GKE doit être activée sur votre cluster. Non compatible avec Git.
Compte de service Google Git Utilise IAM, ce qui évite de stocker les identifiants dans les secrets Kubernetes. Recommandé pour Secure Source Manager et Cloud Source Repositories. La fédération d'identité de charge de travail pour GKE doit être activée sur votre cluster. Nécessite une configuration avant et après l'installation de Config Sync sur vos clusters. Non compatible avec les dépôts hébergés en dehors de Secure Source Manager ou Cloud Source Repositories.
Application GitHub Git Intégration directe à GitHub. Permet des autorisations précises. Uniquement disponible pour les dépôts hébergés dans GitHub. Compatible uniquement avec Config Sync version 1.19.1 et ultérieure.

Config Sync accepte également les méthodes d'authentification suivantes. Toutefois, nous ne les recommandons que si vous ne pouvez pas utiliser l'une des options listées dans le tableau précédent :

  • Il est possible que cookiefile ne soit pas compatible avec tous les fournisseurs Git. Non compatible avec OCI ni Helm.
  • Compte de service Compute Engine par défaut (gcenode) : cette méthode n'est pas recommandée, car elle ne fonctionne que si la fédération d'identité de charge de travail pour GKE est désactivée. Compatible avec Git, OCI et Helm.
  • Compte de service Google pour Helm et OCI : compatible, mais non recommandé, car la méthode du compte de service Kubernetes nécessite moins de configuration.

S'authentifier avec des packages de parc

Si vous utilisez des packages de flotte, vous n'avez pas besoin de suivre les instructions de cette page. Les packages de parc utilisent Cloud Build pour s'authentifier auprès de Git, ce qui vous permet de vous authentifier une seule fois par projet. Vous n'avez donc pas besoin d'accorder l'accès chaque fois que vous installez Config Sync sur un cluster.

Avant de commencer

Avant d'accorder à Config Sync un accès en lecture seule à votre dépôt Git, effectuez les tâches suivantes :

Utiliser une paire de clés SSH

Une paire de clés SSH se compose de deux fichiers : une clé publique et une clé privée. Config Sync n'est pas compatible avec la création de phrases secrètes. En fonction de vos exigences en matière de sécurité et de conformité, vous pouvez utiliser une seule paire de clés pour tous les clusters ou une paire de clés par cluster.

Pour accorder à Config Sync un accès en lecture seule à votre dépôt Git à l'aide d'une paire de clés SSH, procédez comme suit :

  1. Créez une paire de clés SSH ou demandez à votre administrateur de sécurité de vous en fournir une. Si vous devez créer une paire de clés SSH, créez une clé RSA de 4 096 bits en exécutant la commande suivante :

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

    Remplacez les éléments suivants :

    • GIT_REPOSITORY_USERNAME : nom d'utilisateur avec lequel vous souhaitez que Config Sync s'authentifie auprès du dépôt. Si vous utilisez un hôte de dépôt Git tiers tel que GitHub ou si vous souhaitez employer un compte de service avec Secure Source Manager, nous vous recommandons d'utiliser un compte distinct pour l'authentification.
    • /path/to/KEYPAIR_FILENAME : chemin d'accès au fichier de paire de clés.

  2. Configurez votre dépôt pour qu'il reconnaisse la clé publique que vous venez de créer. Reportez-vous à la documentation de votre fournisseur d'hébergement Git. Vous trouverez des instructions pour certains fournisseurs d'hébergement Git courants dans la liste suivante :

  3. Créez le secret git-creds avec la clé privée :

    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

    Remplacez /path/to/KEYPAIR_PRIVATE_KEY_FILENAME par le nom de la clé privée.

  4. Facultatif, mais recommandé : Pour configurer la vérification des hôtes connus lorsque vous utilisez l'authentification SSH, ajoutez la clé des hôtes connus au champ data.known_hosts du secret git_creds.

    1. Pour ajouter la clé d'hôtes connue, exécutez la commande suivante :

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

    2. Pour ajouter l'entrée known_hosts sous data, exécutez la commande suivante :

        known_hosts: KNOWN_HOSTS_KEY

      Remplacez KNOWN_HOSTS_KEY par la clé des hôtes connus.

    Pour désactiver la vérification known_hosts, supprimez le champ known_hosts du secret.

Lorsque vous installez Config Sync, utilisez la paire de clés SSH (ssh) comme type d'authentification.

Lorsque vous saisissez l'URL de votre dépôt Git, elle doit utiliser le format du protocole SSH. Le format de l'URL diffère selon le fournisseur Git.

Utiliser un fichier de cookie

Le processus d'acquisition d'un cookiefile dépend de la configuration de votre dépôt. En général, les identifiants sont stockés dans un fichier .gitcookies d'un répertoire d'accueil ou fournis par un administrateur de la sécurité.

Pour accorder à Config Sync un accès en lecture seule à votre dépôt Git à l'aide d'un cookiefile, procédez comme suit :

Après avoir créé ou obtenu le cookiefile, ajoutez-le à un nouveau secret dans le cluster. Pour des raisons de sécurité, nous vous recommandons d'utiliser le protocole HTTPS :

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

Remplacez /path/to/COOKIEFILE par votre chemin d'accès et votre nom de fichier.

Lorsque vous installez Config Sync, utilisez cookiefile (cookiefile) comme type d'authentification.

Utiliser un jeton

Si votre organisation n'autorise pas l'utilisation de clés SSH, vous pouvez utiliser un jeton.

Pour accorder à Config Sync un accès en lecture seule à votre dépôt Git à l'aide d'un jeton, procédez comme suit :

  1. Générez un jeton auprès de votre fournisseur Git. Pour obtenir des instructions, consultez la documentation de votre fournisseur d'hébergement Git. Vous trouverez des instructions pour certains fournisseurs d'hébergement Git courants dans la liste suivante :

  2. Après avoir créé ou obtenu un jeton, ajoutez-le à un nouveau secret dans le cluster. Pour des raisons de sécurité, nous vous recommandons d'utiliser le protocole 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

    Remplacez les éléments suivants :

    • USERNAME : nom d'utilisateur que vous souhaitez utiliser
    • TOKEN : jeton que vous avez créé à l'étape précédente

Lorsque vous installez Config Sync, utilisez le jeton (token) comme type d'authentification.

Utiliser un compte de service Google

Vous pouvez autoriser Config Sync à accéder à un dépôt du même projet que votre cluster géré à l'aide d'un compte de service Google. Vous devez remplir les conditions suivantes :

Pour accorder à Config Sync un accès en lecture seule à votre dépôt Git à l'aide d'un compte de service Google, procédez comme suit :

  1. Pour obtenir les autorisations nécessaires pour créer une association de règles, demandez à votre administrateur de vous accorder le rôle IAM Administrateur de compte de service (roles/iam.serviceAccountAdmin) sur le compte de service. Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

    Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

  2. Si vous ne disposez pas d'un compte de service, créez-en un.

  3. Attribuez le rôle IAM au compte de service Google, en fonction du type de dépôt que vous utilisez :

    Secure Source Manager

    Attribuez les rôles IAM Accesseur d'instance Secure Source Manager (roles/securesourcemanager.instanceAccessor) et Lecteur de dépôt Secure Source Manager (roles/securesourcemanager.repoReader) au compte de service Google :

    • Accordez une autorisation à l'échelle du projet si les mêmes autorisations s'appliquent à tous les dépôts du projet :

      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"

      Remplacez les éléments suivants :

      • PROJECT_ID : ID de votre projet.
      • GSA_NAME : nom du compte de service Google que vous souhaitez connecter à Secure Source Manager.

    • Pour accorder des autorisations spécifiques à un dépôt, consultez la documentation Secure Source Manager sur l'attribution de rôles au niveau du dépôt aux utilisateurs.

    Lorsque vous installez Config Sync, utilisez Workload Identity (gcpserviceaccount) comme type d'authentification. Vous devez également ajouter l'adresse e-mail de votre compte de service.

    Secure Source Manager requiert un format spécifique pour l'URL du dépôt : https://SSM_INSTANCE_ID-PROJECT_NUMBER-git.INSTANCE_LOCATION.sourcemanager.dev/PROJECT_ID/REPO_NAME.git.

    Cloud Source Repositories

    Attribuez le rôle IAM Lecteur Cloud Source Repositories (roles/source.reader) au compte de service Google :

    • Accordez une autorisation à l'échelle du projet si les mêmes autorisations s'appliquent à tous les dépôts du projet :

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

      Remplacez les éléments suivants :

      • PROJECT_ID : ID de votre projet.
      • GSA_NAME : nom du compte de service Google que vous souhaitez connecter à Cloud Source Repositories.

    • Accordez une autorisation spécifique au dépôt lorsque vous souhaitez que les comptes de service disposent de différents niveaux d'accès pour chaque dépôt de votre projet :

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

      Remplacez les éléments suivants :

      • PROJECT_ID : ID de votre projet.
      • REPOSITORY : nom du dépôt
      • POLICY_FILE : fichier JSON ou YAML contenant la stratégie Identity and Access Management.

    Lorsque vous installez Config Sync, utilisez Workload Identity (gcpserviceaccount) comme type d'authentification. Vous devez également ajouter l'adresse e-mail de votre compte de service.

L'étape suivante doit être effectuée après la configuration de Config Sync, car le compte de service Kubernetes n'est créé que lorsque vous configurez Config Sync pour la première fois. Vous n'aurez à effectuer cette opération qu'une seule fois par parc. Pour créer la liaison qui permet au compte de service Kubernetes d'agir en tant que compte de service Google, exécutez la commande suivante :

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

Remplacez les éléments suivants :

  • FLEET_HOST_PROJECT_ID : si vous utilisez la fédération d'identité de charge de travail pour GKE, la valeur est identique à PROJECT_ID. Si vous utilisez la Workload Identity Federation for GKE pour votre parc, utilisez l'ID du projet dans lequel votre cluster est enregistré comme valeur.
  • GSA_NAME : compte de service Google personnalisé que vous souhaitez utiliser pour vous connecter à Secure Source Manager ou Cloud Source Repositories.
  • KSA_NAME : compte de service Kubernetes pour le rapprochement. Dans la plupart des cas, la valeur est root-sync, car Config Sync crée automatiquement un objet RootSync nommé root-sync lorsqu'il est installé avec la console Google Cloud ou la Google Cloud CLI. Sinon, utilisez root-reconciler-ROOT_SYNC_NAME comme valeur.

Si vous rencontrez des problèmes de connexion à Config Sync avec un compte de service Google, consultez Résoudre les problèmes d'autorisation avec un compte de service Google.

Utiliser un compte de service Compute Engine par défaut

Si vous n'avez pas activé Workload Identity Federation for GKE, vous pouvez utiliser un compte de service Compute Engine pour vous authentifier. Cette méthode n'est compatible qu'avec les dépôts Secure Source Manager et Cloud Source Repositories.

Pour accorder à Config Sync un accès en lecture seule à votre dépôt à l'aide d'un compte de service Compute Engine par défaut, attribuez le rôle roles/source.reader au compte de service par défaut :

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

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet
  • PROJECT_NUMBER : avec votre numéro de projet.

Lorsque vous installez Config Sync, utilisez Google Cloud Repository (gcenode) comme type d'authentification.

Utiliser une application GitHub

Si votre dépôt se trouve dans GitHub, vous pouvez utiliser l'application GitHub pour le connecter à Config Sync :

  1. Suivez les instructions sur GitHub pour provisionner une application GitHub et lui accorder l'autorisation de lire votre dépôt.

  2. Ajoutez la configuration de l'application GitHub à un nouveau secret dans le cluster en utilisant l'ID client ou l'ID d'application :

    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
    • Remplacez CLIENT_ID par l'ID client de l'application GitHub.
    • Remplacez INSTALLATION_ID par l'ID d'installation de l'application GitHub.
    • Remplacez /path/to/GITHUB_PRIVATE_KEY par le nom du fichier contenant la clé privée.
    • Remplacez BASE_URL par l'URL de base du point de terminaison de l'API GitHub. Cette valeur n'est nécessaire que lorsque le dépôt n'est pas hébergé sur www.github.com. L'argument peut être omis et est défini par défaut sur https://api.github.com/.

    ID application 

    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
    • Remplacez APPLICATION_ID par l'ID application de l'application GitHub.
    • Remplacez INSTALLATION_ID par l'ID d'installation de l'application GitHub.
    • Remplacez /path/to/GITHUB_PRIVATE_KEY par le nom du fichier contenant la clé privée.
    • Remplacez BASE_URL par l'URL de base du point de terminaison de l'API GitHub. Cette valeur n'est requise que si le dépôt n'est pas hébergé sur www.github.com. L'argument peut sinon être omis et est défini par défaut sur https://api.github.com/.

Lorsque vous installez Config Sync, utilisez l'application GitHub (githubapp) comme type d'authentification.

Dépannage

Pour obtenir de l'aide afin de résoudre les problèmes de connexion de Config Sync à votre source de vérité, consultez les rubriques de dépannage suivantes :

Étapes suivantes