Helm

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:

Create namespace and labels

Create the namespace manually and apply required labels or annotations.

Prepare values files

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

Install with Helm

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

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:

Pangolin Helm Quick-Start — Install Pangolin
Site (Newt) Helm Quick-Start — Install Site (Newt)

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

helm upgrade --install pangolin oci://ghcr.io/fosrl/helm-charts/pangolin \
  --version 0.1.0-alpha.0 \
  --namespace pangolin \
  --values values-pangolin.yaml

helm upgrade --install newt oci://ghcr.io/fosrl/helm-charts/newt \
  --version 1.4.0 \
  --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.

About

Manage Pangolin

Self-host Pangolin

Development

Helm repository setup

Installation overview

Install command patterns

Namespace preparation

Install with a values file

Values and configuration

Artifact Hub and chart discovery

OCI-based charts

Pull OCI charts

Install from OCI

Upgrade and maintenance

Update the classic Helm repository

Upgrade Pangolin

Upgrade Newt

Check release status

View rendered manifests

View applied values

Roll back a release

Uninstall a release

Troubleshooting

Next steps

Pangolin Helm Install

Site (Newt) Helm Install

Pangolin Configuration

Newt Configuration

Argo CD

Flux

​Helm repository setup

​Installation overview

​Install command patterns

​Namespace preparation

​Install with a values file

​Values and configuration

​Artifact Hub and chart discovery

​OCI-based charts

​Pull OCI charts

​Install from OCI

​Upgrade and maintenance

​Update the classic Helm repository

​Upgrade Pangolin

​Upgrade Newt

​Check release status

​View rendered manifests

​View applied values

​Roll back a release

​Uninstall a release

​Troubleshooting

​Next steps

Pangolin Helm Install

Site (Newt) Helm Install

Pangolin Configuration

Newt Configuration

Argo CD

Flux

Helm repository setup

Installation overview

Install command patterns

Namespace preparation

Install with a values file

Values and configuration

Artifact Hub and chart discovery

OCI-based charts

Pull OCI charts

Install from OCI

Upgrade and maintenance

Update the classic Helm repository

Upgrade Pangolin

Upgrade Newt

Check release status

View rendered manifests

View applied values

Roll back a release

Uninstall a release

Troubleshooting

Next steps