Skip to content

Installation Guide

This guide covers installing, upgrading, and uninstalling Varnish Gateway. Helm is the recommended path; kubectl manifests are available as an alternative.

Prerequisites

  • Kubernetes 1.26+
  • kubectl configured to access your cluster
  • Helm 3.8+ (if using the Helm method)
  • Gateway API CRDs installed in your cluster:
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/standard-install.yaml

Helm

Install

Install the chart from the OCI registry:

helm install varnish-gateway oci://ghcr.io/varnish/charts/varnish-gateway \
  --namespace varnish-gateway-system \
  --create-namespace

This installs:

  • Varnish-specific CRDs: GatewayClassParameters, VarnishCacheInvalidation, and VarnishCachePolicy
  • The operator deployment and RBAC
  • A default GatewayClass named varnish

Install a specific version

helm install varnish-gateway oci://ghcr.io/varnish/charts/varnish-gateway \
  --version v0.19.2 \
  --namespace varnish-gateway-system \
  --create-namespace

Install with custom values

helm install varnish-gateway oci://ghcr.io/varnish/charts/varnish-gateway \
  --namespace varnish-gateway-system \
  --create-namespace \
  -f my-values.yaml

See the chart README for all configuration options.

Upgrade

Helm installs CRDs from a chart's crds/ directory on first install but does not touch them on upgrade or uninstall, this is a deliberate Helm design choice to avoid accidentally destroying data held in custom resources. If the Varnish-specific CRDs (GatewayClassParameters, VarnishCacheInvalidation, VarnishCachePolicy) have changed between your installed version and the target version, apply them manually before upgrading:

# Pull the chart to get the CRDs for the new version
helm pull oci://ghcr.io/varnish/charts/varnish-gateway --version vX.Y.Z --untar
kubectl apply -f varnish-gateway/crds/

If CRDs are unchanged between versions, this step is a no-op and can be skipped — applying them is always safe. Release notes call out CRD changes when they happen.

Then upgrade the release:

helm upgrade varnish-gateway oci://ghcr.io/varnish/charts/varnish-gateway \
  --version vX.Y.Z \
  --namespace varnish-gateway-system

This covers the Varnish-specific CRDs only. The Gateway API CRDs (Gateway, HTTPRoute, etc.) are upstream and upgraded separately — see the Gateway API release notes.

Uninstall

helm uninstall varnish-gateway --namespace varnish-gateway-system

Warning: deleting the CRDs also deletes all Gateway, HTTPRoute, and related resources in the cluster.

kubectl delete crd gatewayclassparameters.gateway.varnish-software.com \
                   varnishcacheinvalidations.gateway.varnish-software.com \
                   varnishcachepolicies.gateway.varnish-software.com

kubectl (Alternative)

Kubernetes manifests live in deploy/:

deploy/
├── 00-prereqs.yaml       # Namespace + GatewayClassParameters CRD
├── 01-operator.yaml      # ServiceAccount, ClusterRole, ClusterRoleBinding, Deployment
├── 02-chaperone-rbac.yaml # ClusterRole for chaperone to watch EndpointSlices
└── 03-gatewayclass.yaml  # GatewayClass "varnish"

Install

kubectl apply -f deploy/

This installs the same resources as the Helm chart, without templating.

Upgrade

Re-apply the manifests for the new version:

kubectl apply -f deploy/

Uninstall

kubectl delete -f deploy/

To also remove the Gateway API CRDs:

kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/standard-install.yaml

Verify Installation

Check the operator is running:

kubectl get pods -n varnish-gateway-system

You should see:

NAME                                        READY   STATUS    RESTARTS   AGE
varnish-gateway-operator-xxxxxxxxxx-xxxxx   1/1     Running   0          30s

Check the GatewayClass was created:

kubectl get gatewayclass

You should see:

NAME      CONTROLLER                      ACCEPTED   AGE
varnish   varnish-software.com/gateway    True       1m

Troubleshooting

View operator logs

kubectl logs -n varnish-gateway-system -l app.kubernetes.io/component=operator -f

GatewayClass not accepted

kubectl describe gatewayclass varnish

For Gateway- and HTTPRoute-level issues, see First Gateway → Troubleshooting and Operations → Troubleshooting.

Next Steps