Aller au contenu principal

Installer sur un cluster existant avec Helm (airgap)

Introduction

Ce guide couvre l'installation de GitGuardian en environnement airgap via Helm sur un cluster Kubernetes existant. En environnement airgap, il n'y a pas de connectivité Internet directe ; cette méthode d'installation nécessite donc de télécharger les Helm charts et les images GitGuardian depuis Internet sur une machine séparée, puis de les transférer dans votre environnement isolé.

Prérequis

Infrastructure requise

  1. Cluster Kubernetes : un cluster Kubernetes opérationnel dans votre environnement isolé. Voir les prérequis système. Pour les clusters OpenShift, consultez les recommandations d'installation OpenShift.

  2. Base PostgreSQL : une instance PostgreSQL externe avec les extensions requises. Voir Configurer votre base de données.

  3. Instance Redis : une instance Redis dédiée. Voir les prérequis système.

  4. Registre d'images privé : un registre de conteneurs privé accessible depuis votre cluster Kubernetes pour héberger les images GitGuardian.

Prérequis supplémentaires

  1. Helm : Helm version 3.13+. Voir les prérequis système. Le déploiement via Helm chart prend en charge uniquement Helm CLI, ArgoCD et FluxCD.

  2. Nom de domaine : un Fully Qualified Domain Name (FQDN). Voir les prérequis système.

  3. Outils de transfert d'images : des outils comme Docker ou Skopeo pour transférer les images vers votre registre privé.

  4. Accès réseau : assurez-vous que votre environnement isolé respecte les prérequis réseau.

Prérequis

Avant de commencer, examinez les prérequis système et réseau.

Installation

Accéder et télécharger le Helm chart GitGuardian

⚠️ Utilisez la dernière version de helm.

Le Helm chart GitGuardian est disponible dans le registre privé Replicated. La licence est incluse directement dans le Helm chart ; aucun fichier de licence séparé n'est requis.

  1. Connexion au registre Helm chart : contactez l'équipe GitGuardian à support@gitguardian.com pour obtenir le mot de passe. Connectez-vous via :
helm registry login registry.replicated.com --username your.name@yourcompany.com
  1. Télécharger le Helm chart localement : après connexion, téléchargez et extrayez le Helm chart GitGuardian dans un répertoire local (par ex. /home/user) :
cd /home/user
helm fetch oci://registry.replicated.com/gitguardian/gitguardian

Télécharger les images GitGuardian

astuce

Les images GitGuardian sont accessibles via le proxy registry Replicated. Pour le connecter à une instance Harbor ou JFrog Container Registry pour le pull-through caching, consultez Using a Registry Proxy for Helm Air Gap Installations.

Vous pouvez obtenir les versions actuelles dans la documentation de référence des values.

Voici la liste des images à télécharger et téléverser dans votre registre privé :

Image TypeRepository and Image Name2026.4
GitGuardian Frontendproxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/prm-static-chainguard2026.4.0
GitGuardian Backendproxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/prm-app-chainguard2026.4.0
Helm Tooling — preflights, support bundle, and upgrade path check (until 2026.4.0)proxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/prm-helm-tooling2026.4.0
Replicated SDK — licensingproxy.replicated.com/proxy/gitguardian/docker.io/replicated/replicated-sdk1.19.3
Machine Learningproxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/ml-secret-engine-app-chainguard0.23.0
File Scannerproxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/wolfi/apache-tika3.2
Analyticsproxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/basalt-onprem-analytics0.4.0
ggscoutproxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/ggscout/chainguard0.27.0
Log collector — fluent-bitproxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/wolfi/fluent-bit4.2.4
Log collector — lokiproxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/wolfi/loki3.6.10
Log collector — minioproxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/wolfi/minio0.20260330
Bash — Custom CA and upgrade path check (starting 2026.5.0)proxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/wolfi/bash5.3
Previous release image versions and tags
Image Type2026.32026.22026.12025.122025.112025.102025.7
GitGuardian Frontend2026.3.02026.2.02026.1.02025.12.02025.11.12025.10.02025.7.1
GitGuardian Backend2026.3.02026.2.02026.1.02025.12.02025.11.12025.10.02025.7.1
Helm Tooling2026.3.02026.2.02026.1.02025.12.02025.11.12025.10.02025.7.0
Replicated SDK1.18.01.16.01.12.21.12.11.11.11.9.01.7.1
Machine Learning0.13.00.4.32026012720251212202512122025102320250806
File Scanner3.23.23.23.23.23.2N/A
Analytics0.3.20.1.12026012220251211N/AN/AN/A
ggscout0.26.00.24.00.22.00.22.00.20.00.19.00.17.5
Log collector — fluent-bit4.2.24.2.24.2.24.0.34.0.34.0.34.0.0
Log collector — loki3.6.73.6.53.6.33.6.23.5.83.5.33.5.1
Log collector — minio0.202510150.202510150.202510150.202510150.202510150.202510150.20250524
Bash5.3latestlatestlatestlatestlatestN/A

