Skip to main content

API and dashboard access

This page describes how client applications and operators reach the API server and the dashboard: through an ingress, through a Gateway API HTTPRoute or through a port forward. The page also describes how to confirm access after installation. Operators configure access with the values of the application release; integrators use the resulting base URL.

Access paths​

MethodAPI server base URLDashboardTypical use
Ingresshttps://<host name>https://<host name>/dashboard/Production
HTTPRoutehttps://<host name>https://<host name>/dashboard/Production on clusters with the Gateway API
Port forwardhttp://localhost:8080Only through a local reverse proxy, as described in Dashboard accessOperator checks and evaluation

The following properties apply to every method:

  • Plain HTTP in the cluster. The API server listens on port 8000 without Transport Layer Security (TLS), behind the Service foundation4ai-api-server on port 80. TLS terminates at the ingress controller or the Gateway.
  • One host name. The dashboard is served under /dashboard/ and sends API requests, including the sign-in request to /login, to the host name that served the dashboard. The dashboard therefore works only where the dashboard and the API server share one host name.
  • Every API path exposed. The ingress and the HTTPRoute forward every path outside /dashboard to the API server, including paths that need no API key. Security hardening describes the paths to restrict at the ingress controller or Gateway.
  • MCP server. The MCP server at /mcp is reachable through every method, at the base URL of the API followed by /mcp. The server accepts any host name unless the configuration restricts the host names, as MCP server describes. Any API server replica answers any MCP request, so MCP clients need no session affinity.
  • Request size. The API server accepts request bodies up to 10 MiB, set by app.max_body_bytes, and answers larger requests with status 413 and a JSON error. An ingress controller with a lower limit rejects larger requests first; ingress-nginx, for example, defaults to 1 MB.
  • Metrics. The API server and the workers serve metrics on port 9090. The Service, the Ingress and the HTTPRoute do not expose port 9090.

Ingress​

With ingress.enabled: true, the application release creates the Ingress foundation4ai. For each entry of ingress.hosts, the Ingress routes paths with the prefix /dashboard to the Service foundation4ai-dashboard and every other path to the Service foundation4ai-api-server.

Create the TLS Secret from the certificate and key of the host name:

kubectl -n foundation4ai create secret tls <tls secret> --cert=<certificate file> --key=<key file>

Expected result: secret/<tls secret> created.

Set the ingress values in foundation4ai.values.yaml. The annotation in this example raises the body size limit of ingress-nginx; other controllers use their own annotations.

ingress:
enabled: true
className: <ingress class>
annotations:
nginx.ingress.kubernetes.io/proxy-body-size: 10m
hosts:
- host: <host name>
tls:
- secretName: <tls secret>
hosts:
- <host name>

Apply the values and read the Ingress:

helm upgrade foundation4ai ./charts/foundation4ai \
-n foundation4ai -f foundation4ai.values.yaml --wait --timeout 10m
kubectl -n foundation4ai get ingress foundation4ai

Expected result: Helm reports STATUS: deployed. The Ingress lists the class, the host name and ports 80, 443, and shows an address once the ingress controller admits the Ingress.

HTTPRoute​

With httpRoute.enabled: true, the application release creates the HTTPRoute foundation4ai for a Gateway that already exists in the cluster. The HTTPRoute routes like the Ingress, with two rules:

MatchAction
Path prefix /dashboardForward to the Service foundation4ai-dashboard
Path prefix /Forward to the Service foundation4ai-api-server

Set the HTTPRoute values in foundation4ai.values.yaml:

httpRoute:
enabled: true
parentRefs:
- name: <gateway name>
namespace: <gateway namespace>
sectionName: <listener name>
hostnames:
- <host name>

The values set the following:

  • Gateway. parentRefs names the Gateway and the listener. Without namespace, the Gateway is looked up in foundation4ai.
  • Listener. The listener terminates TLS for the host name and admits routes from the namespace foundation4ai through the allowedRoutes setting of the Gateway.
  • Host name. hostnames lists the host names that the HTTPRoute serves.

Apply the values and read the HTTPRoute status:

helm upgrade foundation4ai ./charts/foundation4ai \
-n foundation4ai -f foundation4ai.values.yaml --wait --timeout 10m
kubectl -n foundation4ai describe httproute foundation4ai

Expected result: Helm reports STATUS: deployed. The HTTPRoute status lists the Gateway as a parent with the conditions Accepted and ResolvedRefs set to True.

Dashboard disabled​

With dashboard.enabled: false, the chart installs no dashboard, and the Ingress and the HTTPRoute contain no /dashboard rule. Requests under /dashboard then reach the API server, which answers with status 404 and {"error":{"message":"Not found"}}. Client applications do not use the /dashboard path, so API access is unaffected.

Port forward​

