Skip to content

Commit 2275a1c

Browse files
Frederic SpiersixxeL2097
Frederic Spiers
authored and
ixxeL2097
committed
feat(k3d): alternative to docker compose installation with single node cluster based on k3d
1 parent 860c426 commit 2275a1c

File tree

4 files changed

+210
-0
lines changed

4 files changed

+210
-0
lines changed

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,9 @@ Additionaly, a **shell** variant of the Docker image is available, this version
3434

3535
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.
3636

37+
- If you already have a Kubernetes cluster, please follow the [below documentation](#helm-deployment).
38+
- If you do not have a dedicated Kubernetes cluster, you can deploy GGBridge with a `k3d` cluster on a single VM. Please follow the [k3d installation documentation](./docs/k3d-install.md)
39+
3740
### Helm deployment
3841

3942
To deploy the ggbridge client in your Kubernetes cluster using Helm, follow these steps:

‎docs/k3d-install.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# K3d cluster deployment guide
2+
3+
This guide will help you deploy and manage local Kubernetes clusters using k3d for GGBridge deployment.
4+
5+
## 📋 Prerequisites
6+
For this installation method, you will need a single server (VM, bare metal...) and install following components:
7+
8+
- [Docker](https://docs.docker.com/get-docker/) installed and running
9+
- [K3d](https://k3d.io/v5.8.3/#installation) version 5.8.3 or superior
10+
- [helm](https://helm.sh/docs/intro/install/) to install GGBridge in the k3d cluster
11+
- [kubectl](https://kubernetes.io/docs/tasks/tools/) to interact with the cluster
12+
13+
## Quick Start
14+
### Basic CLI installation
15+
16+
> [!NOTE]
17+
> Single node cluster here is minimal installation and low footprint
18+
19+
20+
1. Basic cluster creation (single node cluster):
21+
```bash
22+
k3d cluster create ggbridge --agents 0 \
23+
--servers 1 \
24+
--k3s-arg "--disable=traefik@server:*" \
25+
--k3s-arg "--disable=metrics-server@server:*" \
26+
--k3s-arg "--disable=local-storage@server:*" \
27+
--k3s-arg "--disable=servicelb@server:*" \
28+
--k3s-node-label "project=ggbridge@server:*" \
29+
--api-port 0.0.0.0:6445 \
30+
--image rancher/k3s:v1.34.1-k3s1 \
31+
--timeout 3m0s
32+
```
33+
2. Create the GGBridge namespace
34+
```bash
35+
kubectl create ns ggbridge
36+
```
37+
38+
3. Create the client certificate secret
39+
40+
Extract the certificate bundle downloaded from the GitGuardian dashboard and create a Kubernetes secret with the certificate files
41+
```bash
42+
kubectl create secret generic ggbridge-client-crt -n ggbridge --from-file=tls.crt \
43+
--from-file=tls.key \
44+
--from-file=ca.crt
45+
```
46+
47+
4. Install GGBridge client
48+
49+
> [!IMPORTANT]
50+
> Replace `$uid` here with the Bridge UID
51+
52+
```bash
53+
helm -n ggbridge upgrade -i ggbridge oci://ghcr.io/gitguardian/ggbridge/helm/ggbridge \
54+
--set hostname="$uid.ggbridge.gitguardian.com" \
55+
--set tls.enable=true \
56+
--set tls.existingSecret="ggbridge-client-crt" \
57+
--set tls.existingSecretKeys.caCrt="ca.crt" \
58+
--set tls.existingSecretKeys.crt="tls.crt" \
59+
--set tls.existingSecretKeys.key="tls.key" \
60+
--set image.tag="latest"
61+
```
62+
63+
5. Check installation is healthy
64+
65+
After few seconds, your client bridge should be `Running` and `2/2 Ready`.
66+
67+
> [!NOTE]
68+
> By default, 3 pods are deployed to ensure proper bridge functionality. This is the minimum required number and should not be reduced.
69+
70+
```console
71+
$ kubectl get pods -n ggbridge
72+
NAME READY STATUS RESTARTS AGE
73+
ggbridge-client-0-58f49d45c8-rvjzt 2/2 Running 0 22s
74+
ggbridge-client-1-75f69cdb75-5gpsv 2/2 Running 0 22s
75+
ggbridge-client-2-76b98c699b-bk2q5 2/2 Running 0 22s
76+
```
77+
78+
### Config file installation
79+
80+
> [!NOTE]
81+
> 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.
82+
>
83+
> | Advantage | Config File installation | Basic CLI installation |
84+
> |-----------------------|------------------------------------|------------------------------------|
85+
> | **Version Control** | ✅ Easy to track changes | ❌ Hard to version long commands |
86+
> | **Reproducibility** | ✅ Identical deployments | ❌ Prone to human error |
87+
> | **Documentation** | ✅ Self-documenting | ❌ Requires separate docs |
88+
> | **Collaboration** | ✅ Easy to share & review | ❌ Command sharing is cumbersome |
89+
> | **Complex Configs** | ✅ Handles complexity well | ❌ Commands become unwieldy |
90+
> | **Schema Validation** | ✅ IDE autocompletion & validation | ❌ No validation until execution |
91+
> | **Reusability** | ✅ Template-friendly | ❌ Hard to parameterize |
92+
> | **Maintenance** | ✅ Easy updates & modifications | ❌ Requires command reconstruction |
93+
>
94+
95+
1. Create the cluster with [dedicated configuration file](../k3d/cluster.yaml)
96+
97+
```bash
98+
k3d cluster create --config cluster.yaml
99+
```
100+
101+
2. Create the client certificate secret
102+
103+
Extract the certificate bundle downloaded from the GitGuardian dashboard and create a Kubernetes secret with the certificate files
104+
```bash
105+
kubectl create secret generic ggbridge-client-crt -n ggbridge --from-file=tls.crt \
106+
--from-file=tls.key \
107+
--from-file=ca.crt
108+
```
109+
110+
3. Install GGBridge client
111+
112+
Edit the helm [install file](../k3d/helm-ggbridge.yaml) with your Bridge UID
113+
```yaml
114+
valuesContent: |-
115+
hostname: $uid.ggbridge.gitguardian.tech
116+
```
117+
Install GGBridge
118+
```bash
119+
kubectl apply -f helm-ggbridge.yaml
120+
```
121+
122+
4. Check installation is healthy
123+
124+
After few seconds, your client bridge should be `Running` and `2/2 Ready`.
125+
126+
> [!NOTE]
127+
> By default, 3 pods are deployed to ensure proper bridge functionality. This is the minimum required number and should not be reduced.
128+
129+
```console
130+
$ kubectl get pods -n ggbridge
131+
NAME READY STATUS RESTARTS AGE
132+
ggbridge-client-0-58f49d45c8-rvjzt 2/2 Running 0 22s
133+
ggbridge-client-1-75f69cdb75-5gpsv 2/2 Running 0 22s
134+
ggbridge-client-2-76b98c699b-bk2q5 2/2 Running 0 22s
135+
```

‎k3d/cluster.yaml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Ref: https://k3d.io/stable/usage/configfile/#config-options
2+
# yaml-language-server: $schema=https://raw.githubusercontent.com/k3d-io/k3d/main/pkg/config/v1alpha5/schema.json
3+
---
4+
apiVersion: k3d.io/v1alpha5
5+
kind: Simple
6+
metadata:
7+
name: ggbridge
8+
servers: 1
9+
agents: 0
10+
kubeAPI:
11+
hostIP: "0.0.0.0"
12+
hostPort: "6445"
13+
image: rancher/k3s:v1.34.1-k3s1
14+
files:
15+
- description: 'GGbridge namespace'
16+
source: |
17+
apiVersion: v1
18+
kind: Namespace
19+
metadata:
20+
name: ggbridge
21+
destination: /var/lib/rancher/k3s/server/manifests/ggbridge-ns.yaml
22+
nodeFilters:
23+
- "server:*"
24+
options:
25+
k3d:
26+
wait: true
27+
timeout: 3m0s
28+
k3s:
29+
extraArgs:
30+
- arg: --tls-san=127.0.0.1
31+
nodeFilters:
32+
- server:*
33+
- arg: --disable=traefik
34+
nodeFilters:
35+
- server:*
36+
- arg: "--disable=metrics-server"
37+
nodeFilters:
38+
- "server:*"
39+
- arg: "--disable=local-storage"
40+
nodeFilters:
41+
- "server:*"
42+
- arg: "--disable=servicelb"
43+
nodeFilters:
44+
- "server:*"
45+
nodeLabels:
46+
- label: project=ggbridge
47+
nodeFilters:
48+
- server:*
49+
- agent:*
50+
kubeconfig:
51+
updateDefaultKubeconfig: true
52+
switchCurrentContext: true

‎k3d/helm-ggbridge.yaml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
apiVersion: helm.cattle.io/v1
3+
kind: HelmChart
4+
metadata:
5+
name: ggbridge
6+
namespace: kube-system
7+
spec:
8+
chart: oci://ghcr.io/gitguardian/ggbridge/helm/ggbridge
9+
targetNamespace: ggbridge
10+
valuesContent: |-
11+
hostname: $uid.ggbridge.gitguardian.tech
12+
image:
13+
tag: latest
14+
tls:
15+
enabled: true
16+
existingSecret: ggbridge-client-crt
17+
existingSecretKeys:
18+
caCrt: ca.crt
19+
crt: tls.crt
20+
key: tls.key

0 commit comments

Comments
 (0)