Contactez l'équipe GitGuardian à support@gitguardian.com pour obtenir votre identifiant de licence.

Utilisez cet ID pour vous authentifier auprès du dépôt d'images GitGuardian via la commande ci-dessous. Remplacez <your_licenseID> par votre identifiant de licence réel.

LICENSE_ID="<your_licenseID>";
echo "{\"auths\": {\"proxy.replicated.com\": {\"auth\": \"$(echo -n "${LICENSE_ID}:${LICENSE_ID}" | base64)\"}, \"registry.replicated.com\": {\"auth\": \"$(echo -n "${LICENSE_ID}:${LICENSE_ID}" | base64)\"}}}" > ~/.docker/config.json

Exemple de téléchargement des images via docker pull avec la dernière release :

Architecture des images

Toutes les images GitGuardian sont publiées sous forme de manifestes multi-architecture (multi-arch). La bonne variante d'image est sélectionnée automatiquement selon l'architecture du host Docker.

docker pull proxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/prm-static-chainguard:2026.4.0
docker pull proxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/prm-app-chainguard:2026.4.0
docker pull proxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/prm-helm-tooling:2026.4.0
docker pull proxy.replicated.com/proxy/gitguardian/docker.io/replicated/replicated-sdk:1.19.3
docker pull proxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/ml-secret-engine-app-chainguard:0.23.0
docker pull proxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/wolfi/apache-tika:3.2
docker pull proxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/basalt-onprem-analytics:0.4.0
docker pull proxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/ggscout/chainguard:0.27.0
docker pull proxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/ggscout/chainguard-bash:0.27.0
docker pull proxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/wolfi/fluent-bit:4.2.4
docker pull proxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/wolfi/loki:3.6.10
docker pull proxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/wolfi/minio:0.20260330
docker pull proxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/wolfi/bash:5.3

Vous pouvez vérifier que les images ont été correctement téléchargées et les téléverser vers votre registre privé.

docker images | grep replicated
info

Pour ce processus, vous pouvez utiliser un outil comme Skopeo pour gérer les transferts d'images. De plus, si vous devez configurer un proxy pour accéder au registre Replicated, consultez la documentation Docker.

Transférer les images GitGuardian

Assurez-vous que la structure de répertoires suivante est respectée dans votre registre privé :

Image TypePath and image name
GitGuardian Frontend/gitguardian/prm-static-chainguard
GitGuardian Frontend (FIPS)/gitguardian/prm-static-chainguard-fips
GitGuardian Backend/gitguardian/prm-app-chainguard
GitGuardian Backend (FIPS)/gitguardian/prm-app-chainguard-fips
Helm Tooling/gitguardian/prm-helm-tooling
Replicated SDK/replicated/replicated-sdk
Machine Learning/gitguardian/ml-secret-engine-app-chainguard
Machine Learning (FIPS)/gitguardian/ml-secret-engine-app-chainguard-fips
File Scanner/gitguardian/wolfi/apache-tika
Analytics/gitguardian/basalt-onprem-analytics
ggscout/gitguardian/ggscout/chainguard
ggscout (bash)/gitguardian/ggscout/chainguard-bash
Log collector — fluent-bit/gitguardian/wolfi/fluent-bit
Log collector — loki/gitguardian/wolfi/loki
Log collector — minio/gitguardian/wolfi/minio
Bash/gitguardian/wolfi/bash

