Helm
Kubernetes installation using Helm charts for Pangolin and Newt.
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 fossorialSearch for available charts:
helm search repo fossorialThe classic Helm repository flow is the default path for most installations:
helm install my-newt fossorial/newt
helm install my-pangolin fossorial/pangolinInstallation 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
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.yamlNamespace preparation
Create the namespace before installing the chart:
kubectl create namespace pangolinIf 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=restrictedPangolin 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.yamlNewt example:
helm upgrade --install newt fossorial/newt \
--namespace pangolin \
--values values-newt.yamlUsing 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.yamlUse --set only for small tests or temporary overrides:
helm upgrade --install pangolin fossorial/pangolin \
--namespace pangolin \
--set example.key=valueCommon value sources:
values-pangolin.yamlfor Pangolin.values-newt.yamlfor 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 fossorialArtifact 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.0Pangolin example:
helm pull oci://ghcr.io/fosrl/helm-charts/pangolin \
--version 0.1.0-alpha.0Install from OCI
Newt example:
helm upgrade --install newt oci://ghcr.io/fosrl/helm-charts/newt \
--version 1.4.0 \
--namespace pangolin \
--values values-newt.yamlPangolin example:
helm upgrade --install pangolin oci://ghcr.io/fosrl/helm-charts/pangolin \
--version 0.1.0-alpha.0 \
--namespace pangolin \
--values values-pangolin.yamlUse 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 fossorialThis 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.yamlOCI:
helm upgrade pangolin oci://ghcr.io/fosrl/helm-charts/pangolin \
--version 0.1.0-alpha.0 \
--namespace pangolin \
--values values-pangolin.yamlUpgrade Newt
Classic Helm repository:
helm upgrade newt fossorial/newt \
--namespace pangolin \
--values values-newt.yamlOCI:
helm upgrade newt oci://ghcr.io/fosrl/helm-charts/newt \
--version 1.4.0 \
--namespace pangolin \
--values values-newt.yamlCheck release status
helm status pangolin --namespace pangolin
helm history pangolin --namespace pangolinhelm status newt --namespace pangolin
helm history newt --namespace pangolinView rendered manifests
helm get manifest pangolin --namespace pangolinhelm get manifest newt --namespace pangolinView applied values
helm get values pangolin --namespace pangolinhelm get values newt --namespace pangolinRoll back a release
helm rollback pangolin <revision> --namespace pangolinhelm rollback newt <revision> --namespace pangolinUninstall a release
helm uninstall pangolin --namespace pangolinhelm uninstall newt --namespace pangolinUninstalling 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
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