diff --git a/docs.json b/docs.json
index b4a453d..5727d09 100644
--- a/docs.json
+++ b/docs.json
@@ -108,7 +108,13 @@
"manage/clients/credentials",
"manage/clients/fingerprinting",
"manage/clients/archiving-blocking",
- "manage/clients/firewalls"
+ "manage/clients/firewalls",
+ {
+ "group": "Kubernetes",
+ "pages": [
+ "manage/clients/kubernetes/deployment"
+ ]
+ }
]
},
"manage/domains",
diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx
index 47dbaca..120244b 100644
--- a/manage/clients/install-client.mdx
+++ b/manage/clients/install-client.mdx
@@ -251,6 +251,10 @@ services:
- `cap_add: - NET_ADMIN` is required to grant the container permission to manage network interfaces
- `devices: - /dev/net/tun:/dev/net/tun` is required to give the container access to the TUN device for creating WireGuard interfaces
+
+Deploying in Kubernetes? See [Kubernetes Deployment](/manage/clients/kubernetes/deployment) for a basic guide, including how to run the client as a sidecar container.
+
+
## Olm (Advanced)
diff --git a/manage/clients/kubernetes/deployment.mdx b/manage/clients/kubernetes/deployment.mdx
new file mode 100644
index 0000000..fcb598f
--- /dev/null
+++ b/manage/clients/kubernetes/deployment.mdx
@@ -0,0 +1,126 @@
+---
+title: "Deployment"
+description: "Basic guide for running a Pangolin client in Kubernetes as a sidecar."
+---
+
+This page covers a basic way to run a Pangolin client inside Kubernetes: as a sidecar container that gives a Pod access to your Pangolin resources over the tunnel.
+
+
+This is a minimal example, not a production chart. There is no official Helm chart for the client at this time — adapt the manifests below to your own deployment, Kustomize overlays, or GitOps workflow.
+
+
+## Why a sidecar
+
+Containers in the same Pod share a network namespace. Running Pangolin CLI (or Olm) as a sidecar container brings up the WireGuard tunnel inside that shared namespace, so every other container in the Pod can reach your Pangolin resources as if they were on the tunnel directly — no `hostNetwork` required.
+
+This is useful when a workload running in your cluster (a batch job, an internal service, a CI runner) needs to reach private resources behind Pangolin.
+
+## Prerequisites
+
+- A machine client created in Pangolin, with its `Client ID` and `Client Secret`. See [Install Clients](/manage/clients/install-client).
+- A Kubernetes cluster where you can grant the `NET_ADMIN` capability and access to `/dev/net/tun`.
+
+## Step 1: Create a Secret for client credentials
+
+```bash
+kubectl create secret generic pangolin-client \
+ --namespace default \
+ --from-literal=CLIENT_ID= \
+ --from-literal=CLIENT_SECRET=
+```
+
+
+Do not commit plaintext credentials to Git. For GitOps workflows, use an encrypted or external secret backend such as SOPS, Sealed Secrets, External Secrets Operator, Vault, or Infisical.
+
+
+## Step 2: Add the sidecar container
+
+Add a `pangolin-cli` container alongside your application container in the Pod spec. It needs the `NET_ADMIN` capability and access to the host's `/dev/net/tun` device to create the WireGuard interface.
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+ name: my-app
+ labels:
+ app: my-app
+spec:
+ containers:
+ - name: my-app
+ image: my-app-image:latest
+ # This container can reach Pangolin resources through
+ # the tunnel brought up by the pangolin-cli sidecar below.
+
+ - name: pangolin-cli
+ image: fosrl/pangolin-cli:latest
+ restartPolicy: Always
+ envFrom:
+ - secretRef:
+ name: pangolin-client
+ env:
+ - name: PANGOLIN_ENDPOINT
+ value: "https://pangolin.example.com"
+ securityContext:
+ capabilities:
+ add: ["NET_ADMIN"]
+ volumeMounts:
+ - name: tun
+ mountPath: /dev/net/tun
+
+ volumes:
+ - name: tun
+ hostPath:
+ path: /dev/net/tun
+```
+
+
+Setting `restartPolicy: Always` on the container makes it a [native sidecar](https://kubernetes.io/docs/concepts/workloads/pods/sidecar-containers/) on Kubernetes 1.29+. It starts before the main container and Kubernetes keeps it running for the life of the Pod. On older clusters, omit `restartPolicy` and the container runs as a regular container instead — the tunnel still comes up, but startup ordering isn't guaranteed.
+
+
+The `pangolin-cli` image runs `pangolin up --attach` by default, which launches the client as a machine client using the `CLIENT_ID`/`CLIENT_SECRET` from the Secret and keeps it in the foreground so the container stays alive. See [Install Clients](/manage/clients/install-client#pangolin-cli-linux-macos-windows) for the full list of environment variables and flags.
+
+## Step 3: Apply and verify
+
+```bash
+kubectl apply -f pod.yaml
+```
+
+Check that both containers are running:
+
+```bash
+kubectl get pod my-app
+```
+
+Check the tunnel came up in the sidecar's logs:
+
+```bash
+kubectl logs my-app -c pangolin-cli
+```
+
+In the Pangolin dashboard, verify the client shows as connected. Then, from inside the `my-app` container, confirm you can reach a private resource:
+
+```bash
+kubectl exec my-app -c my-app -- curl -s http://internal-resource.example
+```
+
+## Deployments and other workload types
+
+The same sidecar pattern applies to a `Deployment`, `StatefulSet`, `Job`, or `CronJob` — add the `pangolin-cli` container to `spec.template.spec.containers` (or `initContainers` with `restartPolicy: Always` for native sidecar behavior) the same way as shown above.
+
+
+Each Pod running the sidecar connects as the same machine client. If you scale a Deployment to multiple replicas, every replica's sidecar authenticates with the same `CLIENT_ID`/`CLIENT_SECRET` and appears as one client in Pangolin. If you need to distinguish traffic per replica, create a separate machine client and Secret for each one.
+
+
+## Next steps
+
+
+
+ Review Pangolin CLI and Olm installation options, including Docker.
+
+
+ Review client configuration options.
+
+
+ Manage machine client credentials.
+
+
diff --git a/manage/sites/install-site.mdx b/manage/sites/install-site.mdx
index 9246049..677b47e 100644
--- a/manage/sites/install-site.mdx
+++ b/manage/sites/install-site.mdx
@@ -4,6 +4,10 @@ description: "Install Newt as a binary or Docker container"
---
Newt can be installed as either a static binary executable or a Docker container. You must first create a site and copy the Newt config in Pangolin before running Newt.
+
+Deploying Newt in Kubernetes instead? See the dedicated [Kubernetes](/manage/sites/kubernetes/helm) docs — install guides for [Helm](/manage/sites/kubernetes/helm) and [Kustomize](/manage/sites/kubernetes/kustomize), a full [Configuration](/manage/sites/kubernetes/configuration) reference, and [Troubleshooting](/manage/sites/kubernetes/troubleshooting).
+
+
## Binary Installation
### Quick Install (Recommended)
@@ -216,6 +220,25 @@ docker compose up -d
## Platform-Specific Installation
+### Kubernetes
+
+Running Newt in a Kubernetes cluster is covered separately from the Docker instructions above, since it uses a dedicated Helm chart rather than a plain `docker run` or Compose file. See:
+
+
+
+ Quick-start guide for installing Newt with Helm.
+
+
+ Install Newt with rendered manifests and Kustomize overlays.
+
+
+ Full configuration reference for Helm and Kustomize workflows.
+
+
+ Debug Newt deployment and connection issues in Kubernetes.
+
+
+
### Unraid
Newt is available in the Unraid Community Applications store. Search for "Newt" and follow the installation prompts. Enter the ID, secret, and endpoint from Pangolin in the template fields.