Conformité FIPS pour les installations Airgap

info

La conformité FIPS (Federal Information Processing Standards) est disponible pour les installations Helm en airgap, avec des étapes supplémentaires.

Si vous avez besoin de modules cryptographiques conformes FIPS pour votre installation airgap, téléchargez les images FIPS (avec le suffixe -fips) :

  • proxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/prm-static-chainguard-fips
  • proxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/prm-app-chainguard-fips
  • proxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/ml-secret-engine-app-chainguard-fips

RBAC de l'application Kubernetes

Les rôles RBAC suivants sont nécessaires au bon fonctionnement de l'application : ils permettent au Replicated SDK de valider les droits liés à la licence du client, garantissent que les versions non « skippables » ne sont pas contournées lors des mises à niveau, et autorisent la génération in-cluster du support bundle (limitée par une ValidatingAdmissionPolicy).

Si vous n'êtes pas cluster-admin dans votre cluster Kubernetes, vous devrez appliquer la configuration ci-dessous dans votre namespace cible <gitguardian_namespace> :

Rôles RBAC pour l'installation Helm
# GitGuardian Role
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: gim-role
rules:
- apiGroups:
- ''
resources:
- configmaps
- secrets
verbs:
- get
- list
- watch
# Spawns the support-bundle collector pod. Locked down by a
# ValidatingAdmissionPolicy (Kubernetes 1.30+) — see Troubleshoot > Support.
- apiGroups:
- ''
resources:
- pods
verbs:
- create
- apiGroups:
- ''
resources:
- pods
- pods/log
verbs:
- get
- delete
resourceNames:
- gitguardian-support-bundle

# GitGuardian RoleBinding
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: gim-rolebinding
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: gim-role
subjects:
- kind: ServiceAccount
name: gim-migration
- kind: ServiceAccount
name: gim

# Upgrade-path-check Role
---
kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: upgrade-path-check
rules:
- apiGroups:
- ''
resources:
- configmaps
verbs:
- get
- list

# Upgrade-path-check RoleBindng
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: upgrade-path-check
roleRef:
kind: Role
name: upgrade-path-check
apiGroup: rbac.authorization.k8s.io
subjects:
- kind: ServiceAccount
name: upgrade-path-check

# Replicated SDK Role
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: replicated-role
rules:
- apiGroups:
- ''
resources:
- configmaps
- persistentvolumeclaims
- pods
- secrets
- services
verbs:
- get
- list
- watch
- apiGroups:
- apps
resources:
- daemonsets
- deployments
- replicasets
- statefulsets
verbs:
- get
- list
- watch
- apiGroups:
- networking.k8s.io
- extensions
resources:
- ingresses
verbs:
- get
- list
- watch
- apiGroups:
- ''
resources:
- secrets
verbs:
- create
- apiGroups:
- ''
resources:
- secrets
verbs:
- update
resourceNames:
- replicated
- replicated-instance-report
- replicated-custom-app-metrics-report
- replicated-meta-data

# Replicated SDK RoleBinding
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: replicated-rolebinding
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: replicated-role
subjects:
- kind: ServiceAccount
name: replicated

# Support Bundle
# Below role is mandatory
---
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']
# This role is optional and is used to retrieve cluster-scoped information, which can be useful for troubleshooting
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: support-bundle
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']

Personnaliser le fichier de values local

Cette installation propose plusieurs options de personnalisation. Utilisez un fichier de values local (nommé local-values.yaml) pour vos personnalisations lors de l'installation de toute application Helm.

Assurez-vous que votre fichier de values configure ces éléments essentiels :

Au minimum, vos values doivent configurer les éléments suivants :

  • hostname
  • postgres
  • redis
  • onPrem.adminUser

Voici un exemple de fichier de values couvrant ces éléments, adapté pour une installation airgap :

hostname: gitguardian.internal.yourcompany.com # Hostname where the instance will be accessed

