Kubernetes
The production install: the platform-aio Helm chart on a cluster you run. We run it on RKE2
with Cilium, HAProxy at the edge and gVisor for container apps. Try it first on a laptop with
k3d; the steps are the same.
The chart is published per release:
helm repo add excalibase https://excalibase.github.io/excalibase-service
helm repo update excalibase
helm search repo excalibase/platform-aio --versions
Chart version 1.5.1 runs the excalibase/*:1.5.1 images. Always install a release version,
never a moving tag.
1. Cluster
| Need | Why |
|---|---|
| Kubernetes 1.30+ | CloudNativePG 1.30 supports 1.34 to 1.36; we run 1.35 (RKE2) |
| Cilium 1.19+ as the CNI | enforces the NetworkPolicies every project relies on; apps are fenced by CiliumNetworkPolicies and functions' outbound allowlist uses host names (toFQDNs) |
| A default StorageClass (ReadWriteOnce) | the platform database, NATS, the bundled object store and every project database |
| 4 CPU / 8 GiB on one node, at least | the platform alone requests about 1.5 CPU; paid tiers need 3 nodes |
gVisor (runsc) on the nodes that run apps | container apps run under the gvisor RuntimeClass |
A CNI that ignores NetworkPolicy (plain flannel, minikube's default) installs fine and isolates
nothing. On RKE2, select cni: cilium with kube-proxy replacement, so HAProxy's host ports also
work from inside the cluster (cert-manager's HTTP-01 self-check depends on it).
For sized, hard-limited project volumes use a StorageClass that enforces size (we use OpenEBS LVM LocalPV) and tell the chart about it:
provisioning:
tenantStorage:
requireSizedVolumes: true
className: openebs-lvm # your sized StorageClass
lvmVolumeGroup: excalibase # the volume group it carves from (or nodeCapacity)
local-path does not enforce sizes: a project can fill the node's disk.
2. Operators
kubectl apply --server-side -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.30/releases/cnpg-1.30.1.yaml
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml
kubectl -n cnpg-system wait --for=condition=available deployment/cnpg-controller-manager --timeout=300s
kubectl -n cert-manager wait --for=condition=available deployment --all --timeout=300s
kubectl apply --server-side -f https://github.com/cloudnative-pg/plugin-barman-cloud/releases/download/v0.15.0/manifest.yaml
kubectl -n cnpg-system rollout status deployment/barman-cloud --timeout=300s
The Barman Cloud plugin archives every project's WAL and takes its base backups. cert-manager issues the plugin's mutual-TLS certificates, the DocumentDB plugin's, and your public certificates.
3. Edge (HAProxy)
HAProxy runs on every node on host ports 80 and 443. It drops any X-Forwarded-For a client sends,
so the platform's per-client limits cannot be forged:
cat > haproxy-values.yaml <<'YAML'
controller:
kind: DaemonSet
daemonset: { useHostPort: true, hostPorts: { stat: null } }
service: { enabled: false }
containerPort: { http: 8080, https: 8443 }
ingressClass: haproxy
ingressClassResource: { name: haproxy }
config:
frontend-config-snippet: |
http-request del-header X-Forwarded-For
YAML
helm repo add haproxytech https://haproxytech.github.io/helm-charts
helm install haproxy haproxytech/kubernetes-ingress --version 1.54.2 \
-n haproxy-controller --create-namespace -f haproxy-values.yaml --wait
ingress-nginx works too (ingress.className: nginx, appHosting.ingressClass: nginx).
4. DNS and TLS
Point these names at your nodes: studio.example.com (Studio and its API), api.example.com
(every project's data plane), files.example.com (customer files) and *.apps.example.com
(container apps). Then a Let's Encrypt issuer:
kubectl apply -f - <<'YAML'
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata: { name: letsencrypt }
spec:
acme:
email: ops@example.com
server: https://acme-v02.api.letsencrypt.org/directory
privateKeySecretRef: { name: letsencrypt-account }
solvers:
- http01: { ingress: { ingressClassName: haproxy } }
YAML
5. Secrets
The chart reads credentials only from Secrets you create; nothing secret goes in the values file. For email through your own SMTP relay:
kubectl create namespace excalibase-platform
kubectl -n excalibase-platform create secret generic smtp-creds \
--from-literal=username=excalibase@example.com --from-literal=password='<relay password>'
Amazon SES, Resend, an external bucket and AWS KMS are in Configuration.
6. Values
# values.yaml
provisioning:
studioUrl: https://studio.example.com
publicBaseUrl: https://api.example.com
registrationMode: invite # only invited addresses may sign up
persistence: { enabled: true }
backupCredentials: { provider: sts }
denoRuntime: { egressPolicy: cilium }
auth:
edge:
namespace: haproxy-controller
podLabels: app.kubernetes.io/name=kubernetes-ingress
podPorts: "8080,8443"
podCIDRs: 10.42.0.0/16 # your cluster's pod CIDR
ingress:
enabled: true
host: api.example.com
tls: { clusterIssuer: letsencrypt }
admin:
enabled: true
host: studio.example.com
public: true # or allowCidrs: "203.0.113.0/24" to restrict Studio
tls: { clusterIssuer: letsencrypt }
cors:
origins: https://studio.example.com
secureCookies: "true"
email:
provider: smtp
fromAddress: noreply@example.com
smtp: { host: smtp.example.com, credentialsSecret: smtp-creds }
objectStore:
bundled: { enabled: true, publicUrl: https://files.example.com, storage: 100Gi }
platformDb:
backup: { enabled: true, schedule: "0 0 2 * * *", retention: 30d }
vault:
unseal: { provider: manual }
appHosting:
enabled: true
domain: apps.example.com
ingressFromNamespace: haproxy-controller
ingressFromLabels: app.kubernetes.io/name=kubernetes-ingress
observability:
serviceMonitors: { enabled: false } # true once kube-prometheus-stack is installed
Every key is explained in Configuration.
7. Install
helm install platform-aio excalibase/platform-aio --version 1.5.1 \
-n excalibase-platform --create-namespace -f values.yaml --timeout 15m
kubectl -n excalibase-platform wait --for=condition=complete job/platform-bootstrap --timeout=15m
kubectl -n excalibase-platform get pods
Do not add --wait to the first install: auth and the API engine start only after the bootstrap
Job has run, and Helm runs that Job after --wait would give up.
8. First sign-in
kubectl -n excalibase-platform get secret platform-setup-token -o jsonpath='{.data.token}' | base64 -d; echo
Open https://studio.example.com/setup, paste the one-time setup token and create the platform
admin with a password of your own. With vault.unseal.provider: manual, Studio then asks you to
initialize the vault and shows its unseal key once: keep it off the server. After every restart
of the control plane, sign in and paste the key to unseal (see
Configuration).
Create a project, a table, an app: everything works as on Excalibase Cloud, with
https://api.example.com as the base URL in Connect to your project.
Container apps under gVisor
Install gVisor's runsc and its containerd shim on every node that should run apps (see
gVisor's containerd guide), label those
nodes, and create the RuntimeClass the chart expects:
kubectl label node <node> excalibase.io/gvisor=true
kubectl apply -f - <<'YAML'
apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata: { name: gvisor }
handler: runsc
scheduling: { nodeSelector: { excalibase.io/gvisor: "true" } }
YAML
The control plane refuses to start app hosting while the RuntimeClass is missing. Apps are served
over HTTP until you give them certificates: appHosting.customDomains.enabled: true with
appHosting.customDomains.issuer.email issues one per app host over HTTP-01.