feat(k3d): alternative to docker compose installation with single nod…

README.md

@@ -34,6 +34,14 @@ Additionaly, a **shell** variant of the Docker image is available, this version
 
 The project can be deployed on Kubernetes-like infrastructure (k0s, k3s, Talos, EKS, GKE, AKS...). GGBridge leverages **Helm Chart Deployment** which is an industry standard method for production environements, offering enhanced configurability and scalability for Kubernetes setups.
 
+- If you already have a Kubernetes cluster, please follow the [below documentation](#helm-deployment). 
+- If you do not have access to a Kubernetes cluster, you can deploy GGBridge along with a `k3d` cluster on a single VM. Please follow the [k3d installation documentation](./docs/k3d-install.md).
+
+> [!WARNING]  
+> The [k3d installation method](./docs/k3d-install.md) is not recommended for production due to single point of failure and lack of high availability.
+>
+> **For production setup**, we recommend deploying on a multi-node Kubernetes cluster across multiple AZs with proper redundancy and monitoring.
+
 ### Helm deployment
 
 To deploy the ggbridge client in your Kubernetes cluster using Helm, follow these steps:

docs/k3d-install.md

@@ -0,0 +1,144 @@
+# K3d cluster deployment guide
+
+This guide will help you deploy and manage local Kubernetes clusters using k3d for GGBridge deployment.
+
+> [!WARNING]  
+> This setup is not recommended for production due to single point of failure and lack of high availability.
+>
+> **For production setup**, we recommend deploying on a multi-node Kubernetes cluster across multiple AZs with proper redundancy and monitoring.
+
+## 🔧 Prerequisites
+For this installation method, you will need a single server (VM, bare metal...) and install following components:
+
+- [Docker](https://docs.docker.com/get-docker/) installed and running
+- [K3d](https://k3d.io/v5.8.3/#installation) version 5.8.3 or superior
+- [helm](https://helm.sh/docs/intro/install/) to install GGBridge in the k3d cluster
+- [kubectl](https://kubernetes.io/docs/tasks/tools/) to interact with the cluster
+
+## ⚡ Quick Start
+
+> [!IMPORTANT]  
+> There are two methods for installing GGBridge on k3d, the [Basic CLI installation](#-basic-cli-installation), and [using config files](#-config-file-installation). While the basic CLI works, we recommend the second one for a long-term and maintainable lifecycle.
+
+
+### 💻 Basic CLI installation
+
+> [!NOTE]  
+> Single node cluster here is minimal installation and low footprint
+
+
+1. Basic cluster creation (single node cluster):
+```bash
+k3d cluster create ggbridge --agents 0 \
+                            --servers 1 \
+                            --k3s-arg "--disable=traefik@server:*" \
+                            --k3s-arg "--disable=metrics-server@server:*" \
+                            --k3s-arg "--disable=local-storage@server:*" \
+                            --k3s-arg "--disable=servicelb@server:*" \
+                            --k3s-node-label "project=ggbridge@server:*" \
+                            --api-port 0.0.0.0:6445 \
+                            --image rancher/k3s:v1.33.5-k3s1 \
+                            --timeout 3m0s
+```
+2. Create the GGBridge namespace
+```bash
+kubectl create ns ggbridge
+```
+
+3. Create the client certificate secret
+
+Extract the certificate bundle downloaded from the GitGuardian dashboard and create a Kubernetes secret with the certificate files
+```bash
+kubectl create secret generic ggbridge-client-crt -n ggbridge --from-file=tls.crt \
+                                                              --from-file=tls.key \
+                                                              --from-file=ca.crt
+```
+
+4. Install GGBridge client
+
+Replace `$uid` here with the Bridge UID
+
+```bash
+helm -n ggbridge upgrade -i ggbridge oci://ghcr.io/gitguardian/ggbridge/helm/ggbridge \
+                         --set hostname="$uid.ggbridge.gitguardian.com" \
+                         --set tls.enabled=true \
+                         --set tls.existingSecret="ggbridge-client-crt" \
+                         --set tls.existingSecretKeys.caCrt="ca.crt" \
+                         --set tls.existingSecretKeys.crt="tls.crt" \
+                         --set tls.existingSecretKeys.key="tls.key" \
+                         --set image.tag="latest"
+```
+
+5. Check installation is healthy
+
+After few seconds, your client bridge should be `Running` and `2/2 Ready`.
+
+> [!NOTE]  
+> By default, 3 pods are deployed to ensure proper bridge functionality. This is the minimum required number and should not be reduced.
+
+```console
+$ kubectl get pods -n ggbridge
+NAME                                 READY   STATUS    RESTARTS   AGE
+ggbridge-client-0-58f49d45c8-rvjzt   2/2     Running   0          22s
+ggbridge-client-1-75f69cdb75-5gpsv   2/2     Running   0          22s
+ggbridge-client-2-76b98c699b-bk2q5   2/2     Running   0          22s
+```
+
+### 📝 Config file installation
+
+> [!NOTE]  
+> This installation is using declarative approach with explicit yaml files to describe cluster and Helm installation. It brings several advantages upon [basic CLI installation](#-basic-cli-installation). We recommend using this method if you are familiar with Kubernetes.
+> 
+> | Advantage             | Config File installation           | Basic CLI installation             |
+> |-----------------------|------------------------------------|------------------------------------|
+> | **Version Control**   | ✅ Easy to track changes           | ❌ Hard to version long commands   |
+> | **Reproducibility**   | ✅ Identical deployments           | ❌ Prone to human error            |
+> | **Documentation**     | ✅ Self-documenting                | ❌ Requires separate docs          |
+> | **Collaboration**     | ✅ Easy to share & review          | ❌ Command sharing is cumbersome   |
+> | **Complex Configs**   | ✅ Handles complexity well         | ❌ Commands become unwieldy        |
+> | **Schema Validation** | ✅ IDE autocompletion & validation | ❌ No validation until execution   |
+> | **Reusability**       | ✅ Template-friendly               | ❌ Hard to parameterize            |
+> | **Maintenance**       | ✅ Easy updates & modifications    | ❌ Requires command reconstruction |
+> 
+
+1. Create the cluster with [dedicated configuration file](../k3d/cluster.yaml)
+
+```bash
+k3d cluster create --config cluster.yaml
+```
+
+2. Create the client certificate secret
+
+Extract the certificate bundle downloaded from the GitGuardian dashboard and create a Kubernetes secret with the certificate files
+```bash
+kubectl create secret generic ggbridge-client-crt -n ggbridge --from-file=tls.crt \
+                                                              --from-file=tls.key \
+                                                              --from-file=ca.crt
+```
+
+3. Install GGBridge client
+
+Edit the helm [install file](../k3d/helm-ggbridge.yaml) with your Bridge UID
+```yaml
+  valuesContent: |-
+    hostname: $uid.ggbridge.gitguardian.com
+```
+Install GGBridge
+```bash
+kubectl apply -f helm-ggbridge.yaml
+```
+
+4. Check installation is healthy
+
+After few seconds, your client bridge should be `Running` and `2/2 Ready`.
+
+> [!NOTE]  
+> By default, 3 pods are deployed to ensure proper bridge functionality. This is the minimum required number and should not be reduced.
+
+```console
+$ kubectl get pods -n ggbridge
+NAME                                 READY   STATUS    RESTARTS   AGE
+ggbridge-client-0-58f49d45c8-rvjzt   2/2     Running   0          22s
+ggbridge-client-1-75f69cdb75-5gpsv   2/2     Running   0          22s
+ggbridge-client-2-76b98c699b-bk2q5   2/2     Running   0          22s
+```

k3d/cluster.yaml

@@ -0,0 +1,52 @@
+# Ref: https://k3d.io/stable/usage/configfile/#config-options
+# yaml-language-server: $schema=https://raw.githubusercontent.com/k3d-io/k3d/main/pkg/config/v1alpha5/schema.json
+---
+apiVersion: k3d.io/v1alpha5
+kind: Simple
+metadata:
+  name: ggbridge
+servers: 1
+agents: 0
+kubeAPI:
+  hostIP: "0.0.0.0"
+  hostPort: "6445"
+image: rancher/k3s:v1.33.5-k3s1
+files:
+  - description: 'GGbridge namespace'
+    source: |
+      apiVersion: v1
+      kind: Namespace
+      metadata:
+        name: ggbridge
+    destination: /var/lib/rancher/k3s/server/manifests/ggbridge-ns.yaml
+    nodeFilters:
+    - "server:*"
+options:
+  k3d:
+    wait: true
+    timeout: 3m0s
+  k3s:
+    extraArgs:
+      - arg: --tls-san=127.0.0.1
+        nodeFilters:
+          - server:*
+      - arg: --disable=traefik
+        nodeFilters:
+          - server:*
+      - arg: "--disable=metrics-server"
+        nodeFilters:
+          - "server:*"
+      - arg: "--disable=local-storage"
+        nodeFilters:
+          - "server:*"
+      - arg: "--disable=servicelb"
+        nodeFilters:
+          - "server:*"
+    nodeLabels:
+      - label: project=ggbridge
+        nodeFilters:
+          - server:*
+          - agent:*
+  kubeconfig:
+    updateDefaultKubeconfig: true
+    switchCurrentContext: true

k3d/helm-ggbridge.yaml

@@ -0,0 +1,20 @@
+---
+apiVersion: helm.cattle.io/v1
+kind: HelmChart
+metadata:
+  name: ggbridge
+  namespace: kube-system
+spec:
+  chart: oci://ghcr.io/gitguardian/ggbridge/helm/ggbridge
+  targetNamespace: ggbridge
+  valuesContent: |-
+    hostname: $uid.ggbridge.gitguardian.com
+    image:
+      tag: latest
+    tls:
+      enabled: true
+      existingSecret: ggbridge-client-crt
+      existingSecretKeys:
+        caCrt: ca.crt
+        crt: tls.crt
+        key: tls.key