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.
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", "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.
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
- Enter the password provided at the end of the cluster installation.
- Upload the license downloaded on the portal for instructions on how to download the license file).
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.
Check if preflight checks pass.
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.
- 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
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.