Skip to content

Commit f9d3830

Browse files
ixxeL2097Frederic Spiers
ixxeL2097
and
Frederic Spiers
authored
feat(k3d): alternative to docker compose installation with single nod… (#71)
* feat(k3d): alternative to docker compose installation with single node cluster based on k3d * docs(warn): include warning for production ready setup --------- Co-authored-by: Frederic Spiers <[email protected]>
1 parent 860c426 commit f9d3830

File tree

4 files changed

+224
-0
lines changed

4 files changed

+224
-0
lines changed

‎README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,14 @@ 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 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).
39+
40+
> [!WARNING]
41+
> The [k3d installation method](./docs/k3d-install.md) is not recommended for production due to single point of failure and lack of high availability.
42+
>
43+
> **For production setup**, we recommend deploying on a multi-node Kubernetes cluster across multiple AZs with proper redundancy and monitoring.
44+
3745
### Helm deployment
3846

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

‎docs/k3d-install.md‎

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

‎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.33.5-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.com
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)