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

Method	API server base URL	Dashboard	Typical use
Ingress	`https://<host name>`	`https://<host name>/dashboard/`	Production
HTTPRoute	`https://<host name>`, except the root path	`https://<host name>/dashboard/`	Production on clusters with the Gateway API
Port forward	`http://localhost:8080`	Not available	Operator 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 accepts only the host names localhost, 127.0.0.1 and ::1, so MCP clients connect through the port forward in the current release, as MCP server describes.
Request size. The API server accepts request bodies up to 2 MB. An ingress controller with a lower limit rejects larger requests first; ingress-nginx, for example, defaults to 1 MB.

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: 2m
  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 has three rules:

Match	Action
Path prefix `/dashboard`	Forward to the Service `foundation4ai-dashboard`
Exact path `/`	Redirect to `/dashboard`
Path prefix `/`	Forward to the Service `foundation4ai-api-server`

Because of the redirect, a request for the root path of the host name reaches the dashboard, not the API server. Checks through a Gateway use POST /login, as described in Access validation.

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, but the Ingress and the HTTPRoute still route /dashboard to the Service foundation4ai-dashboard. Requests under /dashboard then fail at the ingress controller or Gateway, and the Gateway reports ResolvedRefs as False. 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 serves the dashboard pages, but the sign-in fails, because the dashboard sends the sign-in request to /login on the forwarded port, where no API server answers. A local setup that serves the dashboard and the API server on one origin is not yet documented. 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:

Path	Content
`/docs`	Interactive reference built with RapiDoc
`/_docs-swagger`	The same reference in Swagger UI
`/openapi.json`	The 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 two authenticated requests: POST /login with the master key, then a list request that reads from the database. GET /healthz is not a validation, because /healthz reports every component as healthy without checking the components.

Set the shell variables with the base URL of the access method and the master key identifier and secret from the secrets file:

export FOUNDATION4_URL=https://<host name>
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": ["*"]}
  }
}

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:

Result	Cause	First check
No connection	The port forward stopped, or the ingress or Gateway does not route the host name	`kubectl -n foundation4ai get ingress,httproute`
Status 502 or 503 from the ingress controller or Gateway	No ready API server pod behind the Service	`kubectl -n foundation4ai get endpoints foundation4ai-api-server`
Status 401	Wrong key identifier or secret, or the API server cannot read API keys from the database	`kubectl -n foundation4ai logs job/foundation4ai-api-server-create-admin-api-key`
Status 413	A request body above the limit of the ingress controller or the API server	The body size annotation of the Ingress

Troubleshooting describes each failure in detail.

Access paths​

Ingress​

HTTPRoute​

Dashboard disabled​

Port forward​

Dashboard access​

API reference​

Access validation​