À propos des packages de parc

Cette page explique les packages de parc, l'API FleetPackage et leur lien avec Config Sync.

FleetPackage est une API déclarative qui vous permet de gérer des packages sur 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, il 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 de la dérive, 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 auxquelles il fait référence sont automatiquement déployées par le service de package de parc sur tous les clusters.

• Configurer automatiquement les 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érez 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.

• Minimisez l'impact des modifications incorrectes : choisissez un nombre maximal de clusters dans lesquels déployer des ressources à la fois. 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. Cela signifie que vous vous authentifiez une seule 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 l'un ou plusieurs des scénarios suivants s'appliquent à votre situation :

• 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 les libellés et les variantes.

Conditions requises et limites

• Seuls les dépôts Git sont acceptés comme 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 calques supplémentaires permettant de transformer la ressource stockée dans Git ne sont pas acceptés. 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 déployer 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 récupérer 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-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 trouver 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 du cluster au parc.

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 mise en 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 :

• Les caractères génériques récursifs (doubles) ne sont pas autorisés. Le modèle ** n'est pas accepté.
• Si un modèle inclut un caractère point (.), il doit être suivi d'un caractère alphanumérique.
• Les modèles ne peuvent pas inclure de guillemets simples (').
• Les noms de 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 fichiers 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 avec 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 à vos clusters et donc les synchroniser, 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érer des variantes :

  • common-ingress (à partir du 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 une variante :

  • common-ingress

• variantsPattern: "us-*" : correspond à us-central1-a et us-central1-b. Générer 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érer 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 suivantes sur l'appartenance à un parc :

• ${membership.name} : nom de l'appartenance au parc du cluster.
• ${membership.location} : emplacement de l'appartenance au parc.
• ${membership.project} : projet de membre du 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 portant le libellé env: prod est synchronisé avec une variante nommée prod.
• variantNameTemplate: "${membership.location}" : les clusters sont synchronisés avec les variantes correspondant à leur emplacement (par exemple, us-central1-a).
• variantNameTemplate: "default" : les clusters sont synchronisés 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 que vos clusters peuvent synchroniser en faisant correspondre le variantNameTemplate.

Par exemple, pour déployer 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 à partir 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

L'FleetPackage suivant utilise une stratégie Rolling 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

L'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

Étapes suivantes

Déployer des packages de parc