À propos des packages de parc

Cette page explique ce que sont les packages de parc, l'API FleetPackage et leur relation avec Config Sync.

Une FleetPackage est une API déclarative qui vous permet de gérer des packages dans un parc. Un package de parc est un ensemble de fichiers manifestes YAML Kubernetes qui définissent la configuration du cluster. En utilisant des packages de parc, vous pouvez déployer des packages en une seule fois ou de manière progressive sur les clusters enregistrés dans votre parc.

Vous définissez chaque objet FleetPackage une seule fois, puis vous pouvez mettre à jour ce package avec une nouvelle révision. Lorsque vous appliquez une nouvelle révision, le service de package de parc récupère ces modifications et les déploie sur vos clusters.

Avantages

Utilisez des packages de parc pour déployer des ressources Kubernetes sur des clusters enregistrés dans un parc. Une fois que vous avez créé et appliqué un package de parc, celui-ci déploie automatiquement les fichiers de configuration Kubernetes du dépôt Git sur le nouveau cluster. Les packages de parc s'appuient sur les avantages de Config Sync, comme la correction automatique des dérives, et offrent les avantages uniques 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 que vous ajoutez ultérieurement des 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 un parc entier de clusters.

• Minimiser l'impact des modifications incorrectes : choisissez un nombre maximal de clusters sur lesquels déployer des ressources en même temps. Vous pouvez surveiller de près les modifications apportées à chaque cluster pour vous assurer que les modifications incorrectes n'ont pas d'impact sur 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 seule fois par projet au lieu d'une fois par objet RootSync ou RepoSync.

Vous pouvez préférer 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 la façon dont les ressources sont déployées sur vos clusters, au-delà de ce que l'API de package de parc fournit avec des libellés et des variantes.

Conditions requises et limites

• Seuls les dépôts Git sont acceptés comme source fiable 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 Bonnes pratiques : Créer des dépôts WET.

• L'API FleetPackage n'est disponible que dans la région us-central1. Vous pouvez toujours déployer sur des clusters dans différentes régions, mais vous devez configurer Cloud Build et la 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 extraire les ressources Kubernetes de votre dépôt Git. Le service de package de parc déploie ensuite ces ressources sur vos clusters.

Comment les variantes sont 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 quels fichiers ou répertoires deviennent des variantes et quel contenu ils incluent.
2. variantSelector.variantNameTemplate: expression qui mappe chaque cluster de votre parc à l'un des noms de variante générés par variantsPattern. Cette sélection est basée sur les métadonnées d'appartenance au parc du cluster.

Correspondance 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 modèle 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 modèle 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 modèles de correspondance de fichiers présentent les limites suivantes :

• Aucun caractère générique récursif (double). Le modèle ** n'est pas accepté.
• Si un modèle 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 de variante 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 provoque un conflit de noms.

Prenons l'exemple d'un dépôt dont la structure est la 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, et donc synchroniser avec vos clusters, différents fichiers, 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 les variantes suivantes :

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

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

  • common-ingress

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

  • 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 les variantes suivantes :

  • gke-1
  • blue-green

Correspondance variantNameTemplate

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

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

Prenons les exemples suivants qui utilisent des libellés pour faire correspondre des variantes :

• variantNameTemplate: "${membership.labels['env']}" : un cluster avec le libellé 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 variante générés par votre variantsPattern sont des noms auxquels 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 utiliserez ensuite 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 libellé 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 de déploiement progressif 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 dont le libellé d'appartenance country correspond à "us" dans le 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
    selector:
      matchLabels:
        country: "us"
rolloutStrategy:
  rolling:
    maxConcurrent: 3

Étape suivante

Déployer des packages de parc