Install on an Existing cluster using KOTS

Introduction

GitGuardian can be installed on your existing Kubernetes cluster using KOTS, a kubectl plugin and KOTS Admin Console to help manage Kubernetes Off-The-Shelf software.

GitGuardian supports deployment on bare metal, private, or public clouds.

Requirements

Before starting the installation, ensure to review the system and network requirements, and download your license.

Installation

KOTS plugin

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

curl https://kots.io/install | bash

Kubernetes Application RBAC

The KOTS Admin Console will have full control over all resources across all namespaces in the cluster. More information in Replicated documentation.

If you are not cluster-admin in your Kubernetes cluster or do not want to grant the KOTS Admin Console such wide permissions, you will need to apply the below configuration in your targeted namespace <gitguardian_namespace>:

---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: kotsadm
  namespace: <gitguardian_namespace>
  labels:
    kots.io/backup: velero
    kots.io/kotsadm: 'true'

---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: kotsadm-role
  namespace: <gitguardian_namespace>
  labels:
    kots.io/backup: velero
    kots.io/kotsadm: 'true'
rules:
  - apiGroups: ['']
    resources:
      [
        'configmaps',
        'persistentvolumeclaims',
        'pods',
        'secrets',
        'services',
        'limitranges',
        'serviceaccounts',
      ]
    verbs: ['get', 'list', 'watch', 'create', 'update', 'patch', 'delete']
  - apiGroups: ['apps']
    resources:
      [
        'daemonsets',
        'deployments',
        'deployments/scale',
        'replicasets',
        'statefulsets',
      ]
    verbs: ['get', 'list', 'watch', 'create', 'update', 'patch', 'delete']
  - apiGroups: ['batch']
    resources: ['jobs', 'cronjobs']
    verbs: ['get', 'list', 'watch', 'create', 'update', 'patch', 'delete']
  - apiGroups: ['networking.k8s.io', 'extensions']
    resources: ['ingresses', 'networkpolicies']
    verbs: ['get', 'list', 'watch', 'create', 'update', 'patch', 'delete']
  - apiGroups: ['policy']
    resources: ['poddisruptionbudgets']
    verbs: ['get', 'list', 'watch', 'create', 'update', 'patch', 'delete']
  - apiGroups: ['']
    resources: ['namespaces', 'endpoints']
    verbs: ['get']
  - apiGroups: ['authorization.k8s.io']
    resources: ['selfsubjectaccessreviews', 'selfsubjectrulesreviews']
    verbs: ['create']
  - apiGroups: ['rbac.authorization.k8s.io']
    resources: ['roles', 'rolebindings']
    verbs: ['get', 'list', 'watch', 'create', 'update', 'patch', 'delete']
  - apiGroups: ['']
    resources: ['pods/log', 'pods/exec']
    verbs: ['get', 'list', 'watch', 'create']
  - apiGroups: ['batch']
    resources: ['jobs/status']
    verbs: ['get', 'list', 'watch']
  - apiGroups: ['monitoring.coreos.com']
    resources: ['servicemonitors']
    verbs: ['get', 'list', 'watch', 'create', 'update', 'patch', 'delete']
  - apiGroups: ['']
    resources: ['events']
    verbs: ['list']

---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: kotsadm-rolebinding
  namespace: <gitguardian_namespace>
  labels:
    kots.io/backup: velero
    kots.io/kotsadm: 'true'
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: kotsadm-role
subjects:
  - kind: ServiceAccount
    name: kotsadm

And proceed with the KOTS Admin Console step.

KOTS Admin Console

Once you have the plugin installed, you can install the KOTS Admin Console.

If you are cluster-admin:

kubectl kots install gitguardian

If not:

kubectl kots install --ensure-rbac=false gitguardian

You will be prompted to choose a namespace to deploy the application and a password to access the KOTS Admin Console.

Once the installation of the KOTS Admin Console is finished, a port forward will be set up, and you will be able to access the KOTS Admin Console on http://localhost:8800.

tip

KOTS Admin Console

By default, this is accessed on http://localhost:8800 using this command kubectl kots admin-console --namespace=<namespace>, which is a wrapper around kubectl port-forward. You can configure an ingress if you want a public endpoint.

Launch

Application

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

2. Upload the license downloaded on the portal for instructions on how to download the license file).

3. Configure the application. You need to fill in all the required fields:

   • Application Hostname: Enter the Fully Qualified Domain Name (FQDN) for the GitGuardian application.
   • Admin User Fields: These fields are used to create the first GitGuardian user. You'll need to change the password upon the first login.
   • Databases: You must select an external PostgreSQL and Redis, see Configure your database. When utilizing Redis Sentinel for high availability, ensure that the Redis master password matches with the Redis sentinel's password and that you're using the correct Sentinel port (default: 26379).

Additional configuration options include:

• Scaling: Adjust the number of replicas for each application component. For more details, visit the Scaling page.
• Prometheus: Activate an exporter for Prometheus.
• Ingress TLS Certificate: This is for the GitGuardian Application. You can either use auto-generated self-signed certificates or upload your own. For self-signed or private CA certificates, disable SSL verification for the GitHub webhook. Learn more on the Configure TLS certificates page.
• Load Balancer: Change the Service type can be changed from ClusterIP to LoadBalancer if needed.
• Custom Certificate Authority: Provide a custom CA if necessary.
• HTTP(s) Proxy: Refer to the proxy section if needed.

4. Check if preflight checks pass.

Requirements

Preflight checks are critical for a successful installation. The following rules apply:

• ❌ Preflight Check Failures: If preflight checks fail, the installation must not continue until the targeted environment meets all requirements. Please reach out to our support team if needed.
• ⚠️ Preflight Check Warnings: If preflight checks return warnings, the installation can proceed, but it is recommended that you address these warnings to comply with our recommendations.

5. Launch

The first installation of the application requires a few minutes to create all database objects. Once the process is completed, you will be able to log in to the dashboard using the administrator user you defined.

Save the Data Encryption Key

caution

GitGuardian encrypts all sensitive information in the database using an encryption key (aka Django Secret Key). In case of disaster recovery, this key will be needed to restore your data.

You should save it and keep it in a secure location. Use the following command to display the key:

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

If needed, specify the Kubernetes namespace with --namespace (default namespace is used if not specified).

Troubleshooting

If you encounter any issues during the installation process, you can generate a support bundle to get proper support from the GitGuardian team: see the support bundle documentation.