Kubernetes Deployment

Install the versioned gateway with the repository’s Helm charts, including working probes, secrets, and CP/DP configuration.

Choose the Chart

Deployment	Repository chart / contract
File, database, control plane, data plane	`charts/ferrum-gateway`
Mesh, injector, node agent	`charts/ferrum-mesh`
Migrate	Explicit CLI invocation or external Kubernetes Job

The core CP distributes database configuration. Kubernetes Gateway API and Istio CRD watches belong to the mesh chart, which provides their RBAC. See the deployment guide.

1. Pin the Chart and Image

bash

git clone --branch v0.9.10 --depth 1 https://github.com/ferrum-edge/ferrum-edge.git
cd ferrum-edge
kubectl create namespace ferrum

These commands use the chart from the release tag and override its image tag with the published v0.9.10 image. Docker Hub supports public pulls. If GHCR refuses an anonymous pull, authenticate or use Docker Hub.

2. File Mode Quick Start

bash

helm upgrade --install ferrum ./charts/ferrum-gateway -n ferrum \
  -f charts/ferrum-gateway/examples/file-values.yaml \
  --set image.repository=ferrumedge/ferrum-edge \
  --set image.tag=v0.9.10

kubectl -n ferrum rollout status deployment/ferrum-ferrum-gateway
kubectl -n ferrum port-forward service/ferrum-ferrum-gateway 8000:8000
# In another terminal:
curl -i http://localhost:8000/httpbin/get

The example creates two replicas and an inline config. Replace its HTTPBin route with your backend. File mode needs no database; its Admin API is read-only.

3. Database Mode

Use an existing PostgreSQL service. Set FERRUM_DB_URL to its connection URL before creating the Secret.

bash

export FERRUM_ADMIN_JWT_SECRET=$(openssl rand -hex 32)
kubectl -n ferrum create secret generic ferrum-gateway-db \
  --from-literal=url="${FERRUM_DB_URL:?Set your PostgreSQL connection URL}"
kubectl -n ferrum create secret generic ferrum-gateway-credentials \
  --from-literal=admin-jwt-secret="$FERRUM_ADMIN_JWT_SECRET"
helm upgrade --install ferrum-db ./charts/ferrum-gateway -n ferrum \
  -f charts/ferrum-gateway/examples/database-values.yaml \
  --set image.repository=ferrumedge/ferrum-edge \
  --set image.tag=v0.9.10

For an existing deployment, follow the release-tagged database upgrade procedure first.

4. Control Plane / Data Plane

This development pair uses the repository’s explicit plaintext gRPC opt-in inside the cluster. For production, disable grpc.allowPlaintext, configure tls.cpGrpc and tls.dpGrpc, and use HTTPS CP URLs.

bash

kubectl -n ferrum create secret generic ferrum-cp-db \
  --from-literal=url="${FERRUM_DB_URL:?Set your PostgreSQL connection URL}"
kubectl -n ferrum create secret generic ferrum-grpc-credentials \
  --from-literal=admin-jwt-secret="$(openssl rand -hex 32)" \
  --from-literal=cp-dp-grpc-jwt-secret="$(openssl rand -hex 32)"
helm upgrade --install ferrum-cp ./charts/ferrum-gateway -n ferrum \
  -f charts/ferrum-gateway/examples/cp-values.yaml \
  --set image.repository=ferrumedge/ferrum-edge \
  --set image.tag=v0.9.10
helm upgrade --install ferrum-dp ./charts/ferrum-gateway -n ferrum \
  -f charts/ferrum-gateway/examples/dp-values.yaml \
  --set image.repository=ferrumedge/ferrum-edge \
  --set image.tag=v0.9.10

Health Probes and Admin Access

yaml

startupProbe:
  exec:
    command: ["/app/ferrum-edge", "health", "--live"]
  periodSeconds: 5
  failureThreshold: 12
livenessProbe:
  exec:
    command: ["/app/ferrum-edge", "health", "--live"]
  periodSeconds: 10
readinessProbe:
  exec:
    command: ["/app/ferrum-edge", "health"]
  periodSeconds: 5

The charts render binary exec probes because admin binds to loopback and the standard distroless image has no shell, curl, or sleep. A kubelet HTTP probe targets the pod IP and cannot reach that default listener.

To expose admin through a Service, configure a non-loopback bind, admin TLS or a restricted CIDR allowlist, and a NetworkPolicy. Include 127.0.0.1/32 in an allowlist so local probes work. Do not expose a Service or Ingress against a loopback-only listener.

Mesh and Optional Features

The mesh chart manages sidecar injection and node-agent capture. The injector requires Kubernetes 1.29+, or 1.28 with the SidecarContainers feature gate. Real ambient capture requires Linux kernel 5.7+, cgroup v2, bpffs, and the v0.9.10-ebpf image. The -ebpf-tools variant includes the shell and network tools required by iptables fallback and the Ambient UDP lifecycle. Node waypoint remains experimental.

Mesh chart guide · Node-agent privileges · Gateway chart values, HPA, metrics, TLS, and shutdown