Skip to main content

Installation - Existing Kubernetes Cluster


GitGuardian Private Repository Monitoring is a Kubernetes application. You can install the software on an existing cluster or use our installer that has an embedded, production-ready Kubernetes distribution packaged with it.

This documentation cover the existing Kubernetes installation. For embedded clusters, please refer to this documentation.

Deployment prerequisites#


GitGuardian requires Kubernetes 1.18. We recommend using one of the version supported by the latest version of KOTS.

Cluster RBAC#

We need a dedicated namespace. The KOTS admin console will have full control over this namespace. This role will be created:

Name:         kotsadm-roleLabels:  <none>PolicyRule:  Resources  Non-Resource URLs  Resource Names  Verbs  ---------  -----------------  --------------  -----  *.*        []                 []              [*]

API resources#

We are using the following objects, you need to have the appropriate controllers and operators to handle them.

  • PersistentVolumeClaims: We are using persistent volume claims for KOTS, workers and the embedded databases.
  • IngressController: We can provide a default ingress, an Ingress Controller is needed to handle it.

Resources requests#

This is the requests the application will do with default settings:

ComponentRequired Capacity
CPU8 cores
Memory32 GB
Ephemeral disk space50GB
Persistent disk space200GB


  • If you want to historical scan large repositories, consider temporarily increasing available ephemeral disk space.
  • If you want additional workers (see application configuration below), provision 1 cpu core per additional worker.
  • See below for recommendations on large scale deployments

Large scale deployment#

For a large scale deployment, we highly recommend using a external redis and an external postgres. We recommend the following capacities for 2000 developers and/or 10000 repositories.

Redis: Use a master-slave setup for HA. We recommend an instance with at least 2 vCPU, 4GB RAM and 20GB disk

Postgresql: Use the replication mechanism your provider offers. We recommend an instance with at least 2 vCPU, 8GB RAM and 200GB disk.

Application requirements#

  • The Full Qualified Domain Name (FQDN) that you want to use for the application (ex: gitguardian.mycorp.local). This cannot be an IP.
  • A TLS certificate for HTTPS access or use the default self signed certificates.

Network requirements#

  • Outgoing access on TCP 443 to download application installer, prerequisites and application containers, and to access your VCS.
  • Incoming access for the admin console. By default, this is accessed on http://localhost:8800 using this command kubectl kots admin-console --namespace $your_namespace, which is a wrapper around kubectl port-forward. You can configure an ingress if you want a public endpoint.
  • Incoming access for the GitGuardian dashboard. By default, the GitGuardian application ships with an ingress. This should make it available on your ingress listening port for the FQDN you chose.

Go to this page, to learn more about network flows.


We recommend using external databases for GitGuardian as the embedded ones are not configured for High Availability and performance.


KOTS plugin#

First, you need to install the KOTS plugin for kubectl. You can do this with this command:

curl | bash

KOTS console#

Once you have the plugin installed, you can install the KOTS admin console:

kubectl kots install gitguardian-seal/prod

You will be be prompted to choose a namespace to deploy the application, and a password to access the admin console.

Namespace and password prompt

Once the installation of the admin console is finished, a port-forward will be setup, and you will be able to access the admin console on http://localhost:8800.

End of existing cluster installation


  1. Enter the password provided at the end of the cluster installation.

Admin console password

  1. Upload the license downloaded on the portal (see here for instructions on how to download the license file).

License upload

  1. Configure the application. You need to fill all the required fields:
    • Application URL: URL for GitGuardian application.
    • Admin user fields: Used to create the first GitGuardian user. Password will need to be changed after the first login.
  • Ingress: A default ingress is provided. More details to configured it are available here.
    • Nginx TLS certificate: You can either use auto-generated self-signed certificates or upload your own. These are not the same as the TLS certificates for the admin console used during step 1. If you choose to use self-signed certificates or your own private CA, you need to disable SSL verification for GitHub webhook.

Admin console application configuration

Other configuration options available:

  • Scaling (advanced): how many replicas for each application component.
  • Databases/datastores: Whether to use an embedded postgres/redis or an external one.

More detailed information about configuration options are available here.

  1. Check if preflight checks pass.

Admin console preflights

  1. Launch