refactor(tunneling): remove HTTPS support for Rtunnel and improve documentation and Helm chart on TLS Rtunnel (#76)

* fix(helm): ingress TLS bad rendering

* refactor(helm): remove HTTPS reverse tunneling

---------

Co-authored-by: Frederic Spiers <[email protected]>

Author: ixxeL2097

docs/client-log-fetcher.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
+mkdir -p "logs_$TIMESTAMP"
+
+for i in 0 1 2; do
+  for c in nginx ggbridge; do
+    echo -e "=== INDEX: $i - CONTAINER: $c - $(date) ===\n" > "logs_$TIMESTAMP/index-${i}_${c}.log"
+    kubectl logs -l "app.kubernetes.io/instance=ggbridge,index=$i" -c "$c" -n ggbridge --tail=1000 2>&1 | sed 's/\x1b\[[0-9;]*[mGKHF]//g' >> "logs_$TIMESTAMP/index-${i}_${c}.log"
+  done
+done
+
+tar -czf "ggbridge_logs_$TIMESTAMP.tgz" "logs_$TIMESTAMP"
+rm -rf "logs_$TIMESTAMP"
+echo "✅ Archive created: ggbridge_logs_$TIMESTAMP.tgz"

docs/troubleshoot.md

@@ -12,6 +12,25 @@ GGBridge provides two types of images for different use cases:
 - **Docker Compose**: Update the image tag in `docker-compose.yaml`
 - **Helm**: Update the image tag in `values.yaml`
 
+### Basic checks
+
+Some very basic commands can be executed to check deployment healthiness before going further into debugging.
+
+Check pods status:
+```bash
+kubectl get pods -n ggbridge -o wide
+```
+
+You should be looking for `Running` status, Ready column showing `1/1` (or `2/2`), and low restart count.
+
+Check pods details:
+```bash
+kubectl describe pod $pod_name -n ggbridge 
+```
+
+Have a look at the `Events` section for suspicious warnings or errors.
+
+
 ### Connectivity Tests
 
 #### 1. Client-Side Healthcheck
@@ -107,29 +126,93 @@ Expected output: List of Git branches and their commit hashes
 > [!TIP]
 > Please consider using the `CronJob` probes available [here](../tests/) if you want a permanent check.
 
-### Log Analysis
+#### 4. Reverse tunneling
 
-#### Client/Server Health Logs.
-Check nginx sidecar logs for connectivity issues:
+When reverse tunneling is enabled on client side, you can check if you are able to connect to `api.gitguardian.com`. Execute this command on the customer's cluster:
 
 ```bash
-# Check specific pod logs
-kubectl logs -l tenant=$uid,index=$index -c nginx -n ggbridge
+kubectl run debug -it --rm \
+                      --restart=Never \
+                      -n ggbridge \
+                      --image=nicolaka/netshoot \
+                      -- zsh -c "curl -IL --resolve api.gitguardian.com:443:$(kubectl get svc ggbridge-proxy-tls -n ggbridge -o jsonpath='{.spec.clusterIP}') https://api.gitguardian.com"
+```
+
+Check that DNS resolution on customer's environment properly resolve to the custom Kubernetes endpoint (implentation specific) instead of the public IP address of `hook.gitguardian.com`/`api.gitguardian.com`. Execute following commands from the customer's VCS server for example:
+
+```bash
+dig hook.gitguardian.com
+dig api.gitguardian.com
+```
 
-# Check all pods for a tenant
-kubectl logs -l tenant=$uid -c nginx -n ggbridge --tail=50
+```bash
+traceroute hook.gitguardian.com
+traceroute api.gitguardian.com
 ```
-Healthy connection log example:
+
+### Log Analysis
+
+> [!TIP]
+> To collect and package **client side** logs in a `.tgz` archive, you can use the [dedicated script](./client-log-fetcher.sh)
+
+#### 1. Client/Server Healthcheck Logs
+Check nginx sidecar logs for connectivity issues :
+
+Server side:
+```bash
+# Check ggbridge server nginx container logs for a specific tenant and index
+kubectl logs -l tenant=$uid,index=$index,app.kubernetes.io/component=server -c nginx -n ggbridge
+```
+Client side:
+```bash
+# Check ggbridge client nginx container logs for a specific index
+kubectl logs -l index=$index,app.kubernetes.io/instance=ggbridge -c nginx -n ggbridge
+```
+
+Healthy connection log example for the Healthcheck probe (nginx container for server/client pod):
 ```console
 health 127.0.0.1 [30/Sep/2025:12:04:38 +0000] 127.0.0.1 "GET /healthz HTTP/1.1" 200 3 "-" "Go-http-client/1.1"
 ```
 No logs = No connectivity from the other tunnel endpoint.
 
-#### Server-Side Proxy Logs
+#### 2. Client/Server tunnel Logs
+
+Server side:
+```bash
+# Check ggbridge server main container logs for a specific tenant and index
+kubectl logs -l tenant=$uid,index=$index,app.kubernetes.io/component=server -c ggbridge -n ggbridge
+```
+Client side:
+```bash
+# Check ggbridge client main container logs for a specific index
+kubectl logs -l index=$index,app.kubernetes.io/instance=ggbridge -c ggbridge -n ggbridge
+```
+
+You should see `INFO` logs mentionning opened/closed connections:
+```console
+2025-10-16T08:21:06.156024Z  INFO wstunnel::protocols::tls::server: Doing TLS handshake using SNI DnsName("jpynh30wscp60zs4lbdf4m4p8qe9idgu.ggbridge.gitguardian.com") with the server jpynh30wscp60zs4lbdf4m4p8qe9idgu.ggbridge.gitguardian.com:443
+2025-10-16T08:21:06.570872Z  INFO tunnel{id="0199ec1b-c14b-7f41-9492-e538c7a90f97" remote="127.0.0.1:8081"}: wstunnel::tunnel::transport::io: Closing local => remote tunnel
+2025-10-16T08:21:06.571213Z  INFO tunnel{id="0199ec1b-c14b-7f41-9492-e538c7a90f97" remote="127.0.0.1:8081"}: wstunnel::tunnel::transport::io: Closing local <= remote tunnel
+2025-10-16T08:21:08.489704Z  INFO tunnel{id="0199ec1b-af3c-70e3-8595-cd82aaf74cf4" remote="0.0.0.0:9081"}: wstunnel::tunnel::transport::io: Closing local => remote tunnel
+2025-10-16T08:21:08.738773Z  INFO wstunnel::protocols::tls::server: Doing TLS handshake using SNI DnsName("jpynh30wscp60zs4lbdf4m4p8qe9idgu.ggbridge.gitguardian.com") with the server jpynh30wscp60zs4lbdf4m4p8qe9idgu.ggbridge.gitguardian.com:443
+2025-10-16T08:21:10.693531Z  INFO tunnel{id="0199ec1b-b789-7362-b52a-5853e726c484" remote="0.0.0.0:9081"}: wstunnel::tunnel::transport::io: Closing local => remote tunnel
+2025-10-16T08:21:10.947501Z  INFO wstunnel::protocols::tls::server: Doing TLS handshake using SNI DnsName("jpynh30wscp60zs4lbdf4m4p8qe9idgu.ggbridge.gitguardian.com") with the server jpynh30wscp60zs4lbdf4m4p8qe9idgu.ggbridge.gitguardian.com:443
+```
+
+> [!NOTE]
+> Any log entries at `WARN` or `ERROR` level are worth highlighting if present.
+
+> [!NOTE]
+> You can also increase verbosity if needed, at `DEBUG` or `TRACE` level (default `INFO`):
+> ```yaml
+> logLevel: INFO # --> set de DEBUG or TRACE on server/client side values.yaml
+> ```
+
+#### 3. Server-Side Proxy Logs
 
 Monitor traffic through the SOCKS proxy:
 ```bash
-kubectl logs -l app.kubernetes.io/component=proxy,tenant=$uid -c nginx -n ggbridge --tail=100
+kubectl logs -l tenant=$uid,index=$index,app.kubernetes.io/component=proxy -n ggbridge
 ```
 
 Port meanings:
@@ -154,6 +237,9 @@ Log format explanation:
 | 10 | `"150"` | `"$upstream_bytes_received"` | Data received nginx ← backend | Bytes |
 | 11 | `"0.000"` | `"$upstream_connect_time"` | Connection time | Seconds |
 
+> [!TIP]
+> If `Session duration` reach 5sec for healtcheck (port 8081), it means time out occured 
+
 ## Client Monitoring/Alerting Guidelines
 ### Overview
 

examples/2-way-tunneling/README.md

@@ -2,12 +2,12 @@
 
 By default, the `ggbridge` client does not expose any **client → server** proxies that allow accessing remote resources through the established tunnel.
 
-However, `ggbridge` supports two types of client-to-server proxies:
+However, `ggbridge` supports client-to-server proxy with **TLS Routing**.
 
-- **TLS Routing**: Exposes a TLS port to forward all incoming TLS traffic through a TCP tunnel. This requires DNS redirection, e.g., redirecting `hook.gitguardian.com` requests to the ggbridge client.
-- **HTTPS Routing**: Exposes an HTTPS service and allows defining routing rules. For instance, you can expose a hostname like `hook.gitguardian.internal` and route traffic to `hook.gitguardian.com` through the ggbridge tunnel.
+**TLS Routing** exposes a TLS port to forward all incoming TLS traffic through a TCP tunnel. This requires **DNS redirection**, e.g., redirecting `hook.gitguardian.com` requests to the ggbridge client.
 
-> **Note:** On the server side, only requests to `hook.gitguardian.com` and `api.gitguardian.com` are allowed for client → server traffic.
+> [!CAUTION]  
+> On the server side, only requests to `hook.gitguardian.com` and `api.gitguardian.com` are allowed for client → server traffic.
 
 ---
 
@@ -24,9 +24,12 @@ client:
       enabled: true
 ```
 
+> [!NOTE]  
+> **TLS Routing** does not work natively with standard `Ingress` objects. Some Ingress controllers offer specific configurations (annotations, custom parameters, etc.) to enable TLS Routing with `Ingress`, but this depends entirely on your controller’s capabilities and is highly implementation-specific. Please refer to your Ingress controller’s documentation for this particular use case.
+
 The TLS port can be exposed using one of the following methods:
 
-1. LoadBalancer Service
+### 1. LoadBalancer Service
 
 Helm values file example 👉 [values-tls-service.yaml](./helm/values-tls-service.yaml)
 
@@ -38,124 +41,91 @@ proxy:
         type: LoadBalancer
         ports:
           tls:
-            # 443 is the default TLS port
             port: 443
 ```
+Ensure that your VCS (and any assets using the GitGuardian hook) resolve `hook.gitguardian.com` and `api.gitguardian.com` to the external IP address of the created LoadBalancer Service (default name `ggbridge-proxy-tls`).
 
-2. Ingress
+> [!NOTE]  
+> `LoadBalancer` Service exposes the Service externally using an external load balancer. Kubernetes does not directly offer a load balancing component; you must provide one, or you can integrate your Kubernetes cluster with a cloud provider. Refer to official [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer) for more information.
 
-Helm values file example 👉 [values-tls-ingress.yaml](./helm/values-tls-ingress.yaml)
+### 2. Custom Resource (CRD)
 
-```yaml
-proxy:
-  tunnels:
-    tls:
-      ingress:
-        enabled: true
-        className: ""
-```
+Some Ingress controllers provide Custom Resources that enable enhanced capabilities—such as TCP handling, authentication, and other advanced features. This is the case with Traefik, Istio, and other well-known Kubernetes networking solutions.
 
-3. Gateway API
+Currently we support Traefik [`IngressRouteTCP`](https://doc.traefik.io/traefik/reference/routing-configuration/kubernetes/crd/tcp/ingressroutetcp/) Custom Resource. Ensure that Traefik ingress controller is installed in your cluster first.
 
-Helm values file example 👉 [values-tls-gateway.yaml](./helm/values-tls-gateway.yaml)
+Helm values file example 👉 [values-tls-traefik.yaml](./helm/values-tls-traefik.yaml)
 
 ```yaml
 proxy:
   tunnels:
     tls:
-      gateway:
-        enabled: true
-        # This will create the gateway resource, you can disable it if you want to mange it on you own.
-        create: true
-        className: ""
-```
-
-4. OpenShift Route
-
-Helm values file example 👉 [values-tls-openshift-route.yaml](./helm/values-tls-openshift-route.yaml)
-
-```yaml
-proxy:
-  resolver: dns-default.openshift-dns.svc.cluster.local
-  tunnels:
-    tls:
-      openShiftRoute:
+      ingress:
         enabled: true
+        controller: "traefik"
 ```
 
-## HTTPS Routing
-
-![https-routing](../../docs/images/ggbridge-https-routing.drawio.png)
-
-To enable HTTPS Routing, update your Helm values:
-
-```yaml
-client:
-  tunnels:
-    web:
-      enabled: true
+Ensure that your VCS (and any assets using the GitGuardian hook) resolve `hook.gitguardian.com` and `api.gitguardian.com` to the external IP address of the Traefik LoadBalancer Service.
+```console
+$ kubectl get service -n traefik
+NAME             TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)                      AGE
+traefik          LoadBalancer   10.43.65.162   172.31.26.173   80:20572/TCP,443:27014/TCP   29h
 ```
 
-This service can be exposed via Ingress or Gateway:
+### 3. Gateway API
 
-1. Ingress
+> [!NOTE]  
+> [Gateway API](https://gateway-api.sigs.k8s.io/guides/#getting-started-with-gateway-api) must be installed in your cluster first.
 
-Helm values file example 👉 [values-https-ingress.yaml](./helm/values-https-ingress.yaml)
+Helm values file example 👉 [values-tls-gateway.yaml](./helm/values-tls-gateway.yaml)
 
 ```yaml
 proxy:
   tunnels:
-    web:
-      ingress:
+    tls:
+      gateway:
         enabled: true
-        # -- Set the ingress ClassName (leave empty to use default)
-        className: ""
-        listeners:
-          # This listener exposes an HTTPS service with the hostname
-          # `hook.private.com` and routes traffic to `hook.gitguardian.com`
-          - hostname: hook.private.com
-            backend: hook.gitguardian.com
-            tls:
-              # Certificate for hook.private.com
-              secretName: internal-crt
+        gateway:
+          # This will create the gateway resource, you can disable it if you want to manage it on your own.
+          create: true
+          # This will set the gatewayClass of the Gateway
+          className: "my-gatewayclass"
 ```
 
-2. Gateway API
-
-Helm values file example 👉 [values-https-gateway.yaml](./helm/values-https-gateway.yaml)
+This will create a [`Gateway`](https://gateway-api.sigs.k8s.io/concepts/api-overview/#gateway) and [`TLSRoute`](https://gateway-api.sigs.k8s.io/concepts/api-overview/#tlsroute) object. You need to deploy first a [`GatewayClass`](https://gateway-api.sigs.k8s.io/concepts/api-overview/#gatewayclass) in your cluster.
 
+If your teams already manage `GatewayClass` and `Gateway` resources, you can reference the `Gateway` in the `TLSRoute` with :
 ```yaml
 proxy:
   tunnels:
-    web:
+    tls:
       gateway:
         enabled: true
-        # -- Set the gateway ClassName (leave empty to use default)
-        className: ""
-        listeners:
-          - hostname: hook.private.com
-            backend: hook.gitguardian.com
-            tls:
-              # Certificate for hook.private.com
-              secretName: internal-crt
+        parentRefs:
+        - name: my-gateway
+          namespace: my-gateway-namespace
+        gateway:
+          create: false
 ```
 
-3. OpenShift Route
+Ensure that your VCS (and any assets using the GitGuardian hook) resolve `hook.gitguardian.com` and `api.gitguardian.com` to the IP address of the `Gateway` Custom Resource.
+```console
+$ kubectl get gateway
+NAME             CLASS             ADDRESS         PROGRAMMED    AGE
+my-gateway       my-gatewayclass   192.168.1.200   True          54h
+```
+
+### 4. OpenShift Route
 
-Helm values file example 👉 [values-https-openshift-route.yaml](./helm/values-https-openshift-route.yaml)
+Helm values file example 👉 [values-tls-openshift-route.yaml](./helm/values-tls-openshift-route.yaml)
 
 ```yaml
 proxy:
   resolver: dns-default.openshift-dns.svc.cluster.local
   tunnels:
-    web:
-      openShiftRoute::
+    tls:
+      openShiftRoute:
         enabled: true
-        listeners:
-          - hostname: hook-gitguardian.internal.com
-            backend: hook.gitguardian.com
-            tls:
-              termination: edge
 ```
 
-With these configurations, your ggbridge client can securely forward traffic through the tunnel from the client side to approved GitGuardian services.
+With these configurations, your ggbridge client can securely forward traffic through the tunnel from the client side to approved GitGuardian services.