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
-
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.
-
Base PostgreSQL : une instance PostgreSQL externe avec les extensions requises. Voir Configurer votre base de données.
-
Instance Redis : une instance Redis dédiée. Voir les prérequis système.
-
Registre d'images privé : un registre de conteneurs privé accessible depuis votre cluster Kubernetes pour héberger les images GitGuardian.
Prérequis supplémentaires
-
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.
-
Nom de domaine : un Fully Qualified Domain Name (FQDN). Voir les prérequis système.
-
Outils de transfert d'images : des outils comme Docker ou Skopeo pour transférer les images vers votre registre privé.
-
Accès réseau : assurez-vous que votre environnement isolé respecte les prérequis 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.
- 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
- 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
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 Type | Repository and Image Name | 2026.4 |
|---|---|---|
| GitGuardian Frontend | proxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/prm-static-chainguard | 2026.4.0 |
| GitGuardian Backend | proxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/prm-app-chainguard | 2026.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-tooling | 2026.4.0 |
| Replicated SDK — licensing | proxy.replicated.com/proxy/gitguardian/docker.io/replicated/replicated-sdk | 1.19.3 |
| Machine Learning | proxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/ml-secret-engine-app-chainguard | 0.23.0 |
| File Scanner | proxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/wolfi/apache-tika | 3.2 |
| Analytics | proxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/basalt-onprem-analytics | 0.4.0 |
| ggscout | proxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/ggscout/chainguard | 0.27.0 |
| Log collector — fluent-bit | proxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/wolfi/fluent-bit | 4.2.4 |
| Log collector — loki | proxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/wolfi/loki | 3.6.10 |
| Log collector — minio | proxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/wolfi/minio | 0.20260330 |
| Bash — Custom CA and upgrade path check (starting 2026.5.0) | proxy.replicated.com/proxy/gitguardian/ghcr.io/gitguardian/wolfi/bash | 5.3 |
Previous release image versions and tags
| Image Type | 2026.3 | 2026.2 | 2026.1 | 2025.12 | 2025.11 | 2025.10 | 2025.7 |
|---|---|---|---|---|---|---|---|
| GitGuardian Frontend | 2026.3.0 | 2026.2.0 | 2026.1.0 | 2025.12.0 | 2025.11.1 | 2025.10.0 | 2025.7.1 |
| GitGuardian Backend | 2026.3.0 | 2026.2.0 | 2026.1.0 | 2025.12.0 | 2025.11.1 | 2025.10.0 | 2025.7.1 |
| Helm Tooling | 2026.3.0 | 2026.2.0 | 2026.1.0 | 2025.12.0 | 2025.11.1 | 2025.10.0 | 2025.7.0 |
| Replicated SDK | 1.18.0 | 1.16.0 | 1.12.2 | 1.12.1 | 1.11.1 | 1.9.0 | 1.7.1 |
| Machine Learning | 0.13.0 | 0.4.3 | 20260127 | 20251212 | 20251212 | 20251023 | 20250806 |
| File Scanner | 3.2 | 3.2 | 3.2 | 3.2 | 3.2 | 3.2 | N/A |
| Analytics | 0.3.2 | 0.1.1 | 20260122 | 20251211 | N/A | N/A | N/A |
| ggscout | 0.26.0 | 0.24.0 | 0.22.0 | 0.22.0 | 0.20.0 | 0.19.0 | 0.17.5 |
| Log collector — fluent-bit | 4.2.2 | 4.2.2 | 4.2.2 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.0 |
| Log collector — loki | 3.6.7 | 3.6.5 | 3.6.3 | 3.6.2 | 3.5.8 | 3.5.3 | 3.5.1 |
| Log collector — minio | 0.20251015 | 0.20251015 | 0.20251015 | 0.20251015 | 0.20251015 | 0.20251015 | 0.20250524 |
| Bash | 5.3 | latest | latest | latest | latest | latest | N/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 :
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
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 Type | Path 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
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-fipsproxy.replicated.com/proxy/gitguardian/docker.io/gitguardian/prm-app-chainguard-fipsproxy.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 :
hostnamepostgresredisonPrem.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 :
- les paramètres configurables, consultez la page Référence des values du Helm chart.
- le paramètre
existingSecretet son processus de mise en place, consultez la page Helm Sensitive Information Management. - la configuration de la base, voir Configurer votre base de données.
- les options de scaling, consultez la documentation Scaling.
- le proxy HTTP, voir Configurer un serveur proxy.
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 :
- Configurez le service en
LoadBalancervia la valeurfront.service.type. Voir Load-balancer. - Ajoutez un objet Ingress qui route vers le service
nginx. Voir Ingress. - Si votre cluster dispose du service mesh
istio, activez-le via la valeuristio.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 🚦
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
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