Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt

Use this file to discover all available pages before exploring further.

Try free on Pangolin Cloud

Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
Before installing Pangolin or Sites (Newt) on Kubernetes, check that your cluster, tools, networking, and storage setup match the deployment path you want to use.

​
Kubernetes cluster

Use a Kubernetes version that satisfies the Helm chart kubeVersion requirement and is supported by your Kubernetes provider or distribution. Check your cluster version: 
kubectl version
See the Version Matrix for the supported Kubernetes versions of the Pangolin and Newt Helm charts.

​
Controller access and RBAC

Controller mode is the default and recommended Kubernetes deployment mode for Pangolin. When controller mode is enabled, the Pangolin Kube Controller runs with its own ServiceAccount and needs permission to watch and manage the Kubernetes and Traefik resources it reconciles. The chart creates the required RBAC resources for you, unless RBAC creation is disabled. By default, the controller is scoped to the namespace of a single Pangolin deployment. It can also be configured for a broader scope when one controller should reconcile resources for multiple Pangolin deployments. Depending on the configured controller scope, the controller needs namespace-scoped or cluster-scoped access to the resources it reconciles:
API groupResourcesVerbs
""eventscreate, patch, update
""services, endpointsget, list, watch, create, update, patch, delete
discovery.k8s.ioendpointslicesget, list, watch, create, update, patch, delete
traefik.ioingressroutes, ingressroutetcps, ingressrouteudps, middlewares, middlewaretcps, traefikservices, serverstransports, serverstransporttcps, tlsoptions, tlsstoresget, list, watch, create, update, patch, delete
If leader election is enabled, the controller also needs access to:
API groupResourcesVerbs
coordination.k8s.ioleasesget, list, watch, create, update, patch
The controller also needs cluster-wide read access to Kubernetes discovery resources:
API groupResourcesVerbs
networking.k8s.ioingressclassesget, list, watch
apiextensions.k8s.iocustomresourcedefinitionsget, list, watch
For namespace-scoped deployments, the chart creates namespaced RBAC for the controller namespace and, if configured, the target namespace. For broader controller scopes, the chart creates the required cluster-scoped RBAC.

​
Database and storage

Pangolin requires a database backend. The Helm chart supports multiple database modes, including CloudNativePG, external PostgreSQL, embedded PostgreSQL, and SQLite. For persistent database-backed deployments, make sure your cluster has a usable StorageClass or configure the StorageClass explicitly in your chart values. Check available StorageClasses: 
kubectl get storageclasses
For long-running/production deployments, prefer PostgreSQL-based modes such as CloudNativePG or external PostgreSQL.
SQLite can be useful for simple or test deployments, but PostgreSQL-based modes are the better fit for long-running/production Kubernetes deployments.

​
Site connector storage

A Site (Newt) deployment does not require persistent storage by default. Use writable configuration persistence only if your deployment needs runtime configuration to survive pod replacement, upgrades, node drains, or rescheduling. For simple deployments, no PVC is required.

​
Networking

​
Ingress and routing

Pangolin needs an external entrypoint for the dashboard, API, and site traffic. Depending on your chart values, this can use:
  • controller mode with a Traefik ingress controller
  • standalone mode with chart-managed Traefik components
  • an existing ingress or load balancer setup
If you use controller mode with Traefik CRDs, verify that the required Traefik API resources are available: 
kubectl api-resources --api-group=traefik.io
You can also check existing ingress resources: 
kubectl get ingress -A

​
DNS

Configure DNS records for the domains used by Pangolin before exposing it publicly. At minimum, the Pangolin dashboard domain should resolve to the ingress controller, load balancer, or public endpoint used by your deployment. Example: 
nslookup pangolin.example.com
For tunneled site deployments, also verify the DNS name used by the site connector endpoint.

​
TLS

Use HTTPS for the Pangolin dashboard and API. Common TLS options include:
  • Traefik ACME / Let’s Encrypt
  • cert-manager
  • a pre-created Kubernetes TLS Secret
  • TLS termination at an external load balancer or ingress controller
Use the TLS method that matches your ingress and cluster setup. If you use cert-manager, verify that the certificate CRDs are available: 
kubectl get crd certificates.cert-manager.io

​
Namespace and security

Choose the namespace where Pangolin and related components should run. Example: 
kubectl create namespace pangolin
When using Helm, you can also let Helm create the namespace: 
helm upgrade --install pangolin fossorial/pangolin \
  --namespace pangolin \
  --create-namespace
If your cluster enforces Pod Security Admission, make sure the namespace labels match the selected deployment mode. Deployments that include tunnel components may require permissions that are not compatible with a fully restricted namespace profile.

​
NetworkPolicy

The Pangolin and Newt charts can manage NetworkPolicies for the required application traffic. If you enable chart-managed NetworkPolicies, review the generated policies before adding custom deny rules. If you replace them with your own policies, allow the required traffic between the components you deploy, such as Pangolin, Traefik, Gerbil, the database, DNS, and Site connectors.

​
Resource planning

Pangolin and Site (Newt) Kubernetes deployments include predefined resource profiles for the supported deployment methods. These profiles set CPU and memory requests and limits for the components used by the selected deployment mode. The available profiles are:
ProfileIntended use
SmallSmall deployments, or clusters with very limited available resources.
StandardDefault profile for most normal deployments.
LargeLarger environments with more Sites, more users, higher traffic, or stricter availability expectations.
The selected profile applies to the workloads that are part of your deployment, for example:
ComponentResource considerations
PangolinMain application workload. Size according to dashboard/API usage, users, and traffic.
Pangolin Kube ControllerRequired in controller mode. Size according to the number of reconciled Kubernetes and Traefik resources.
TraefikSize according to ingress and proxy traffic.
GerbilRequired when the tunnel stack is enabled. Size according to tunnel traffic and number of connected Sites.
PostgreSQL / CloudNativePGSize according to database mode, stored state, and expected write/read activity.
Site connectors (Newt)Each Site connector adds its own resource usage. Size according to the traffic handled by that Site.
The Standard profile is intended to be enough for most standard deployments. Use Small for very limited lab or test environments, and Large for higher traffic, more Sites, more users, or larger production environments.
After installation, monitor CPU and memory usage and adjust the selected profile or individual resource overrides if needed.
Avoid setting CPU limits on latency-sensitive Pangolin components unless your cluster policy requires them or you intentionally want to cap CPU usage.CPU limits can cause throttling when a workload temporarily needs more CPU, even if spare CPU capacity is available on the node. This can negatively affect ingress, tunnel, proxy, database, and controller workloads.For most deployments, use CPU requests to reserve baseline capacity and memory limits to protect the node from excessive memory usage.

​
Next steps

Choose an Installation Path

Pick the Kubernetes workflow that matches how you deploy applications.

Helm Quick-Start

Install Pangolin or Sites (Newt) with Helm.

Kustomize Quick-Start

Use Kustomize overlays and patches.

Argo CD Guide

Deploy Pangolin or Sites (Newt) with Argo CD.

Flux Guide

Deploy Pangolin or Sites (Newt) with Flux.

Pangolin Helm

Start with the Pangolin Helm installation guide.