Utiliser des packages de parc dans Distributed Cloud connecté

Cette page explique comment utiliser les packages de parc Config Sync dans votre environnement Google Distributed Cloud connecté, version 1.12.0. Les packages de parc sont un outil qui utilise un dépôt Git comme source unique de vérité pour la configuration de votre cluster.

Les packages de parc dans Distributed Cloud Connected utilisent la même technologie et les mêmes commandes sous-jacentes que les clusters Google Kubernetes Engine standards. La documentation GKE explique comment créer et gérer des packages de parc sur la page Déployer des packages de parc. Cette page explique comment adapter ce guide à votre environnement Distributed Cloud connecté.

Les sections suivantes expliquent ce que vous devez faire différemment pour Distributed Cloud connecté et quelles étapes de la documentation GKE vous pouvez suivre sans modification.

Conditions requises

L'utilisation des packages de parc Config Sync dans Distributed Cloud Connected est soumise aux exigences suivantes :

  • Étant donné que le contrôleur de déploiement réside dans le cloud, votre dépôt Git doit être accessible sur l'Internet public. Les serveurs Git internes ou sur site qui ne sont pas exposés publiquement ne sont pas acceptés.
  • Distributed Cloud connecté n'est compatible qu'avec la fédération d'identité de charge de travail de parc pour l'authentification auprès des services Google Cloud . Les autres méthodes d'authentification Config Sync, telles que les clés SSH ou les cookies, ne sont pas compatibles avec la connexion entre vos clusters et le dépôt de bundles versionnés. Pour en savoir plus, consultez Authentification du cluster Workload Identity.
  • Tous les clusters d'un parc doivent appartenir au même projet. Distributed Cloud Connected n'est pas compatible avec l'enregistrement de clusters dans plusieurs projets dans un seul projet central pour la gestion de parc.
  • Vos manifestes Kubernetes doivent respecter les limites des charges de travail connectées Distributed Cloud. Les manifestes qui ne respectent pas ces restrictions sont bloqués par le contrôleur d'admission du cluster.
  • Les packages de parc nécessitent Config Sync version 1.16.0 ou ultérieure.

Comportement du système

Les packages de parc dans Distributed Cloud connected présentent les comportements suivants :

  • Les packages de parc transforment vos fichiers manifestes Kubernetes en images OCI versionnées. Ces images sont stockées dans un dépôt Artifact Registry géré nommé fleet-packages, qui est automatiquement créé dans votre projet. Vos clusters extraient ces images directement du dépôt pour assurer une diffusion cohérente et fiable.
  • Les packages de parc héritent du comportement de correction de dérive de Config Sync. Les modifications manuelles apportées aux ressources d'un cluster sont automatiquement écrasées pour correspondre aux bundles OCI versionnés.
  • Si un cluster connecté Distributed Cloud passe en mode de survie, l'agent Config Sync continue d'appliquer localement la dernière configuration synchronisée. Toutefois, tout nouveau déploiement ou mise à jour du package de parc est mis en pause jusqu'à ce que la connectivité au cloud soit rétablie.
  • Les packages de parc héritent du comportement d'élagage automatique des ressources de Config Sync. Lorsque vous créez un tag dans votre dépôt Git et que vous mettez à jour la configuration du package de parc avec le nouveau tag pour lancer une synchronisation, l'agent Config Sync supprime la ressource correspondante de votre cluster si vous supprimez un fichier manifeste de votre dépôt Git.
  • Si plusieurs packages de flotte gèrent la même ressource, un conflit de propriété se produit. Si vous essayez de supprimer un package de parc alors qu'il est en conflit de propriété, la suppression peut être bloquée. Pour résoudre ce problème, modifiez l'un des packages de parc concurrents afin de supprimer la ressource en conflit avant d'essayer de supprimer le package.

Prérequis pour Distributed Cloud connecté

Avant de suivre les étapes décrites dans Déployer des packages de parc, assurez-vous que votre environnement Distributed Cloud connecté et vos autorisations utilisateur sont correctement configurés.

Mise en réseau et sécurité

Votre environnement réseau doit répondre aux exigences suivantes :

  • VPC Service Controls. Si votre projet est protégé par un périmètre de service VPC, assurez-vous que vos agents de service Cloud Build et Config Delivery, par exemple service-PROJECT_NUMBER@gcp-sa-configdelivery.iam.gserviceaccount.com, sont autorisés à franchir le périmètre et à extraire des images d'Artifact Registry. Pour en savoir plus, consultez Configurer l'intégration de VPC Service Controls.
  • Accès à la sortie. Vos clusters connectés Distributed Cloud doivent disposer d'un accès sortant à us-central1-docker.pkg.dev. Les packages de parc stockent vos ensembles de fichiers manifestes en tant qu'images OCI dans Artifact Registry. Les clusters doivent pouvoir extraire ces images directement depuis Artifact Registry.

