Trust the install CA and enforce HTTPS
Every hop inside a Ramen install is TLS, signed by the install's own CA (transport → TLS). Your browser and your tools do not know that CA, so anything you open through a port-forward or on the local compose stack shows a certificate warning until you trust it:
| What | Address | Signed by |
|---|---|---|
| Phoenix (trace UI) | https://localhost:6006 after kubectl -n ramen-system port-forward svc/phoenix 6006 — sign in as admin@localhost |
install CA |
| Jaeger (trace UI) | https://localhost:16686 after kubectl -n ramen-system port-forward svc/jaeger 16686 — user admin |
install CA |
| promptfoo (evals UI) | https://localhost:3443 after kubectl -n ramen-system port-forward deploy/promptfoo 3443:3443 — user admin |
install CA |
| Local compose: console, worker, Redis, Phoenix, promptfoo | https://localhost:… |
the compose CA (deploy/local/.certs/ca/ca.crt) |
| The console and workers through the edge | your public host name | a public CA (Google-managed, Let's Encrypt) or the certificate you gave the edge — not the install CA |
The three engines also ask for a sign-in (since 1.0.0, D92): one password per install, generated by the chart into
Secret ramen-engines and never printed. A super admin with cluster access reads it:
A port-forward goes around every NetworkPolicy, which is why the engines do not rely on them. Local compose: the
same password is RAMEN_ENGINES_PASSWORD in deploy/local/.env (make env).
So you only need the install CA for the in-cluster services you reach yourself. Clients that use the public edge
(Claude Code, the bridge, curl against the console's address) need nothing from this page unless your edge uses a
self-signed certificate (the AWS guide's ACM import), which is a different certificate with its own --ca.
The CA certificate is public data — trusting it lets your machine verify this install's certificates, nothing more. Its private key never leaves the console.
1. Export the certificate
From a cloud install (the ConfigMap is in every namespace that talks TLS; ramen-system is enough):
From the local compose stack, the file already exists: deploy/local/.certs/ca/ca.crt (created by the certs
service on the first make up, kept across runs).
Check what you got — the subject names the install:
During a CA rotation the file holds two certificates (the old and the new CA) until the old one is retired; trust the file as it is, and export it again after the retire.
2. Trust it
Keychain Access: File → Import Items…, pick ~/ramen-ca.crt into the login keychain, double-click the
certificate, open Trust and set When using this certificate to Always Trust. Or from a terminal:
Safari and Chrome use the keychain; restart the browser tab. Firefox keeps its own store (below).
Double-click ramen-ca.crt → Install Certificate… → Current User → Place all certificates in the
following store → Trusted Root Certification Authorities. Or in PowerShell:
Edge and Chrome use this store.
Debian / Ubuntu:
Fedora / RHEL: sudo cp ~/ramen-ca.crt /etc/pki/ca-trust/source/anchors/ && sudo update-ca-trust.
Chrome on Linux reads its own NSS store: Settings → Privacy and security → Security → Manage certificates →
Authorities → Import.
Settings → Privacy & Security → Certificates → View Certificates… → Authorities → Import…, pick the file and tick Trust this CA to identify websites.
Then open https://localhost:6006 or https://localhost:3443 again: no warning. The leaves carry localhost and
127.0.0.1 besides their in-cluster names, so the name matches through a port-forward.
3. Command-line tools
You do not have to trust the CA system-wide; point a single tool at the file instead:
curl --cacert ~/ramen-ca.crt https://localhost:3443/health # curl
REQUESTS_CA_BUNDLE=~/ramen-ca.crt python my_script.py # Python requests / httpx (SSL_CERT_FILE too)
NODE_EXTRA_CA_CERTS=~/ramen-ca.crt node my_script.js # Node.js
uvx ramen-mcp-bridge --ca ~/ramen-ca.crt --target localhost:8080 … # the bridge, against the local compose worker
The bridge's --ca replaces its trust store (RAMEN_BRIDGE_CA is the same), so use it only for a target the
install CA signed — the local worker, or a port-forward to a pod — never for the public edge.
After a rotation
A super admin rotates the CA with POST /api/v1/config/tls/rotate and, once every leaf is new, retires the old one
(…/rotate?retire=1); GET /api/v1/config/tls shows the stage. Your exported file stops matching once the old CA is retired: export it again (step 1) and
trust the new certificate; you can remove the old Ramen install CA entry from your keychain or store.
Remove it
macOS: delete the Ramen install CA … certificate in Keychain Access (or
security delete-certificate -c "Ramen install CA <id>"). Windows: certmgr.msc → Trusted Root Certification
Authorities → delete it. Debian / Ubuntu: delete /usr/local/share/ca-certificates/ramen-ca.crt and run
sudo update-ca-certificates --fresh. Firefox: Authorities → select → Delete or Distrust.
How Ramen enforces HTTPS
Trusting the CA removes a warning; it never turns encryption on or off. HTTPS is enforced by the install itself, and there is no setting that turns it off on a cloud install (decision D86, contract §39):
| Layer | What is enforced |
|---|---|
| The chart | tls.require is always true — helm install … --set tls.require=false fails to render. Every pod gets RAMEN_REQUIRE_TLS=1. |
| The console | Plain http:// to a page or the API: a GET is redirected (301) to https://, anything else is refused with 403 "HTTPS required"; responses carry Strict-Transport-Security (one year) so a browser never tries plain HTTP again. It refuses to start with RAMEN_WORKER_TLS=0, a redis:// Redis URL, or an http:// internal or evals URL. |
| The console API | An http:// telemetry endpoint, http:// LLM base URL or redis:// throttle URL is answered 422 — never stored. |
| Workers (node) | Serve TLS only (the load balancer speaks HTTP/2 over TLS to them); refuse to start without their certificate, or with an http:// console, upstream or telemetry URL or a redis:// URL. |
| Chart services | Redis listens on its TLS port only (--port 0); Phoenix, its collector, Jaeger serve TLS; promptfoo, which has no TLS of its own, listens on 127.0.0.1 only behind a TLS front on 3443, and so does Jaeger's query UI (16686). Phoenix's UI and API, Jaeger's and promptfoo's fronts want a credential (D92). |
| The network | NetworkPolicies admit only the TLS ports (e.g. promptfoo 3443, never 3000) — enforced on GKE (Dataplane V2), EKS (VPC CNI policy agent) and AKS (Calico). |
| The bridge | TLS by default (bridge 1.0.0, the bridge for Ramen 1.0.0); plaintext needs an explicit --insecure (local development only), which prints a warning and cannot be combined with --tls/--ca. |
| The edge | The public load balancer serves HTTPS with a public certificate (Google-managed, Let's Encrypt) or yours. |
The one plain hop is your own machine's loopback: kubectl port-forward carries the bytes from the cluster inside the
API server's TLS tunnel and hands them to localhost, where your browser speaks TLS again to the forwarded port.
Check it on your install
# the chart will not render without TLS
helm template x deploy/helm/ramen --set tls.require=false # → Error: … tls.require=false: D86 — plaintext is refused
# the console redirects plain HTTP and sends HSTS
curl -sI http://<your-console-host>/login | grep -i -E '^(HTTP|location)'
curl -sI https://<your-console-host>/login | grep -i strict-transport-security
# plaintext telemetry is refused (super admin session or API key)
curl -s -X PUT https://<your-console-host>/api/v1/config/otel -H 'content-type: application/json' \
-H "authorization: Bearer $RAMEN_API_KEY" -d '{"enabled":true,"endpoint":"http://collector:4318"}' # → 422
# every certificate comes from the current CA, and which stage a rotation is in
curl -s https://<your-console-host>/api/v1/config/tls -H "authorization: Bearer $RAMEN_API_KEY"
# promptfoo's plaintext port is loopback-only: from another pod it does not answer
kubectl -n ramen-system get pod -l app.kubernetes.io/name=promptfoo -o wide # note the pod IP
kubectl -n ramen-system run tls-probe --rm -i --restart=Never --image=curlimages/curl:8.11.1 -- \
curl -s -m 5 http://<pod-ip>:3000/health || echo "refused, as it should be"