À propos des packages de parc

L'API déclarative FleetPackage de Config Sync vous permet de déployer et de gérer des packages de parc sur des clusters enregistrés dans un parc. Un package est un ensemble de fichiers manifestes YAML Kubernetes qui définissent les configurations de cluster. En utilisant des packages de parc, vous pouvez déployer des mises à jour de configuration sur votre parc en une seule fois ou progressivement pour réduire le risque de pannes généralisées.

Vous définissez chaque objet FleetPackage une fois, puis vous mettez à jour ce package avec de nouvelles révisions à mesure que vos configurations changent. Lorsque vous appliquez une nouvelle révision, le service de package de parc détecte automatiquement ces modifications et les déploie sur vos clusters cibles.

Avantages

Les packages de parc s'appuient sur les fonctionnalités de Config Sync, telles que la correction automatique de la dérive, et offrent les avantages suivants :

• Automatiser le déploiement des ressources : une fois que vous avez configuré un package de parc, les ressources Kubernetes vers lesquelles il pointe sont automatiquement déployées par le service de package de parc sur tous les clusters.

• Configurer automatiquement de nouveaux clusters : si vous configurez un package de parc, puis ajoutez de nouveaux clusters à un parc, toutes les ressources définies par le package de parc sont automatiquement déployées sur le nouveau cluster.

• Gérer la configuration Kubernetes à grande échelle : au lieu de gérer les clusters un par un, utilisez des packages de parc pour déployer des ressources sur l'ensemble d'un parc de clusters.

• Minimiser l'impact des modifications incorrectes : choisissez un nombre maximal de clusters sur lesquels déployer des ressources simultanément. Vous pouvez surveiller de près les modifications apportées à chaque cluster pour vous assurer que les modifications incorrectes n'affectent pas l'ensemble de votre parc.

• Simplifier la configuration de Config Sync : les packages de parc utilisent Cloud Build pour s'authentifier auprès de Git, ce qui signifie que vous vous authentifiez une fois par projet au lieu d'une fois par objet RootSync ou RepoSync.

Vous préférerez peut-être utiliser Config Sync avec des objets RootSync ou RepoSync plutôt que des packages de parc si un ou plusieurs des scénarios suivants s'appliquent à vous :

• Vous gérez un petit nombre de clusters.

• Vous avez besoin de plus de contrôle sur le déploiement des ressources sur vos clusters, au-delà de ce que l'API Fleet Package fournit avec les libellés et les variantes.

Conditions requises et limites

• Seuls les dépôts Git sont acceptés en tant que source de vérité lors de la configuration d'un package de parc.

• Les ressources Kubernetes stockées dans Git doivent représenter l'état final de la ressource. Les superpositions supplémentaires permettant de transformer la ressource stockée dans Git ne sont pas acceptées. Pour en savoir plus sur les différences entre ces ressources, consultez Bonne pratique : créer des dépôts WET.

• L'API FleetPackage n'est disponible que dans la région us-central1. Vous pouvez toujours effectuer un déploiement sur des clusters situés dans différentes régions, mais vous devez configurer Cloud Build et gcloud CLI dans us-central1.

• Le nombre maximal de packages de parc est de 300 par projet et par région.

Architecture

Vous pouvez utiliser l'API FleetPackage pour déployer des fichiers manifestes Kubernetes sur un parc de clusters. L'API FleetPackage utilise Cloud Build pour synchroniser et récupérer des ressources Kubernetes à partir de votre dépôt Git. Le service de package de parc déploie ensuite ces ressources sur vos clusters.

Comment les variantes sont-elles générées ?

Les packages de parc utilisent un système de variantes pour déployer différentes configurations de ressources Kubernetes sur différents clusters ou groupes de clusters de votre parc, mais à partir du même dépôt Git.

Deux champs de la spécification FleetPackage contrôlent le comportement des variantes :

1. resourceBundleSelector.cloudBuildRepository.variantsPattern : modèle glob utilisé pour rechercher des fichiers et des répertoires dans votre dépôt Git (sous le path spécifié ou à la racine du dépôt si path est omis). Ce modèle détermine les fichiers ou répertoires qui deviennent des variantes et le contenu qu'ils incluent.
2. variantSelector.variantNameTemplate : expression qui mappe chaque cluster de votre parc à l'un des noms de variantes générés par variantsPattern. Cette sélection est basée sur les métadonnées d'appartenance au parc du cluster.

Correspondances variantsPattern

Le champ variantsPattern est obligatoire pour spécifier comment générer des variantes à partir des configurations stockées dans votre dépôt. La correspondance utilise la logique suivante :

• Correspondance de fichier : si le format correspond à un fichier YAML, une variante est créée.

  • Nom de la variante : nom du fichier sans l'extension (par exemple, prod-config.yaml devient la variante prod-config).
  • Contenu de la variante : contenu de ce fichier unique.

• Correspondance de répertoire : si le format correspond à un répertoire, une variante est créée.

  • Nom de la variante : nom du répertoire (par exemple, le répertoire dev devient la variante dev).
  • Contenu de la variante : combinaison de tous les fichiers YAML trouvés dans ce répertoire et tous ses sous-répertoires, de manière récursive.

Les formats de correspondance de fichiers présentent les limites suivantes :

