Support bundle

Générer depuis la zone d'administration (in-cluster)

GitGuardian fournit une page Support Bundle intégrée dans la zone d'administration. Cela permet aux administrateurs de générer, télécharger et éventuellement téléverser des support bundles directement vers GitGuardian. Elle est disponible pour les installations basées sur Helm et basées sur KOTS.

remarque

Les sections de configuration ci-dessous s'appliquent uniquement aux installations basées sur Helm.

Configuration

La génération in-cluster de support bundle est activée par défaut, avec toutes les ressources RBAC gérées par le chart. Aucune configuration supplémentaire n'est nécessaire pour un déploiement standard.

Clé	Valeur par défaut	Effet
rbac.enabled	true	Crée le rôle GIM avec des permissions de gestion des pods
replicated.supportBundle.rbac.createPodRole	true	Ajoute les règles create/get/delete de pods au rôle GIM
replicated.supportBundle.rbac.serviceAccount.create	true	Crée un SA dédié support-bundle pour le pod collecteur
replicated.supportBundle.rbac.role.create	true	Crée le Role à portée de namespace pour le pod collecteur
replicated.supportBundle.rbac.clusterRole.create	true	Crée un ClusterRole pour les diagnostics à l'échelle du cluster (nodes, CRDs, etc.)
replicated.supportBundle.admissionPolicy.enabled	true	Déploie une ValidatingAdmissionPolicy restreignant la création de pods (nécessite Kubernetes 1.30+)

Scénarios courants :

• Désactiver entièrement la génération in-cluster — définissez replicated.supportBundle.rbac.createPodRole: false. Cela supprime les permissions de gestion des pods du rôle GIM, empêchant l'application de créer des pods de support bundle. Vous pouvez toujours générer des bundles depuis la CLI.
• Gérer vous-même le SA support-bundle — créez le service account et ses bindings en dehors de Helm, puis référencez-le avec existingServiceAccountName et définissez role.create et clusterRole.create à false :

replicated:
  supportBundle:
    rbac:
      serviceAccount:
        create: false
        existingServiceAccountName: 'my-custom-support-bundle-sa'
      role:
        create: false
      clusterRole:
        create: false

• Désactiver la ValidatingAdmissionPolicy (nécessite Kubernetes 1.30+) — définissez replicated.supportBundle.admissionPolicy.enabled: false. Cela supprime le garde-fou qui restreint ce que le SA GIM peut créer, ce qui signifie que toute compromission de l'application pourrait permettre la création arbitraire de pods dans le namespace. Ne désactivez cette option que si votre cluster ne prend pas en charge Kubernetes 1.30+, et envisagez de la remplacer par une politique équivalente à l'aide d'OPA/Gatekeeper, Kyverno, ou tout autre admission controller.

Fonctionnement

Lorsque vous cliquez sur Generate new support bundle, l'application crée un pod de courte durée dans le même namespace. Ce pod :

1. Exécute la commande kubectl support-bundle par rapport à une spécification prédéfinie pour collecter les logs, les ressources du cluster et les données de diagnostic.
2. Sert l'archive .tar.gz résultante via un endpoint HTTP interne afin que l'application puisse la renvoyer en flux vers votre navigateur.
3. Téléverse éventuellement le bundle directement vers Replicated pour une analyse à distance par l'équipe de support GitGuardian.

Le pod a une durée de vie fixe de 1 heure (activeDeadlineSeconds: 3600). Passé ce délai, Kubernetes le termine automatiquement.

Architecture de sécurité

La génération de bundle in-cluster utilise deux service accounts distincts avec des permissions strictement séparées :

Service account	Utilisé par	Objectif
Service account GIM	pods webapp-internal-api	Crée, surveille et supprime le pod support-bundle
Service account support-bundle	Le pod support-bundle lui-même	Accès en lecture seule au namespace et (éventuellement) aux ressources du cluster

Le SA GIM ne détient jamais les larges permissions de lecture nécessaires au collecteur, et le collecteur ne détient jamais les permissions de gestion des pods.