Configuration du dépôt

Le dépôt Artifact Registry contenant vos bundles de fichiers manifestes doit se trouver dans le même projet que le package de parc et dans us-central1.

Autorisations requises

Pour effectuer les étapes dans l'environnement connecté Distributed Cloud, vous devez disposer des rôles IAM suivants sur le projet :

  • Administrateur Config Delivery (roles/configdelivery.admin) : requis pour créer et gérer des packages et des déploiements de parc
  • Administrateur Developer Connect (roles/developerconnect.admin) : requis pour créer et gérer les connexions de dépôt
  • Administrateur IAM du projet (roles/resourcemanager.projectIamAdmin) : obligatoire pour attribuer les rôles nécessaires au compte de service

Pour en savoir plus sur l'attribution de rôles, consultez Accorder, modifier et révoquer les accès aux ressources.

API requises

Vous devez activer les API pour les connexions aux dépôts et la communication sécurisée avec les clusters connectés Distributed Cloud. Pour activer les API requises, exécutez la commande gcloud services enable suivante :

gcloud services enable anthosconfigmanagement.googleapis.com \
    configdelivery.googleapis.com \
    cloudbuild.googleapis.com \
    connectgateway.googleapis.com \
    developerconnect.googleapis.com \
    artifactregistry.googleapis.com

Ces API sont requises pour les composants suivants :

  • anthosconfigmanagement.googleapis.com : gère l'agent Config Sync sur vos clusters
  • configdelivery.googleapis.com : coordonne le déploiement des ressources Kubernetes dans votre parc de clusters.
  • cloudbuild.googleapis.com : récupère vos fichiers manifestes Kubernetes depuis Git et les regroupe dans des packages versionnés.
  • connectgateway.googleapis.com : fournit une connexion sécurisée entre le service Config Delivery et vos clusters connectés Distributed Cloud.
  • developerconnect.googleapis.com : permet d'établir des connexions sécurisées à l'hôte de votre dépôt Git externe.
  • artifactregistry.googleapis.com : stocke les bundles de packages versionnés en tant qu'images OCI dans votre projet

Paramètres d'environnement par défaut

L'API Config Delivery pour les packages de parc n'est compatible qu'avec us-central1. Pour vous assurer que vos commandes sont correctement acheminées, utilisez la commande gcloud config set pour définir votre projet et votre emplacement par défaut :

  1. Définissez le projet par défaut :

    gcloud config set project PROJECT_ID

    Remplacez PROJECT_ID par l'ID du projet Google Cloud .

  2. Définissez l'emplacement par défaut des packages de parc. Toutes les connexions de dépôt Cloud Build utilisées avec les packages de parc informatique doivent se trouver dans la région us-central1.

    gcloud config set config_delivery/location us-central1

Différences de procédure

Le tableau suivant vous explique comment appliquer les étapes de Déployer des packages de parc automobile à votre environnement Distributed Cloud connecté.

Étape standard Ajustement Distributed Cloud connecté
Enregistrer des clusters dans un parc Ignorer cette étape Les clusters connectés Distributed Cloud sont automatiquement enregistrés dans un parc de votre projet lorsqu'ils sont créés.
Installer Config Sync Suivez la procédure standard, mais nous vous recommandons d'utiliser la méthode Installer sur l'ensemble du parc (par défaut pour le parc). Configurez cette méthode dans les paramètres Hub ou Flotte de la console Google Cloud . Cette implémentation garantit que tous les nœuds connectés Distributed Cloud existants ou futurs de votre zone reçoivent automatiquement l'agent Config Sync.

Pour le type de membre d'authentification, vous devez sélectionner Workload Identity.

Le compte de service que vous utilisez pour Workload Identity doit disposer du rôle roles/artifactregistry.reader dans le projet afin que l'agent Config Sync puisse extraire les bundles de fichiers manifestes du dépôt fleet-packages géré.
Créer un compte de service Suivez les instructions pour créer un compte de service pour Cloud Build et accorder les autorisations requises. Le compte de service doit se trouver dans le même projet que votre package de parc. Nous vous recommandons d'utiliser les commandes suivantes :
  1. Créez le compte de service en exécutant la commande gcloud iam service-accounts create : 
    gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME"
    Remplacez SERVICE_ACCOUNT_NAME par le nom que vous souhaitez donner au compte de service.
  2. Ajoutez les rôles Identity and Access Management obligatoires en exécutant la commande gcloud projects add-iam-policy-binding pour chacun des rôles suivants. Pour en savoir plus sur IAM, consultez la présentation d'IAM.
    • roles/configdelivery.resourceBundlePublisher : permet au compte de service de créer et de gérer des bundles de ressources et des versions.
    • roles/cloudbuild.connectionUser : permet au compte de service d'utiliser la connexion au dépôt Cloud Build.
    • roles/logging.logWriter : permet au compte de service d'écrire des journaux de compilation.
    • roles/artifactregistry.writer : permet au compte de service d'envoyer des packages groupés versionnés à Artifact Registry
    • roles/developerconnect.connectionUser : permet au compte de service d'utiliser la connexion Developer Connect.
    Le compte de service doit également être autorisé à lire les données de votre dépôt Git connecté sur votre fournisseur Git. Pour savoir comment autoriser la connexion, consultez Se connecter à un dépôt.