# Airgap-specific configuration
global:
imageRegistry: docker.internal/example/path # Location of the GitGuardian images in your private registry
image:
registry: docker.internal/example/path # Location of the GitGuardian images (same as imageRegistry)
imagePullSecrets:
- name: pull-secret # Existing docker secret used to pull images from your private registry

proxy:
noProxyHostNames:
- 127.0.0.1
- 10.0.0.0/8
existingSecret: 'gim-proxy'
existingSecretKeys:
httpProxyUrl: 'http_proxy' # Secret should contain: http://username:password@proxy.company.com:8080
httpsProxyUrl: 'https_proxy' # Secret should contain: https://username:password@proxy.company.com:8080

replicated:
isAirgap: false # Set to true only for environments without Internet access and no HTTP proxy configured
privateCASecret: # optional if you are using a custom CA
name: custom-ca-secret-name
key: 'custom-ca.pem'
extraEnv:
- name: NO_PROXY
valueFrom:
configMapKeyRef:
name: gim-config
key: 'NO_PROXY'
- name: HTTP_PROXY
valueFrom:
secretKeyRef:
name: 'gim-proxy'
key: 'http_proxy' # Example: http://username:password@proxy.company.com:8080
- name: HTTPS_PROXY
valueFrom:
secretKeyRef:
name: 'gim-proxy'
key: 'https_proxy' # Example: https://username:password@proxy.company.com:8080

postgresql:
host: gitguardian-postgres # PostgreSQL host
username: postgres # PostgreSQL username
database: gitguardian # PostgreSQL database name
existingSecret: gitguardian-postgresql-secret # Kubernetes secret where to check the PostgreSQL password
existingSecretKeys:
password: postgres-password # Name of the key containing password in the secret

redis:
main:
host: gitguardian-redis # Redis host
tls:
enabled: false # Set TLS encryption for Redis
existingSecret: gitguardian-redis-secret # Kubernetes secret where to check the Redis password
existingSecretKeys:
url: redis-url # Name of the key containing redis url in the secret

onPrem:
adminUser:
email: your.name@yourcompany.com # email of the instance admin user
firstname: YourName # name of the instance admin user

Notes importantes pour la configuration airgap :

Remplacez docker.internal/example/path par votre registre privé et le chemin approprié où les images sont stockées dans votre registre. Veillez à respecter la structure de répertoires spécifiée dans la section « Transférer les images GitGuardian ».

Pour des recommandations détaillées sur :

Activer la conformité FIPS (optionnel)

Si vous avez besoin de modules cryptographiques conformes FIPS, vous pouvez les activer en ajoutant ce qui suit à votre fichier local-values.yaml :

global:
fips:
enabled: true

Lorsque FIPS est activé en environnement airgap, assurez-vous d'avoir téléchargé et téléversé les images FIPS comme indiqué dans la section Conformité FIPS pour les installations Airgap ci-dessus. L'installation utilisera automatiquement les versions conformes FIPS des images d'application qui incluent des modules cryptographiques spécialisés répondant aux Federal Information Processing Standards.

Pour plus d'informations sur la conformité FIPS et les considérations de sécurité, consultez la page Recommandations de sécurité.

Configurer l'accès réseau à l'application

Le frontend de l'application est derrière un objet Service nommé nginx. Vous pouvez configurer l'accès à l'application de différentes manières :

  1. Configurez le service en LoadBalancer via la valeur front.service.type. Voir Load-balancer.
  2. Ajoutez un objet Ingress qui route vers le service nginx. Voir Ingress.
  3. Si votre cluster dispose du service mesh istio, activez-le via la valeur istio.enabled. Cela créera les objets Gateway et VirtualService appropriés.

Notez que le service nginx n'est pas configuré avec la prise en charge SSL. Vous devez le configurer et gérer votre certificat TLS via votre Load-Balancer, Ingress ou Service Mesh.

Exécuter les preflight checks 🚦

Prérequis

