Support bundle

Générer depuis l'admin area (in-cluster)

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

remarque

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

Configuration

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

Clé	Défaut	Effet
rbac.enabled	true	Crée le rôle GIM avec les permissions de gestion des pods
replicated.supportBundle.rbac.createPodRole	true	Ajoute les règles create/get/delete de pod au rôle GIM
replicated.supportBundle.rbac.serviceAccount.create	true	Crée un SA support-bundle dédié pour le pod collecteur
replicated.supportBundle.rbac.role.create	true	Crée le Role restreint au 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 sur 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 ceci que si votre cluster ne prend pas en charge Kubernetes 1.30+, et envisagez de le remplacer par une politique équivalente utilisant OPA/Gatekeeper, Kyverno ou tout autre admission controller.

Fonctionnement

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

1. Exécute la commande kubectl support-bundle selon une spec 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 streaming vers votre navigateur.
3. Uploade é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.

Éviction du pod

Le pod support-bundle n'a pas de contrôleur. Lorsqu'un outil l'évince, Kubernetes ne le remplace pas et le bundle est perdu : la génération s'arrête, ou le bundle n'est plus disponible au téléchargement. L'admin area n'affiche alors aucun bundle, et vous devez en générer un nouveau.

Les autoscalers de nodes et les deschedulers peuvent évincer ce pod lorsqu'ils déplacent les workloads vers moins de nodes. Pour éviter cela, utilisez replicated.supportBundle.podAnnotations pour ajouter l'annotation que votre outil respecte. Par exemple, avec Karpenter :

replicated:
  supportBundle:
    podAnnotations:
      karpenter.sh/do-not-disrupt: 'true'

Ces annotations bloquent uniquement l'éviction volontaire, pendant la durée de vie du pod (1 heure maximum). Elles n'empêchent pas les défaillances de nodes ni les interruptions Spot.

Architecture de sécurité

La génération in-cluster de bundle 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 requises par le collecteur, et le collecteur ne détient jamais de 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 attendu exact (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 RBAC de l'application Kubernetes.

Le service account support-bundle nécessite :

Role (restreint au 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 (à l'échelle du cluster, facultatif) — le nom est suffixé avec le namespace (support-bundle-<namespace>) pour éviter les collisions dans les clusters multi-tenant :

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 en utilisant les définitions ci-dessus.

Identifiants d'upload

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 d'upload. 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 requests et limits 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 linéairement 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 de 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 workloads.

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

Ajustez ensuite les ressources :

1. Limite de mémoire : pic estimé (~45 Mi × taille du bundle en Mo) × 1,5 pour la marge.
2. Request de mémoire : la moitié de la limite (ratio request/limit de 1:2).
3. Limite de CPU : augmentez-la si vous voulez une génération plus rapide et 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 d'application verbeux ont tendance à être nettement 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 en utilisant le 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 créera un support bundle .tar.gz dans votre répertoire courant. Vous pouvez ensuite l'envoyer au support GitGuardian, ou l'uploader 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 vos 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 en utilisant KOTS et que vous ne disposez pas des 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 RBAC de l'application Kubernetes.

La KOTS Admin Console inclut un outil de diagnostic permettant de générer un support bundle pour identifier les problèmes courants. Les informations sensibles sont automatiquement masqué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.

Enregistrez ensuite la configuration, et Deploy l'application pour appliquer la nouvelle configuration.

Uploader un bundle depuis la CLI

Les bundles générés depuis la CLI peuvent être envoyés au support GitGuardian sans passer par l'admin area.

Ajoutez --auto-upload pour uploader 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 uploadez l'archive depuis une machine qui en a un :

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

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

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

remarque

L'upload 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 l'upload. Dans les environnements air-gapped, copiez l'archive sur une machine ayant accès à Internet et uploadez-la depuis celle-ci. Envoyer l'archive manuellement au support GitGuardian 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 en utilisant la commande suivante :

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

remarque

Si votre utilisateur actuel ne dispose pas de 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.