Deploy the rule server on Kubernetes

Build the image, load the rules into a ConfigMap, create the token Secret, apply the manifests, verify, publish new rules and rotate the token.

deploy/kubernetes runs the rule server as three replicas spread across zones, with zero-downtime rolling updates, probes, a non-root read-only container, autoscaling from 3 to 20 replicas and a disruption budget that keeps at least 2.

Not yet applied to a cluster

The manifests and the Dockerfile are written to the Kubernetes and Docker documentation, but were not run against a cluster when the repository was put together. CI builds the image and smoke-tests it with Docker only. Apply them to a test namespace first.

Before you start

kubectl access to a namespace, Docker, and a registry your cluster can pull from.
The rules as source rulesets (with the OpenAPI schemas they reference) or as bundles compiled in CI. Prefer bundles: the server then serves exactly what CI built and reviewed.

Steps

Build and push the image

docker build -f packages/server/Dockerfile -t registry.example.com/rule-cascade-server:1.0.0-alpha.2 .
docker push registry.example.com/rule-cascade-server:1.0.0-alpha.2

Replace the placeholder image: in deploy/kubernetes/deployment.yaml (ghcr.io/yarlisaisolutions/rule-cascade-server:1.0.0-alpha.2) with your image.

Put the rules in a ConfigMap

kubectl create configmap rule-cascade-rules --from-file=examples/contracts

The Deployment mounts it read-only at /rules (RULES_DIR). A ruleset id may be defined once.

Create the token Secret

kubectl create secret generic rule-cascade-server --from-literal=token="$(openssl rand -hex 32)"

The token protects POST /evaluations, the server manifest, bundles and server-only rule details. The client manifest, the ruleset list and the probes stay public, so browsers and the kubelet need no token.

The token is required

Deploy with RULE_SERVER_TOKEN set from this Secret. The server exits with status 1 at start-up without it, and the Deployment reads the Secret without optional, so a pod without it stays in CreateContainerConfigError. To run without a token on a private network, replace the RULE_SERVER_TOKEN entry in deployment.yaml with { name: RULE_SERVER_ALLOW_OPEN, value: "1" }; the server logs a warning at start-up.

Apply the manifests

kubectl apply -f deploy/kubernetes/
kubectl rollout status deployment/rule-cascade-server

If any ruleset fails a load check or any bundle is unusable, the process exits before it listens and the pod never becomes ready (GET /readyz).

Verify from inside the cluster

kubectl run rc-check --rm -it --restart=Never --image=curlimages/curl -- \
  curl -s http://rule-cascade-server/readyz
kubectl port-forward service/rule-cascade-server 8080:80 &
curl -s -o /dev/null -w '%{http_code}\n' localhost:8080/evaluations -d '{}'      # 401: token enforced
TOKEN=$(kubectl get secret rule-cascade-server -o jsonpath='{.data.token}' | base64 -d)
curl -s localhost:8080/evaluations -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"ruleset":"acme.payments.transfer","entity":"Transfer","operation":"create","data":{"type":"domestic","amount":-5}}'

The Service listens on port 80 and forwards to the container's port 8080. The server speaks plain HTTP: keep the Service inside the cluster and put TLS and external authentication in your gateway.

Publish new rules

Treat rules like code: a new ConfigMap and a rolling restart.

kubectl create configmap rule-cascade-rules --from-file=examples/contracts -o yaml --dry-run=client | kubectl apply -f -
kubectl rollout restart deployment/rule-cascade-server
kubectl rollout status deployment/rule-cascade-server

maxUnavailable: 0 keeps every old pod serving until a new one is ready, and a pod whose rules fail to load never becomes ready, so a broken ruleset stops the rollout at the first pod while production keeps the previous rules.

Rotate the token

Update the Secret, then restart the Deployment; the callers switch to the new token at the same time.

kubectl create secret generic rule-cascade-server --from-literal=token="$(openssl rand -hex 32)" \
  -o yaml --dry-run=client | kubectl apply -f -
kubectl rollout restart deployment/rule-cascade-server

Done when three replicas are ready across zones; /readyz answers 200; POST /evaluations answers 401 without the token and an evaluation result with it; and a deliberately broken ruleset in the ConfigMap stops the rollout at the first pod while the old pods keep serving.

Custom operators: the image runs the stock rule-cascade-server command, which registers none. Rules that need one fail closed. To supply them, build an image around createRuleServer (package README).

Source: site/content/docs/playbooks/deploy-rule-server-kubernetes.mdx

Deploy the rule server on Kubernetes

On this page