Les preflight checks sont essentiels pour une installation réussie. Les règles suivantes s'appliquent :

  • Échec des preflight checks : si les preflight checks échouent, l'installation ne doit pas continuer tant que l'environnement cible ne satisfait pas tous les prérequis. Contactez notre équipe support si nécessaire.
  • ⚠️ Avertissements des preflight checks : si les preflight checks renvoient des avertissements, l'installation peut continuer, mais il est recommandé de les traiter pour respecter nos recommandations.

Nous recommandons fortement d'exécuter notre script de preflights pour vérifier que votre cluster existant respecte les prérequis GitGuardian. Récupérez le script depuis notre dépôt public ici.

Indiquez un namespace Kubernetes existant via l'option -n. Sinon, le script s'exécutera dans votre namespace par défaut. Remplacez <release-name> par le nom de release Helm souhaité.

Pour les installations airgap, utilisez le fichier Helm chart local :

./preflights.sh -r <release-name> -n <namespace> gitguardian-<version>.tgz -f local-values.yaml

Installer l'application

Utilisez la commande suivante pour installer l'application avec votre fichier local-values.yaml. Remplacez <release-name> par le nom de release Helm souhaité.

Précisez un namespace Kubernetes existant avec l'option -n. Sinon, Helm installe GitGuardian dans votre namespace par défaut. Utilisez l'option --create-namespace pour créer le namespace s'il n'existe pas.

Pour les installations airgap, utilisez le fichier Helm chart local au lieu du dépôt distant :

helm install <release-name> --timeout 30m -n <namespace> --create-namespace gitguardian-<version>.tgz -f local-values.yaml

Note : l'installation peut prendre quelques minutes en raison des migrations de base.

Vérifier l'installation

En cas de succès, vous devriez voir la sortie suivante :

NAME: <release-name>
LAST DEPLOYED: Mon May 15 16:15:56 2023
NAMESPACE: <namespace>
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
Thank you for installing GitGuardian Internal Monitoring.

Ces notes peuvent ensuite être récupérées avec helm get notes <release-name>

Conserver la clé de chiffrement des données

attention

GitGuardian chiffre toutes les informations sensibles dans la base à l'aide d'une clé de chiffrement (aussi appelée Django Secret Key). En cas de reprise après sinistre, cette clé sera nécessaire pour restaurer vos données.

Lorsque vous ne la précisez pas via le paramètre inline miscEncryption.djangoSecretKey ou via un secret existant avec miscEncryption.existingSecret, la clé de chiffrement est générée automatiquement par le Helm chart. Vous devriez la sauvegarder et la conserver dans un emplacement sûr. Utilisez la commande suivante pour afficher la clé :

kubectl get secrets gim-secrets --namespace=<namespace> -o jsonpath='{.data.DJANGO_SECRET_KEY}' | base64 -d

Si nécessaire, précisez le namespace Kubernetes avec --namespace (le namespace par défaut est utilisé sinon).

Connexion à l'application

Après une installation réussie, vous devrez récupérer votre mot de passe administrateur temporaire. Utilisez la commande suivante :

kubectl get secrets gim-secrets --namespace=<namespace> -o jsonpath='{.data.ADMIN_PASSWORD}'| base64 -d

Si nécessaire, précisez le namespace Kubernetes avec --namespace (le namespace par défaut est utilisé sinon).

Vous pouvez accéder à l'application via le hostname fourni, en vous connectant avec l'e-mail de onPrem.adminUser.email et le mot de passe temporaire.

Dépannage

Si vous rencontrez des problèmes durant l'installation, vous pouvez générer un support bundle pour permettre à l'équipe GitGuardian de diagnostiquer et résoudre les problèmes plus efficacement. Consultez la documentation du support bundle pour des instructions détaillées.

Prochaines étapes

Après une installation réussie :

  • Accédez à votre instance GitGuardian via le hostname configuré
  • Connectez-vous avec les identifiants administrateur que vous avez définis (changez le mot de passe temporaire à la première connexion)
  • Configurez les paramètres d'e-mail pour les notifications
  • Mettez en place l'intégration SSO et SCIM (optionnel)
  • Intégrez vos premiers dépôts pour démarrer la détection des secrets