pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-08-30 18:51:29 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add k8s docs to the site and client

Browse Source
This commit is contained in:
Owen
2026-08-25 17:11:35 -04:00
parent 8ee0505275
commit 9ea288bbec
4 changed files with 160 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs.json
View File

@@ -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",

4
manage/clients/install-client.mdx
View File

@@ -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
<Note>
Deploying in Kubernetes? See [Kubernetes Deployment](/manage/clients/kubernetes/deployment) for a basic guide, including how to run the client as a sidecar container.
</Note>
## Olm (Advanced)
<Accordion title="Olm CLI (advanced use only)">

126
manage/clients/kubernetes/deployment.mdx Normal file
View File

@@ -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.
<Note>
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.
</Note>
## 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=<client-id> \
--from-literal=CLIENT_SECRET=<client-secret>
```
<Warning>
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.
</Warning>
## 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
```
<Note>
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.
</Note>
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.
<Warning>
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.
</Warning>
## Next steps
<CardGroup cols={2}>
<Card title="Install Clients" href="/manage/clients/install-client" icon="download">
Review Pangolin CLI and Olm installation options, including Docker.
</Card>
<Card title="Configure Clients" href="/manage/clients/configure-client" icon="sliders">
Review client configuration options.
</Card>
<Card title="Credentials" href="/manage/clients/credentials" icon="key">
Manage machine client credentials.
</Card>
</CardGroup>

23
manage/sites/install-site.mdx
View File

@@ -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.
<Note>
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).
</Note>
## 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:
<CardGroup cols={2}>
<Card title="Helm" href="/manage/sites/kubernetes/helm" icon="box">
Quick-start guide for installing Newt with Helm.
</Card>
<Card title="Kustomize" href="/manage/sites/kubernetes/kustomize" icon="layer-group">
Install Newt with rendered manifests and Kustomize overlays.
</Card>
<Card title="Configuration" href="/manage/sites/kubernetes/configuration" icon="sliders">
Full configuration reference for Helm and Kustomize workflows.
</Card>
<Card title="Troubleshooting" href="/manage/sites/kubernetes/troubleshooting" icon="circle-question">
Debug Newt deployment and connection issues in Kubernetes.
</Card>
</CardGroup>
### 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.