Lorsque admissionPolicy.enabled vaut true, le chart déploie une ValidatingAdmissionPolicy (nécessite Kubernetes 1.30+) qui restreint ce que le SA GIM peut créer. Seul le pod exact attendu (nom, service account, images, commandes, variables d'environnement) est autorisé. Ceci est fortement recommandé — ne le désactivez que si votre cluster ne le prend pas en charge.

Détails RBAC

La définition complète du rôle GIM (y compris les règles de gestion des pods) est documentée dans la section Kubernetes Application RBAC.

Le service account support-bundle nécessite :

Role (à portée de namespace, requis) :

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: support-bundle
  namespace: <gitguardian_namespace>
rules:
  - apiGroups: ['*']
    resources: ['*']
    verbs: ['get', 'list', 'watch']
  - apiGroups: ['']
    resources: ['pods/exec']
    verbs: ['create']

ClusterRole (à portée de cluster, facultatif) — le nom est suffixé avec le namespace (support-bundle-<namespace>) pour éviter les collisions dans les clusters multi-tenants :

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: support-bundle-<namespace>
rules:
  - apiGroups: ['']
    resources: ['namespaces', 'nodes']
    verbs: ['get', 'list', 'watch']
  - apiGroups: ['apiextensions.k8s.io']
    resources: ['customresourcedefinitions']
    verbs: ['get', 'list', 'watch']
  - apiGroups: ['storage.k8s.io']
    resources: ['storageclasses']
    verbs: ['get', 'list', 'watch']

RBAC autogéré

Si votre organisation exige que le RBAC soit provisionné en dehors de Helm, désactivez les ressources gérées par le chart en utilisant les scénarios décrits dans la section Configuration et créez vous-même le service account, les rôles et les bindings à l'aide des définitions ci-dessus.

Identifiants de téléversement

Pour activer Upload bundle directly to Replicated, le chart crée un secret support-bundle-credentials contenant l'ID de licence Replicated et le domaine de téléversement. Pour gérer ce secret vous-même :

replicated:
  supportBundle:
    credentials:
      existingSecret: 'my-support-bundle-credentials'

Le secret doit contenir les clés license-id et upload-domain.

upload-domain doit être replicated.app par défaut et pourrait être différent à l'avenir.

Limites de ressources

Vous pouvez configurer les requêtes et limites de ressources pour les deux conteneurs du pod support-bundle :

replicated:
  supportBundle:
    resources:
      initContainer:
        requests:
          cpu: 100m
          memory: 128Mi
        limits:
          cpu: 500m
          memory: 512Mi
      mainContainer:
        requests:
          cpu: 50m
          memory: 32Mi
        limits:
          cpu: 100m
          memory: 64Mi

Dimensionner l'init container

L'init container collecte et compresse le support bundle. Sa consommation de mémoire évolue de manière linéaire avec la taille du bundle — environ ~45 Mi par Mo de bundle généré (1 Mo → ~45 Mi, 4 Mo → ~175 Mi, 10 Mo → ~400 Mi). Si l'init container dépasse sa limite de mémoire, il est OOMKilled (code de sortie 137) et la génération du bundle échoue.

Augmenter la limite CPU réduit le temps de compression mais n'affecte pas la mémoire. Les valeurs par défaut sont maintenues basses (500m) pour minimiser l'impact sur les autres charges de travail.

Pour déterminer les bonnes valeurs, générez d'abord un bundle depuis la CLI et vérifiez sa taille :

ls -lh support-bundle-*.tar.gz

Puis ajustez les ressources :

1. Limite de mémoire : pic estimé (~45 Mi × taille du bundle en Mo) × 1,5 pour la marge.
2. Requête de mémoire : la moitié de la limite (ratio requête/limite de 1:2).
3. Limite CPU : augmentez-la si vous souhaitez une génération plus rapide et que vous pouvez vous permettre le pic.

Par exemple, si votre bundle de test fait 8 Mo (pic estimé ~360 Mi) :

replicated:
  supportBundle:
    resources:
      initContainer:
        requests:
          cpu: 100m
          memory: 256Mi
        limits:
          cpu: 500m
          memory: 640Mi

astuce

Les bundles qui incluent des logs Loki ou applicatifs verbeux ont tendance à être significativement plus volumineux. Si vous augmentez replicated.supportBundle.logs.maxLines, régénérez un bundle de test pour réévaluer la taille avant d'ajuster les limites de ressources.

Générer depuis la CLI (kubectl)

Installation basée sur Helm

Pour les installations basées sur Helm, vous pouvez également générer un support bundle depuis la ligne de commande à l'aide du gestionnaire de paquets Krew :

1. Installez le plugin Krew.
2. Installez l'utilitaire support-bundle : kubectl krew install support-bundle.
3. Exécutez : kubectl support-bundle --load-cluster-specs --namespace <namespace>.

Cette commande va créer un support bundle .tar.gz dans votre répertoire courant. Vous pouvez ensuite l'envoyer au support GitGuardian, ou le téléverser depuis la CLI.

Pour personnaliser le nombre de lignes de logs capturées, définissez le paramètre maxLines comme indiqué ci-dessous. Ajustez la valeur pour capturer plus ou moins de logs selon les besoins :

replicated:
  supportBundle:
    logs:
      maxLines: 100000 # Maximum number of log lines

Si vous n'êtes pas cluster-admin dans votre cluster Kubernetes, vous devrez appliquer la configuration RBAC décrite dans la section Détails RBAC ci-dessus à votre namespace ciblé.

Installation basée sur KOTS

attention

Si vous avez précédemment installé GitGuardian sur un existing cluster à l'aide de KOTS et que vous n'avez pas les droits cluster-admin dans votre cluster Kubernetes ou que vous souhaitez limiter les permissions de la KOTS Admin Console, vous devez appliquer la configuration dans votre namespace ciblé comme décrit dans Kubernetes Application RBAC.

La KOTS Admin Console inclut un outil de diagnostic pour générer un support bundle afin d'identifier les problèmes courants. Les informations sensibles sont automatiquement expurgées. Vous pouvez également obtenir une commande pour générer manuellement un support bundle depuis une CLI.

Une fois généré, vous pouvez prévisualiser le contenu et l'envoyer directement à GitGuardian pour analyse.

Pour personnaliser le nombre de lignes de logs capturées dans le support bundle, allez dans la KOTS Admin Console et définissez le champ Maximum number of lines in logs dans la section Support Bundle de la section de configuration.

Puis enregistrez la configuration, et Deploy l'application pour appliquer la nouvelle configuration.

Téléverser un bundle depuis la CLI

Les bundles générés depuis la CLI peuvent être envoyés au support GitGuardian sans passer par la zone d'administration.

Ajoutez --auto-upload pour téléverser le bundle dès qu'il est généré :

kubectl support-bundle --load-cluster-specs --namespace <namespace> --auto-upload

Si la machine qui génère le bundle n'a pas d'accès Internet, générez-le d'abord, puis téléversez l'archive depuis une machine qui en a :

kubectl support-bundle upload support-bundle-<timestamp>.tar.gz

Les deux commandes lisent l'ID de licence et le slug d'application depuis le bundle lui-même. S'ils sont introuvables, passez-les explicitement :

Flag	Effet
--license-id	ID de licence utilisé pour authentifier le téléversement
--app-slug	Slug d'application de votre licence GitGuardian
--upload-domain	Domaine de téléversement personnalisé, par défaut replicated.app

remarque

Le téléversement nécessite un accès HTTPS sortant vers replicated.app sur le port 443, et le plugin support-bundle doit être installé sur la machine effectuant le téléversement. Dans les environnements air-gapped, copiez l'archive vers une machine ayant un accès Internet et téléversez-la depuis celle-ci. Envoyer l'archive au support GitGuardian manuellement est un dernier recours, car les bundles dépassent souvent la limite de taille des pièces jointes de notre portail de support.

Générer un support bundle lorsque le cluster Kubernetes est hors service

Lors du débogage d'un cluster Kubernetes hors ligne, vous pouvez utiliser des host collectors pour générer un support bundle même sans accès à l'Admin Console.

Pour commencer, installez l'outil support bundle sur un hôte ayant accès au cluster que vous devez déboguer :

curl -L https://github.com/replicatedhq/troubleshoot/releases/latest/download/support-bundle_linux_amd64.tar.gz | tar xzvf -

Ensuite, générez le support bundle à l'aide de la commande suivante :

./support-bundle --interactive=false https://raw.githubusercontent.com/replicatedhq/troubleshoot-specs/main/host/default.yaml

remarque

Si votre utilisateur actuel n'a pas l'accès nécessaire pour collecter les informations d'un collecteur spécifique, vous devrez peut-être exécuter la commande ci-dessus avec sudo.

Pour les environnements air gap, téléchargez le fichier YAML et copiez-le sur la machine air gap.

Pour plus de détails, consultez la documentation Replicated.