• Pas de caractères génériques récursifs (doubles). Le format ** n'est pas accepté.
• Si un format inclut un point (.), il doit être suivi d'un caractère alphanumérique.
• Les modèles ne peuvent pas inclure de guillemets simples (').
• Les noms des variantes doivent être uniques. Si votre modèle correspond à plusieurs fichiers portant le même nom (par exemple, app1/deploy.yaml et app2/deploy.yaml), les deux tentent de créer une variante nommée deploy, ce qui entraîne un conflit de noms.

Prenons l'exemple d'un dépôt ayant la structure suivante :

repo-root/
└── FleetPackages/
    └── clusters/
        ├── common-ingress.yaml
        ├── us-central1-a/
        │   ├── gke-1/
        │   │   ├── deployment.yaml
        │   │   └── service.yaml
        │   └── gke-2/
        │       ├── deployment.yaml
        │       └── service.yaml
        └── us-central1-b/
            ├── gke-1.yaml
            └── blue-green.yaml

Vous pouvez faire correspondre différents fichiers, et donc les synchroniser avec vos clusters, en fonction du type de correspondance de fichier ou de répertoire que vous définissez dans la spécification du package de parc, par exemple :

• variantsPattern: "*" : correspond à common-ingress.yaml, us-central1-a et us-central1-b. Génère des variantes :

  • common-ingress (à partir d'un fichier)
  • us-central1-a (en combinant tous les fichiers YAML de ce dossier)
  • us-central1-b (en combinant tous les fichiers YAML de ce dossier)

• variantsPattern: "*.yaml" : correspond à common-ingress.yaml. Génère la variante :

  • common-ingress

• variantsPattern: "us-*" : correspond à us-central1-a et us-central1-b. Génère des variantes :

  • us-central1-a
  • us-central1-b

• variantsPattern: "us-central1-b/*.yaml" : correspond à us-central1-b/gke-1.yaml et us-central1-b/blue-green.yaml. Génère des variantes :

  • gke-1
  • blue-green

Correspondances variantNameTemplate

Une fois les variantes définies, le champ variantNameTemplate de la section variantSelector détermine la variante appliquée à chaque cluster. Le modèle peut utiliser des variables pour accéder aux métadonnées d'appartenance au parc suivantes :

• ${membership.name} : nom de l'appartenance au parc du cluster.
• ${membership.location} : emplacement de l'appartenance au parc.
• ${membership.project} : projet d'appartenance au parc.
• ${membership.labels['KEY']} : valeur de l'étiquette KEY sur l'appartenance au parc.

Prenons l'exemple des scénarios suivants, qui utilisent des étiquettes pour faire correspondre des variantes :

• variantNameTemplate: "${membership.labels['env']}" : un cluster avec l'étiquette env: prod se synchronise avec une variante nommée prod.
• variantNameTemplate: "${membership.location}" : les clusters se synchronisent avec les variantes correspondant à leur emplacement (par exemple, us-central1-a).
• variantNameTemplate: "default" : les clusters se synchronisent avec une variante nommée default. Il s'agit du comportement par défaut si variantSelector est omis. Si votre dépôt ne contient pas de fichier nommé default.yaml ni de répertoire nommé "default", rien n'est synchronisé.

Combiner variantsPattern et variantNameTemplate

Pour que le déploiement réussisse, vous devez vous assurer que les noms de variantes générés par votre variantsPattern sont des noms avec lesquels vos clusters peuvent se synchroniser en faisant correspondre le variantNameTemplate.

Par exemple, pour déployer sur des clusters en fonction d'un libellé d'environnement, vous pouvez structurer votre dépôt Git avec des répertoires tels que dev, staging et prod. Vous utiliseriez alors la spécification de package de parc suivante :

resourceBundleSelector:
  cloudBuildRepository:
    # ... other fields
    path: "manifests"
    variantsPattern: "*" # Matches dev, staging, prod directories
variantSelector:
  variantNameTemplate: "${membership.labels['env']}"

Avec cette configuration, un cluster étiqueté env: staging reçoit le contenu du répertoire manifests/staging/.

Stratégies de déploiement

Vous pouvez utiliser des packages de parc pour déployer des ressources d'un dépôt Git sur l'ensemble de votre parc de clusters. Vous pouvez également configurer votre package de parc pour contrôler comment, où et quel type de ressources sont déployées.

La section suivante présente des exemples de différentes configurations FleetPackage. Pour en savoir plus sur l'application des packages de parc, consultez Déployer des packages de parc.

Déploiement sur tous les clusters d'un parc

Le FleetPackage suivant utilise une stratégie progressive pour déployer des ressources Kubernetes sur trois clusters à la fois et cible tous les clusters d'un parc :

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    variantsPattern: "*.yaml"
    serviceAccount: projects/my-project/serviceAccounts/[e-mail]
target:
  fleet:
    project: projects/my-project
rolloutStrategy:
  rolling:
    maxConcurrent: 3
variantSelector:
  variantNameTemplate: deployment # matches a file named deployment.yaml

Déploiement sur un sous-ensemble de clusters

Le FleetPackage suivant utilise un sélecteur de libellés pour déployer des ressources Kubernetes uniquement sur les clusters du parc dont le libellé d'appartenance country correspond à "us" :

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    variantsPattern: "*.yaml"
    serviceAccount: projects/my-project/serviceAccounts/[e-mail]
target:
  fleet:
    project: projects/my-project
    selector:
      matchLabels:
        country: "us"
rolloutStrategy:
  rolling:
    maxConcurrent: 3

Étapes suivantes

Déployer des packages de parc