Skip to content

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:

kubectl -n ramen-system get secret ramen-engines -o jsonpath='{.data.password}' | base64 -d; echo

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):

kubectl -n ramen-system get configmap ramen-ca -o jsonpath='{.data.ca\.crt}' > ~/ramen-ca.crt

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:

openssl x509 -in ~/ramen-ca.crt -noout -subject -enddate
# subject=CN=Ramen install CA <id>

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:

security add-trusted-cert -r trustRoot -k ~/Library/Keychains/login.keychain-db ~/ramen-ca.crt

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:

Import-Certificate -FilePath $HOME\ramen-ca.crt -CertStoreLocation Cert:\CurrentUser\Root

Edge and Chrome use this store.

Debian / Ubuntu:

sudo cp ~/ramen-ca.crt /usr/local/share/ca-certificates/ramen-ca.crt && sudo update-ca-certificates

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"