This repository hosts Helm charts for deploying the Blockcast CDN Gateway on Kubernetes.
There are two release tracks:
| Track | Purpose | Helm repo URL |
|---|---|---|
| stable | Production | https://blockcast.github.io/helm-charts/stable |
| beta | Staging / early access | https://blockcast.github.io/helm-charts/beta |
Note: All chart versions use pre-release SemVer suffixes (e.g.,
1.8.8-15529.de614275). You must pass--develto Helm commands so that Helm includes these versions — without it Helm will find no installable chart.
-
Kubernetes 1.25+
-
Helm 3.12+
-
Cluster admin credentials for the initial setup step
-
Gateway API CRDs — the experimental channel is required because the relay uses
TCPRouteandUDPRoute, which are not in the standard channel:kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/experimental-install.yaml
-
Cilium (optional) — the chart includes an egress
CiliumNetworkPolicy(cilium.io/v2) for the device-export collector. From chart1.8.186-17424.3dc9fcda(beta channel; the stable channel picks it up at its next release cut) it is installed only when the cluster servesciliumnetworkpolicies.cilium.io. On any other cluster (kind, k3s, k3d, microk8s, minikube's default CNI, most managed clusters' default networking) it is skipped, the install succeeds, and Helm prints:WARNING: device-export egress policy NOT installed. deviceExport.egressPolicy.enabled is true, but this cluster does not serve the cilium.io/v2/CiliumNetworkPolicy API (Cilium is not installed), so the CiliumNetworkPolicy blockcastd-device-export-egress was skipped. The gateway runs normally without it. To silence this warning on a cluster without Cilium, set deviceExport.egressPolicy.enabled=false.Chart versions from
1.8.109up to (not including)1.8.186-17424.3dc9fcdado not check for Cilium: on a cluster without it the install fails withno matches for kind "CiliumNetworkPolicy"(see Troubleshooting). On those versions, or to silence the warning, turn the policy off in your values file:deviceExport: egressPolicy: enabled: false
The gateway runs normally without this policy. The other Cilium resources in the chart (
cast.tailscale.enabled,multicast.egressBgpAnchor.enabled,relay.egress.enabled) are off by default, and enabling them also requires Cilium. -
Release name alignment — the prereqs chart's
ClusterRoleBindingsubjects must match the gateway release'sServiceAccount. The prereqsreleaseNamevalue must match the gateway release name used in Step 2. The defaultblockcastdworks as long as you don't override the gateway release name.
Stable (production):
helm repo add blockcast https://blockcast.github.io/helm-charts/stable
helm repo updateBeta (staging):
helm repo add blockcast-beta https://blockcast.github.io/helm-charts/beta
helm repo updateThe gateway is split into two charts. The prereqs chart must be installed first by a cluster admin. The gateway chart is what runs on the node and self-updates.
This installs the ClusterRole, ClusterRoleBinding, and GatewayClass that the gateway needs. Requires cluster-admin credentials.
Stable:
helm upgrade --install blockcastd-prereqs blockcast/cdn-gateway-orc8r-prereqs \
-n <your-namespace> \
--create-namespace \
--develBeta:
helm upgrade --install blockcastd-prereqs blockcast-beta/cdn-gateway-orc8r-prereqs \
-n <your-namespace> \
--create-namespace \
--develIf your gateway release name is not
blockcastd, pass--set releaseName=<your-release-name>.
The cluster-scoped resources are installed independently of the gateway release. The most common cause of a broken install is silently skipping this step. Confirm before continuing:
helm list -n <your-namespace> | grep blockcastd-prereqs
kubectl get gatewayclass ats-<your-namespace>Both should return non-empty results. If the GatewayClass is NotFound or the gateway is later stuck on PROGRAMMED=Unknown ("Waiting for controller"), Step 1 was skipped or used the wrong namespace — re-run it.
Stable:
helm upgrade --install blockcastd blockcast/cdn-gateway \
-n <your-namespace> \
--devel \
-f my-values.yamlBeta:
helm upgrade --install blockcastd blockcast-beta/cdn-gateway \
-n <your-namespace> \
--devel \
-f my-values.yamlSee helm show values blockcast/cdn-gateway for all available configuration options.
Once the pods are running, get the registration URL:
kubectl exec -n <your-namespace> deploy/blockcastd-blockcastd -- blockcastd -sCopy the printed URL and register the gateway in the Blockcast portal. Until registered, blockcastd will not receive a configuration and no dynamic services will start.
After registering, blockcastd will connect to the controller and pull its configuration. Check the logs to confirm:
kubectl logs -n <your-namespace> deploy/blockcastd-blockcastd -fLook for the configuration received and dynamic services starting up (e.g. beacond).
The gateway upgrades itself automatically once running. To manually upgrade the Helm release:
helm repo update
helm upgrade blockcastd blockcast/cdn-gateway -n <your-namespace> --devel -f my-values.yamlUse blockcast-beta/cdn-gateway instead if you are on the beta track.
The prereqs chart rarely changes. Re-run Step 1 only if instructed in the release notes.
kubectl get gateway -n <your-namespace>
# NAME CLASS ADDRESS PROGRAMMED AGE
# blockcastd-relay ats-<namespace> Unknown 5dAlmost always means the prereqs chart was skipped for this namespace. Check:
helm list -n <your-namespace> | grep blockcastd-prereqs
kubectl get gatewayclass ats-<your-namespace>If either is empty, re-run Step 1. The relay controller will pick up the new GatewayClass on its next reconcile, or you can force it with:
kubectl rollout restart deployment/blockcastd-relay -n <your-namespace>Error: unable to build kubernetes objects from release manifest: resource mapping not found for name: "blockcastd-device-export-egress" namespace: "" from "": no matches for kind "CiliumNetworkPolicy" in version "cilium.io/v2"
ensure CRDs are installed first
The cluster does not run Cilium, and the chart (versions 1.8.109 up to (not including) 1.8.186-17424.3dc9fcda) renders the device-export egress policy by default without checking for Cilium. Nothing was installed. Either install a chart that skips the policy on clusters without Cilium (beta 1.8.186-17424.3dc9fcda or later; stable from its next release cut), or turn the policy off:
helm upgrade blockcastd blockcast/cdn-gateway -n <your-namespace> --devel \
--reset-then-reuse-values --set deviceExport.egressPolicy.enabled=false--reset-then-reuse-values needs Helm 3.14+. Do not use --reuse-values here: it applies the old chart's defaults to the new chart. For a first install, use helm upgrade --install with your usual -f values file plus --set deviceExport.egressPolicy.enabled=false.
Pre-release chart versions require --devel:
helm search repo blockcast/cdn-gateway --develhelm uninstall blockcastd -n <your-namespace>
helm uninstall blockcastd-prereqs -n <your-namespace>PVCs (blockcastd-certs and the snowflake PVC) are retained by default due to the resource policy annotation. Delete them manually if needed — otherwise reinstalling in the same namespace will reuse the existing certificate and snowflake state.