Identifier le nom de l'abonnement Lorsqu'une commande demande un MEMBERSHIP_NAME, utilisez le nom de votre cluster Distributed Cloud connecté. Vous pouvez trouver le nom du cluster en exécutant la commande gcloud container fleet memberships list.
Identifier un cluster Avant de cibler un cluster avec un package de parc, si vos charges de travail nécessitent une configuration réseau au niveau de l'hôte, telle que HugePages ou SR-IOV, appliquez et vérifiez les ressources NodeSystemConfigUpdate sur chaque nœud du cluster.
Identifier les tags Git Le contrôleur de déploiement exige que les tags Git soient au format de version sémantique complet (major.minor.patch). Par exemple, v1.0.0 est valide, mais v1 ne l'est pas.
Cibler des clusters spécifiques Bien que les clusters soient enregistrés automatiquement, vous devez ajouter manuellement des libellés aux appartenances aux clusters si vous souhaitez cibler des sous-ensembles de clusters à l'aide de sélecteurs de libellés.
Stratégies de déploiement Utilisez des libellés et des variantes pour cibler des clusters spécifiques. Pour Distributed Cloud connecté, les variables de métadonnées d'appartenance, telles que le projet et l'emplacement, utilisées dans vos modèles de variantes font référence aux ressources côté cloud associées à votre cluster Distributed Cloud connecté.

Les métadonnées d'appartenance spécifiques à Distributed Cloud suivantes sont disponibles pour une utilisation dans les modèles de variantes :
  • cluster_name : nom de votre cluster connecté Distributed Cloud
  • location : région Google Cloud associée au cluster
  • project : ID du projet dans lequel le cluster est enregistré.
  • labels : libellés que vous avez appliqués à l'appartenance au cluster

Procédures partagées

Pour les tâches opérationnelles suivantes, la syntaxe des commandes et le comportement des services sont identiques pour Distributed Cloud Connected et GKE standard. Lorsque vous suivez ces instructions, utilisez les paramètres et les valeurs définis dans le tableau de la section Différences de procédure de ce document.

Surveillance et dépannage

Pour surveiller plus efficacement les déploiements, utilisez l'option --format avec la commande gcloud afin d'obtenir des messages d'état détaillés lors d'un déploiement.

Par exemple, exécutez la commande gcloud container fleet packages rollouts describe suivante pour afficher un message d'état détaillé pour chaque cluster de votre parc :

gcloud container fleet packages rollouts describe ROLLOUT_NAME \
    --fleet-package=FLEET_PACKAGE_NAME \
    --format=json

Remplacez les valeurs suivantes :

  • ROLLOUT_NAME : nom du déploiement.
  • FLEET_PACKAGE_NAME : nom du package de parc.

Si une compilation échoue ou est bloquée, vous trouverez un lien vers les journaux de flux du job Cloud Build dans le résultat de la commande gcloud container fleet packages list. Si un déploiement reste à l'état PENDING ou STALLED, vérifiez la connectivité de votre matériel connecté Distributed Cloud, comme décrit dans Résoudre les problèmes de connectivité de Distributed Cloud.

Pour en savoir plus sur le diagnostic des erreurs liées à Cloud Build, consultez Résoudre les erreurs de compilation.

Vérifier l'état de la synchronisation sur le cluster

Pour vérifier que votre cluster se synchronise correctement avec le package de parc, examinez la ressource RootSync sur le cluster. Le nom de l'objet RootSync sur le cluster est identique à celui de FLEET_PACKAGE_NAME que vous avez choisi pour votre package.

Pour vérifier l'état, exécutez la commande suivante :

kubectl get rootsync FLEET_PACKAGE_NAME -n config-management-system

Une synchronisation réussie affiche l'état SYNCED. Si l'état Error s'affiche, exécutez la commande suivante pour obtenir plus de détails :

kubectl describe rootsync FLEET_PACKAGE_NAME -n config-management-system

Pour en savoir plus, consultez Surveiller les objets RootSync et RepoSync dans la documentation GKE.

Pour obtenir de l'aide sur le décodage de codes d'erreur spécifiques dans le résultat, consultez la documentation de référence sur les erreurs Config Sync.