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.
Helm is the recommended method for standard Kubernetes installations of Pangolin and Newt. Use Helm when you want a chart-based workflow for installing, upgrading, rolling back, and removing releases from your cluster.

​
Helm repository setup

Add the Fossorial Helm chart repository: 
helm repo add fossorial https://charts.fossorial.io
helm repo update fossorial
Search for available charts: 
helm search repo fossorial
The classic Helm repository flow is the default path for most installations: 
helm install my-newt fossorial/newt
helm install my-pangolin fossorial/pangolin

​
Installation overview

A typical Helm installation flow looks like this:
1

Create namespace and labels

Create the namespace manually and apply required labels or annotations.
2

Prepare values files

Create a values.yaml file for each release (values-pangolin.yaml, values-newt.yaml).
3

Install with Helm

Install with helm upgrade --install to support first install and future updates with the same command.
4

Verify release and resources

Confirm Helm release status and Kubernetes resources after deployment.
It is recommended to create the namespace explicitly before installation. This allows you to apply Pod Security Admission labels, policy labels, annotations, or other cluster-specific metadata before the chart creates workloads.
For detailed installation steps, see:

​
Install command patterns

helm upgrade --install pangolin fossorial/pangolin \
  --namespace pangolin \
  --values values-pangolin.yaml

helm upgrade --install newt fossorial/newt \
  --namespace pangolin \
  --values values-newt.yaml

​
Namespace preparation

Create the namespace before installing the chart: 
kubectl create namespace pangolin
If your cluster uses Pod Security Admission or namespace-based policies, apply the required labels before installation. Example: 
kubectl label namespace pangolin \
  pod-security.kubernetes.io/enforce=baseline \
  pod-security.kubernetes.io/audit=restricted \
  pod-security.kubernetes.io/warn=restricted
Pangolin deployments that include Gerbil require permissions that are not compatible with a restricted namespace profile, because Gerbil manages WireGuard and requires capabilities such as NET_ADMIN.
For more details, see Prerequisites.

​
Install with a values file

Both charts use values files for configuration. Pangolin example: 
helm upgrade --install pangolin fossorial/pangolin \
  --namespace pangolin \
  --values values-pangolin.yaml
Newt example: 
helm upgrade --install newt fossorial/newt \
  --namespace pangolin \
  --values values-newt.yaml
Using helm upgrade --install keeps the command usable for both the first installation and later configuration changes.
Do not use --create-namespace if you need custom namespace labels or annotations. Create the namespace first and then run Helm against that namespace.

​
Values and configuration

Keep reusable configuration in a values file: 
helm upgrade --install pangolin fossorial/pangolin \
  --namespace pangolin \
  --values values-pangolin.yaml
Use --set only for small tests or temporary overrides: 
helm upgrade --install pangolin fossorial/pangolin \
  --namespace pangolin \
  --set example.key=value
Common value sources:
  • values-pangolin.yaml for Pangolin.
  • values-newt.yaml for Newt.
  • Kubernetes Secrets for credentials.
  • Existing cluster resources such as TLS secrets, StorageClasses, or ingress controllers.
Full configuration options are documented here:

​
Artifact Hub and chart discovery

The Fossorial charts can be installed from the Fossorial Helm repository: 
helm repo add fossorial https://charts.fossorial.io
helm repo update fossorial
helm search repo fossorial
Artifact Hub can also be used to discover published chart metadata, available versions, install commands, and repository information.
Always verify the chart name, chart version, and repository URL before copying install commands into production.

​
OCI-based charts

OCI is not a separate installation method. It only changes where Helm pulls the chart from. For Pangolin and Newt, OCI chart publishing is available in GHCR:
  • Newt: oci://ghcr.io/fosrl/helm-charts/newt
  • Pangolin: oci://ghcr.io/fosrl/helm-charts/pangolin
You still use Helm in the same way: choose a chart, select a version, provide values, and install the release.

​
Pull OCI charts

Newt example: 
helm pull oci://ghcr.io/fosrl/helm-charts/newt \
  --version 1.4.0
Pangolin example: 
helm pull oci://ghcr.io/fosrl/helm-charts/pangolin \
  --version 0.1.0-alpha.0

​
Install from OCI

Newt example: 
helm upgrade --install newt oci://ghcr.io/fosrl/helm-charts/newt \
  --version 1.4.0 \
  --namespace pangolin \
  --values values-newt.yaml
Pangolin example: 
helm upgrade --install pangolin oci://ghcr.io/fosrl/helm-charts/pangolin \
  --version 0.1.0-alpha.0 \
  --namespace pangolin \
  --values values-pangolin.yaml
Use the classic Helm repository when you want the normal helm repo add and helm search repo workflow. Use OCI when you want to pull charts directly from GHCR or when your deployment tooling expects OCI chart references.

​
Upgrade and maintenance

​
Update the classic Helm repository

helm repo update fossorial
This step is only needed when using the classic Helm repository. OCI installs pull the chart by OCI reference and version.

​
Upgrade Pangolin

Classic Helm repository: 
helm upgrade pangolin fossorial/pangolin \
  --namespace pangolin \
  --values values-pangolin.yaml
OCI: 
helm upgrade pangolin oci://ghcr.io/fosrl/helm-charts/pangolin \
  --version 0.1.0-alpha.0 \
  --namespace pangolin \
  --values values-pangolin.yaml

​
Upgrade Newt

Classic Helm repository: 
helm upgrade newt fossorial/newt \
  --namespace pangolin \
  --values values-newt.yaml
OCI: 
helm upgrade newt oci://ghcr.io/fosrl/helm-charts/newt \
  --version 1.4.0 \
  --namespace pangolin \
  --values values-newt.yaml

​
Check release status

helm status pangolin --namespace pangolin
helm history pangolin --namespace pangolin

helm status newt --namespace pangolin
helm history newt --namespace pangolin

​
View rendered manifests

helm get manifest pangolin --namespace pangolin

helm get manifest newt --namespace pangolin

​
View applied values

helm get values pangolin --namespace pangolin

helm get values newt --namespace pangolin

​
Roll back a release

helm rollback pangolin <revision> --namespace pangolin

helm rollback newt <revision> --namespace pangolin

​
Uninstall a release

helm uninstall pangolin --namespace pangolin

helm uninstall newt --namespace pangolin
Uninstalling a Helm release does not always remove persistent volumes, externally managed secrets, DNS records, certificates, or cloud load balancers. Review the namespace and related cluster resources before deleting data.

​
Troubleshooting

For component-specific troubleshooting, see: Useful Helm commands: 
helm list --all-namespaces
helm status <release-name> --namespace <namespace>
helm history <release-name> --namespace <namespace>
helm get values <release-name> --namespace <namespace>
helm get manifest <release-name> --namespace <namespace>
Useful Kubernetes commands: 
kubectl get pods -n pangolin
kubectl get events -n pangolin --sort-by=.lastTimestamp
kubectl describe pod <pod-name> -n pangolin
kubectl logs <pod-name> -n pangolin

​
Next steps

Pangolin Helm Install

Install Pangolin with the Helm chart.

Site (Newt) Helm Install

Install Site (Newt) with the Helm chart.

Pangolin Configuration

Configure Pangolin chart values for your cluster.

Newt Configuration

Configure Newt chart values and credentials.

Argo CD

Deploy the charts with Argo CD.

Flux

Deploy the charts with Flux.