Installer sur un cluster existant avec Helm

Introduction

GitGuardian peut être installé sur votre cluster Kubernetes existant à l’aide de Helm, un gestionnaire de paquets pour Kubernetes. GitGuardian prend en charge le déploiement sur bare metal, cloud privé ou public.

Prérequis

Infrastructure requise

1. Cluster Kubernetes : un cluster Kubernetes opérationnel. Voir les exigences système pour les détails. Pour les clusters OpenShift, consultez les directives d’installation OpenShift.

2. Base PostgreSQL : une instance PostgreSQL externe avec les extensions requises installées. Voir la configuration des bases de données pour la mise en place.

3. Instance Redis : une instance Redis dédiée. Voir les exigences système pour la configuration.

Autres exigences

4. Helm : Helm version 3.13 ou supérieure installé. Voir les exigences système pour la compatibilité des versions. Actuellement, le déploiement de l’application avec les charts Helm prend uniquement en charge Helm CLI, ArgoCD et FluxCD. Les installations Helm sont prises en charge sur les clusters AMD64 et ARM64 ; voir architecture.

5. Accès réseau : vérifiez que votre cluster respecte les exigences réseau.

6. Nom de domaine : un nom de domaine pleinement qualifié (FQDN) pour accéder à l’application. Voir les exigences système.

Exigences

Consultez l’intégralité des exigences système et réseau avant de poursuivre.

Installation

remarque

Seules les méthodes suivantes sont prises en charge pour déployer l’application avec les charts Helm : Helm CLI et ArgoCD.

Pour une installation GitGuardian en environnement airgap, utilisez un dépôt d’images privé. Les instructions détaillées se trouvent sur la page Installation en airgap.

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

Accéder au registre des charts Helm

⚠️ Utilisez la dernière version de helm.

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

Contactez l’équipe GitGuardian à support@gitguardian.com pour obtenir le mot de passe.

Pour vous connecter, utilisez la commande ci-dessous en remplaçant l’adresse e-mail par celle fournie par l’équipe GitGuardian :

helm registry login registry.replicated.com --username your.name@yourcompany.com

Personnaliser le fichier values local

Cette installation offre de nombreuses options de personnalisation. Utilisez un fichier values local (nommé local-values.yaml) pour vos personnalisations lors de l’installation d’une application Helm.

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

• hostname
• postgres
• redis
• onPrem.adminUser

Voici un exemple de fichier values couvrant ces éléments :

hostname: gitguardian.internal.yourcompany.com # Hostname où l’instance sera accessible

postgresql:
  host: gitguardian-postgres # Hôte PostgreSQL
  username: postgres # Nom d’utilisateur PostgreSQL
  database: gitguardian # Nom de la base PostgreSQL
  existingSecret: gitguardian-postgresql-secret # Secret Kubernetes contenant le mot de passe PostgreSQL
  existingSecretKeys:
    password: postgres-password # Nom de la clé contenant le mot de passe dans le secret

redis:
  main:
    host: gitguardian-redis # Hôte Redis
    tls:
      enabled: false # Activer le chiffrement TLS pour Redis
    existingSecret: gitguardian-redis-secret # Secret Kubernetes contenant le mot de passe Redis
    existingSecretKeys:
      url: redis-url # Nom de la clé contenant l’URL Redis dans le secret

onPrem:
  adminUser:
    email: your.name@yourcompany.com # E-mail de l’utilisateur administrateur de l’instance
    firstname: YourName # Prénom de l’utilisateur administrateur de l’instance

Pour plus de détails sur :

• les paramètres configurables, consultez la page Référence des values du chart Helm.
• le paramètre existingSecret et sa mise en place, consultez la page Gestion des informations sensibles avec Helm.
• la configuration des bases de données, voir Configurer votre base de données.
• la montée en charge, consultez la documentation sur le scaling.
• le proxy HTTP, voir Configurer un serveur proxy.

Activer la conformité FIPS (facultatif)

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é, l’installation utilise des versions des images d’application conformes FIPS, avec des modules cryptographiques spécialisés répondant aux Federal Information Processing Standards, pour un chiffrement renforcé des données sensibles au repos et en transit.

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 front-end de l’application est placé derrière un objet Service nommé nginx. Vous pouvez configurer l’accès de plusieurs façons :

1. Configurez le service en LoadBalancer via la valeur front.service.type. Voir Équilibreur de charge pour plus de détails.
2. Ajoutez un objet Ingress pointant vers le service nginx. Voir Ingress pour plus de détails.
3. Si votre cluster dispose d’un service mesh istio, activez-le avec la valeur istio.enabled. Les objets Gateway et VirtualService appropriés seront créés.

Notez que le service nginx n’est pas configuré avec la prise en charge SSL. Vous devez configurer et gérer votre certificat TLS via votre équilibreur de charge, votre Ingress ou votre service mesh.

Exécuter les preflights 🚦

Exigences

Les preflights sont essentiels pour une installation réussie. Règles suivantes :

• ❌ Échec des preflights : si les preflights échouent, l’installation ne doit pas continuer tant que l’environnement cible ne satisfait pas toutes les exigences. Contactez notre équipe support si besoin.
• ⚠️ Avertissements des preflights : si les preflights renvoient des avertissements, l’installation peut continuer, mais il est recommandé de traiter ces avertissements pour respecter nos recommandations.

Nous vous recommandons fortement d’exécuter notre script de preflight pour vérifier que votre cluster existant répond aux exigences GitGuardian. Récupérez le script dans notre dépôt public ici.

Indiquez un namespace Kubernetes existant avec l’option -n. Sans cela, le script s’exécute dans votre namespace par défaut. Remplacez <release-name> par le nom de release Helm souhaité.

./preflights.sh -r <release-name> -n <namespace> oci://registry.replicated.com/gitguardian/gitguardian -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é.

Indiquez un namespace Kubernetes existant avec l’option -n. Sans cela, Helm installe GitGuardian dans votre namespace par défaut. Utilisez l’option --create-namespace pour créer le namespace s’il n’existe pas.

helm install <release-name> --timeout 30m -n <namespace> --create-namespace oci://registry.replicated.com/gitguardian/gitguardian -f local-values.yaml

Remarque : l’installation peut prendre quelques minutes en raison des migrations de base de données.

Vérifier l’installation

En cas de succès, vous devriez voir une sortie similaire à :

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 être récupérées plus tard 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.

Si vous ne la définissez ni via le paramètre inline miscEncryption.djangoSecretKey ni via un secret existant avec miscEncryption.existingSecret, la clé est générée automatiquement par le chart Helm. Enregistrez-la et conservez-la 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 besoin, indiquez le namespace Kubernetes avec --namespace (le namespace par défaut est utilisé sinon).

Connexion à l’application

Après une installation réussie, récupérez votre mot de passe administrateur temporaire avec la commande suivante :

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

Si besoin, indiquez le namespace Kubernetes avec --namespace (le namespace par défaut est utilisé sinon).

Vous pouvez accéder à l’application via le nom d’hôte configuré, en vous connectant avec l’adresse e-mail fournie dans 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