A port forward reaches the API server without an ingress. The port forward runs in a separate terminal for as long as access is needed:

kubectl -n foundation4ai port-forward svc/foundation4ai-api-server 8080:80

Expected result: Forwarding from 127.0.0.1:8080 -> 8000. The base URL is http://localhost:8080.

Dashboard access​

The dashboard is optional. Operators open https://<host name>/dashboard/ through the ingress or the HTTPRoute and sign in with an API key identifier and secret, such as the master key.

A port forward to the dashboard Service alone serves the dashboard pages, but the sign-in fails with Login failed: no API server answers at this address. Open the dashboard through the address (ingress or proxy) that also serves the API. The dashboard sends the sign-in request to /login on the forwarded port, where no API server answers.

Without an ingress or an HTTPRoute, a local reverse proxy in front of two port forwards serves the dashboard and the API server on one address. The following procedure uses the web server Caddy on the operator's workstation:

  1. Start one port forward to the dashboard and one to the API server, each in a separate terminal:

    kubectl -n foundation4ai port-forward svc/foundation4ai-dashboard 3000:80
    kubectl -n foundation4ai port-forward svc/foundation4ai-api-server 8000:80

    Expected result: Forwarding from 127.0.0.1:3000 -> 3000 and Forwarding from 127.0.0.1:8000 -> 8000.

  2. Save the following configuration as Caddyfile in an empty directory:

    :8080 {
    handle /dashboard* {
    reverse_proxy localhost:3000
    }
    handle {
    reverse_proxy localhost:8000
    }
    }

    Expected result: the directory contains the file Caddyfile.

  3. Start the proxy in that directory, in a third terminal:

    caddy run

    Expected result: http://localhost:8080/dashboard/ shows the sign-in page, and the sign-in with an API key identifier and secret succeeds.

On a single-node evaluation installation, the dashboard access section of Install for evaluation uses an ingress on the node instead.

API reference​

The API server serves the API reference itself, with no internet access required:

PathContent
/docsInteractive reference built with RapiDoc
/_docs-swaggerThe same reference in Swagger UI
/openapi.jsonThe OpenAPI document

The reference pages load scripts from /assets on the API server. API conventions describes the routes and request conventions, and Send requests from an API client describes the uses and limits of the pages.

Access validation​

Access is confirmed by a health request and two authenticated requests: GET /healthz, which needs no API key, then POST /login with the master key, then a list request that reads from the database.

Set the base URL of the access method and request the health status:

export FOUNDATION4_URL=https://<host name>
curl "$FOUNDATION4_URL/healthz"

Expected result: status 200 and the following response. /healthz checks the connections to the database, NATS JetStream, Valkey and the gRPC service, and answers with status 503 and "status": "error", naming the failed component with error, when a check fails.

{"status":"ok","database":"ok","message_queue":"ok","cache":"ok","llm_service":"ok"}

Set the master key identifier and secret from the secrets file, and sign in:

export FOUNDATION4_API_KEY=<master key identifier>
export FOUNDATION4_API_SECRET=<master key secret>
curl -X POST "$FOUNDATION4_URL/login" \
-H "x-api-key: $FOUNDATION4_API_KEY" \
-H "x-api-key-secret: $FOUNDATION4_API_SECRET"

Expected result: status 201. The following response is shortened to one of the object types:

{
"message": "OK",
"key": "Master Admin Key",
"description": null,
"permissions": {
"pipelines": {"access_level": 7, "classifications": ["*"]}
},
"admin": true
}

List the embedding model that every installation includes:

curl "$FOUNDATION4_URL/embedding-models?name=all-MiniLM-L6-v2" \
-H "x-api-key: $FOUNDATION4_API_KEY" \
-H "x-api-key-secret: $FOUNDATION4_API_SECRET"

Expected result: status 200 and a data list with one entry whose name is all-MiniLM-L6-v2. Authenticate describes the shell variables and creates a key with fewer permissions for the tutorials. In a production installation, First API keys creates the keys of client applications.

The following results point to a specific cause:

ResultCauseFirst check
No connectionThe port forward stopped, or the ingress or Gateway does not route the host namekubectl -n foundation4ai get ingress,httproute
Status 502 or 503 from the ingress controller or GatewayNo ready API server pod behind the Servicekubectl -n foundation4ai get endpoints foundation4ai-api-server
Status 401Wrong key identifier or secret, or a master key that is expired, inactive or missingThe secrets file, and the API server log: kubectl -n foundation4ai logs deploy/foundation4ai-api-server -c server
Status 503 with Unable to validate the API key; try again laterThe API server cannot reach the database or Valkey to check the keycurl "$FOUNDATION4_URL/healthz"
Status 413A request body above the limit of the ingress controller or the API serverThe body size annotation of the Ingress

Troubleshooting describes each failure in detail.