From 36eae539de1b6b9fab0c3d8a77cc73a9c1541ad2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Djema=C3=AF?=
 <53857555+SamyDjemai@users.noreply.github.com>
Date: Thu, 4 Dec 2025 21:21:51 +0100
Subject: [PATCH] feat(kubernetes): add private cluster connection page

---
 .../how-to/connect-private-cluster.mdx        | 99 +++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 pages/kubernetes/how-to/connect-private-cluster.mdx

diff --git a/pages/kubernetes/how-to/connect-private-cluster.mdx b/pages/kubernetes/how-to/connect-private-cluster.mdx
new file mode 100644
index 0000000000..15862d9bcd
--- /dev/null
+++ b/pages/kubernetes/how-to/connect-private-cluster.mdx
@@ -0,0 +1,99 @@
+---
+title: How to connect to a fully isolated Kubernetes Kapsule cluster using Public Gateway
+description: Learn how to connect to a private Kubernetes cluster using kubectl and Public Gateway. Follow steps to connect securely to your cluster while ensuring its networking isolation.
+tags: connection cluster kubectl public-gateways
+dates:
+  validation: 2025-12-04
+  posted: 2025-12-04
+---
+import Requirements from '@macros/iam/requirements.mdx'
+
+
+When [creating your cluster](/kubernetes/how-to/create-cluster/), you can choose to connect it to a Private Network using [full isolation](/kubernetes/reference-content/secure-cluster-with-private-network/#what-is-the-difference-between-controlled-isolation-and-full-isolation). The control plane is created without a public IP, and a [Public Gateway](/public-gateways/how-to/configure-a-public-gateway/) is required to connect to it.
+
+You can connect to the control plane using your Public Gateway's [SSH bastion](/public-gateways/how-to/use-ssh-bastion/). This lets you manage your cluster using `kubectl` and other tools while ensuring that its control plane is not exposed to the Internet.
+
+<Requirements />
+
+- A [Scaleway account](https://console.scaleway.com) logged into the console.
+- [Owner status](https://console.scaleway.com) or [IAM permissions](/iam/concepts/#permission) to perform actions in the intended Organization.
+- Created a [Private Network](/vpc/how-to/create-private-network/) with an attached [Public Gateway](/public-gateways/how-to/create-a-public-gateway/) with [SSH bastion](/public-gateways/how-to/use-ssh-bastion/) enabled.
+- Created a [Kubernetes Kapsule cluster](/kubernetes/how-to/create-cluster/) attached to the aforementioned Private Network, and configured with [full isolation](/kubernetes/reference-content/secure-cluster-with-private-network/#what-is-the-difference-between-controlled-isolation-and-full-isolation).
+- [kubectl](https://kubernetes.io/docs/tasks/tools/) installed locally.
+- The [Scaleway CLI](/scaleway-cli/quickstart/) installed locally.
+- Downloaded [a `kubeconfig` file](https://www.scaleway.com/en/docs/kubernetes/how-to/connect-cluster-kubectl/) from the Scaleway console.
+
+## Opening a SSH tunnel to the Kubernetes Kapsule control plane
+
+To connect to the fully isolated Kubernetes Kapsule control plane, you can open a SSH tunnel using the Public Gateway's SSH bastion. This will port-forward the control plane to a local port, to which you can then connect.
+
+### Finding your cluster's URL
+
+In the Scaleway console, go to the [Kubernetes product section](https://console.scaleway.com/kubernetes), then click your cluster's name.
+
+Scroll down to the **Network** section, and click on the **URL** value. The URL is copied to your clipboard.
+
+### Opening the SSH tunnel
+
+Open a terminal on your computer, then run the following command:
+
+```bash
+ssh -fNL 6443:<CLUSTER_URL_WITHOUT_HTTPS> bastion@<PUBLIC_GATEWAY_PUBLIC_IP> -p <SSH_BASTION_PORT>
+```
+
+Make sure to replace the values with the appropriate values. `<CLUSTER_URL_WITHOUT_HTTPS>` should end in `:6443`, which is the control plane's port.
+
+Here is an example command:
+
+```bash
+ssh -fNL 6443:1379355f-f36a-4383-9791-b6c573dea811.api.k8s.fr-par.scw.cloud:6443 bastion@51.159.153.192 -p 61000
+```
+
+<Message type="note">
+
+The command contains several `ssh` flags:
+
+- `-f` runs the command in the background;
+- `-N` tells `ssh` not to run a remote command, which is the case here since we only want to port-forward;
+- `-L` sets up port-forwarding from a local port (here, port `6443`) and a given host and port on the remote side;
+- `-p` indicates the remote SSH port.
+
+</Message>
+
+A tunnel to the Kubernetes Kapsule control plane is opened: all local traffic to port `6443` will now be redirected to the control plane through the Public Gateway's SSH bastion.
+
+## Accessing the cluster
+
+### Editing the `/etc/hosts` file
+
+The downloaded `kubeconfig` file points to the control plane's URL, which is currently unreachable due to its lack of public IP. However, you can redirect traffic to your local port-forwarded port by editing your `/etc/hosts` file.
+
+Open the `/etc/hosts` file on your computer using a text editor, and add the following line:
+
+```
+127.0.0.1 <CLUSTER_URL_WITHOUT_HTTPS>
+```
+
+Using the same values as the previous example, the line would be:
+
+```
+127.0.0.1 1379355f-f36a-4383-9791-b6c573dea811.api.k8s.fr-par.scw.cloud
+```
+
+Processes on your computer now resolve your cluster's hostname to `127.0.0.1`, your `localhost` address.
+
+### Using `kubectl`
+
+You can now manage your cluster using `kubectl`. Run the following command:
+
+```bash
+kubectl get nodes
+```
+
+A list of nodes from your Kapsule cluster should appear.
+
+<Message type="note">
+
+You need to run the `ssh` command again every time your computer reboots. This can be automated using various tools such as shell scripts.
+
+</Message>