Canvas Portal v2¶
A web management portal for an ODA Canvas. It is the successor to the Spring Boot + Vue portal in canvas-portal/.
Part |
Stack |
Role |
|---|---|---|
|
React 18, Vite, TypeScript, Ant Design, React Query, |
The UI. Served by nginx in production. |
|
FastAPI, |
The API. It reads and writes the cluster. |
|
Helm chart |
Deploys both parts, plus RBAC, volumes and a Keycloak init job. |
Features¶
Components: list ODA Components with status, pods, APIs and events (
/api/components).APIs: browse exposed and dependent APIs, with an API relationship graph and resource map.
Gateway: view Istio, Kong or APISIX resources. The backend detects the gateway at startup from the deployment names in the
canvasnamespace.Operators and pods: view operators and pods, with live log streaming. See how operators are discovered.
Helm (admins only): manage chart repositories, then install, uninstall and view history and values for releases. Installs are limited to configured namespaces and, optionally, allowed chart sources.
Conformance (admins only): run the Canvas BDD tests from the repo, view logs, and download the cucumber and HTML reports.
Model gateway: create, edit and delete
ModelGatewayServiceresources, and proxy chat requests through them.Cluster overview and observability: a cluster summary, plus Grafana and Prometheus links if configured.
Authentication: Keycloak or Entra ID (
IDM_PROVIDER). The backend validates the JWT and the browser keeps a refresh cookie.
Prerequisites¶
A running ODA Canvas. The
canvasnamespace must exist for gateway detection.A Keycloak realm with a
canvas-portalclient and acanvas-portal-adminservice client. The chart does not create the realm or the clients. Itskeycloak.initjob (which needs the Keycloak master admin password) creates the admin group and realm role (see Admin access) and grants thecanvas-portal-adminservice account its permissions.Persistent storage: 5Gi for the backend (Helm repo catalog and conformance runs) and 1Gi for the frontend.
Deploy with Helm¶
helm install canvas-portal ./helm/canvas-portal -n <ns> \
--set keycloak.init.adminPassword=... \
--set backend.env.KEYCLOAK_URL=https://<keycloak>/auth \
--set frontend.nginx.keycloakUpstream=https://<keycloak>/auth
Images default to tmforumodacanvas/canvas-portal (tags frontend-0.1.0 and backend-0.1.0). Review these defaults in helm/canvas-portal/values.yaml before installing, because several look environment-specific:
KEYCLOAK_URLandfrontend.nginx.keycloakUpstreamdefault to a hardcoded IP.keycloak.init.adminUserdefaults totestadminpo..CORS_ORIGINSincludes the placeholderhttp://xx.xx.xx.xx.rbac.*.targetNamespacesdefaults tocomponents,odacompns-1andtemp-namespace. Add any namespace you want to install into or run conformance tests in, then runhelm upgrade.Both Services are
LoadBalancerby default.backend.auth.cookieSecureisfalse. Set it totruewhen serving over HTTPS.The Keycloak realm defaults to
odariin the chart, but tocanvasinfrontend/.env.exampleand the frontend entrypoint.
Build the images¶
docker build -t <repo>:frontend-0.1.0 frontend
docker build -t <repo>:backend-0.1.0 backend
Then set frontend.image.* and backend.image.* in the chart values.
Authentication¶
Login goes through the backend, not through keycloak-js.
The login page posts
{username, password}toPOST /auth/login. The backend runs a Keycloak password grant against thecanvas-portalclient.The access token is returned in the response body and held in memory only by
frontend/src/lib/auth.ts. The refresh token goes into anhttpOnlycookie (canvas_portal_refresh, path/auth,SecureandSameSiteset bybackend.auth.*).On a page reload,
main.tsxcallsPOST /auth/refreshto turn the cookie into a new access token.useSessionManagershows a warning before expiry.client.tsretries on a 401.POST /auth/logoutrevokes the refresh token at Keycloak and clears the cookie.Every
/api/*route uses theget_current_userdependency. It verifies the bearer JWT (RS256, signature via the realm JWKS,expandiss) and builds anAuthUserfrompreferred_username,email,groupsandsub.
First-login flow: if Keycloak answers “Account is not fully set up”, /auth/login returns 409. The UI then asks for a new password and calls /auth/set-initial-password. The backend uses the canvas-portal-admin service client (KEYCLOAK_ADMIN_CLIENT_SECRET) to clear required actions and reset the password. GET /auth/security-status warns when the Canvas default admin/adpass credentials still work in the odari realm.
frontend/src/lib/keycloak.ts (a keycloak-js redirect flow) exists but is not imported by the login path.
Entra ID is selectable with IDM_PROVIDER=entraid, but /auth/login, /auth/refresh and set-initial-password use the Keycloak token endpoint only. With Entra ID, only bearer-token validation on the API is covered.
Admin access¶
/api/helm/* and /api/conformance/* require the user to hold one of the names in backend.auth.adminGroups (env AUTHZ_ADMIN_GROUPS, a JSON list, default ["canvas-admin"]). Everyone else gets 403.
With Keycloak, the backend checks both the
groupsclaim and the realm roles (realm_access.roles). A leading/in group paths is ignored, so/canvas-adminmatchescanvas-admin.On install and upgrade, the
keycloak.initjob creates a group and a realm role for each name (top-level names only), and gives the group that role. It does not assign users.To grant access, add the user to the
canvas-admingroup or assign them thecanvas-adminrealm role. Realm roles are in the access token by default, so no extra Keycloak mapper is needed.The check fails closed: an empty
adminGroupslist denies everyone.backend.auth.allowAllAuthenticated: true(envAUTHZ_ALLOW_ALL_AUTHENTICATED) turns the check off, so any logged-in user can use Helm and conformance again.Upgrading an existing install: after the upgrade, Helm and conformance return 403 until users are in the group or have the role. To keep the old behaviour, set
backend.auth.allowAllAuthenticated: true.The UI does not hide these pages from other users. They see an error when the API returns 403.
Security notes¶
Role check on Helm and conformance only. See Admin access. All other routes (components, gateway, pods, operators, model gateway and so on) are open to any authenticated user.
Backend service account for everything.
get_impersonated_client()ignores the user and returns the shared backend client. Kubernetes audit logs show the portal service account, not the person. The Helm router logs the username.TLS verification is off for Keycloak. The backend calls Keycloak with
httpx.AsyncClient(verify=False), and thekeycloak-initjob disables certificate checks.Audience is not verified (
verify_audis false), so tokens issued to any client in the realm are accepted.Out-of-cluster mode disables TLS verification to the API server if
K8S_REMOTE_CA_CERTis empty.
RBAC model¶
The backend runs as one ServiceAccount, and the chart grants it these permissions.
Template |
Scope |
Grants |
|---|---|---|
|
Cluster-wide, read-only |
|
|
Per namespace in |
A |
|
Per namespace |
Write access on |
|
Cluster roles plus per-namespace roles |
What the BDD runner needs. |
How this fits together:
INSTALL_TARGET_NAMESPACES_JSONin the backend ConfigMap comes fromrbac.canvasInstallAccess.targetNamespaces. The Helm install and uninstall routes return 403 for other namespaces if the list is non-empty, so the app check and the RoleBindings stay in sync.To allow a new namespace, add it to
targetNamespacesand runhelm upgrade. WithcreateNamespaces: falseit must already exist.create_namespacein the install request only works if the service account may create namespaces. The error handler hints at this.The namespaced
adminrole is powerful inside those namespaces (secrets, workloads, RBAC). Only users with the admin role can reach the Helm routes (see Admin access), so keep that role to people you would trust with those namespaces.
Helm install flow¶
Helm operations run by shelling out to the helm v3.15.4 binary baked into the backend image (backend/k8s/helm/installer.py).
Repositories (
/api/helm/repos) are kept in a JSON catalog on the PVC (/app/data/helm-repositories.json).POST /reposadds one andPOST /repos/{name}/syncrefreshes its chart index. The portal does not rely on the container’shelm repostate.Browse and configure. The UI lists charts and versions from the catalog and fetches default values with
GET /api/helm/values.Install (
POST /api/helm/install):It checks the namespace against
INSTALL_TARGET_NAMESPACES_JSON.It checks
repo_urloroci:///http(s)://chart refs againstbackend.helm.allowedChartSources. An empty list allows any source.It writes a temporary kubeconfig that uses the service account token. In-cluster this is the mounted token and CA. Out-of-cluster it is
K8S_REMOTE_*.It runs
helm upgrade --install <release> <chart> -n <ns> --wait --timeout <1-60>m [--create-namespace] [--version] [--repo] -f <values>, so installing an existing release name upgrades it. Values come fromvalues_yamlorvalues.On failure it returns 500 with the Helm error plus a hint for known RBAC problems.
Manage.
GET /releases,GET /history,GET /releases/valuesandDELETE /uninstallcover the lifecycle. The frontend modals areHelmInstallModal,HelmHistoryModalandHelmReleaseManagementModals. nginx gives/api/a 10-minute read timeout because installs use--wait.
Deploying the portal itself¶
On helm install or helm upgrade, a post-install/post-upgrade hook Job (keycloak-init) runs a Python script. It logs in to Keycloak’s master realm as keycloak.init.adminUser, creates a group and a realm role for each backend.auth.adminGroups entry (if missing) and maps the role onto the group, finds the canvas-portal-admin client’s service account, and grants it manage-users, view-users and query-users from realm-management. It retries 5 times and warns if the client is missing.
Order of work:
Create the Keycloak realm and clients first. The init job does not create them.
Fill in the Keycloak URL, realm,
KEYCLOAK_ADMIN_CLIENT_SECRETandkeycloak.init.adminPassword. The chart fails to render ifKEYCLOAK_URLis empty.List every namespace you will install into in the
rbac.*.targetNamespacesvalues.After install, check
kubectl get svcfor the frontend external IP, then add that origin tobackend.env.CORS_ORIGINS.Verify with
GET /health. It returns the detectedcanvasTypeand the IDM provider.
The frontend gets its runtime settings (APP_API_BASE_URL, APP_KEYCLOAK_*) from config.js, which the nginx entrypoint writes at container start. nginx proxies /api/* and the session endpoints to BACKEND_UPSTREAM, and Keycloak paths under /auth/realms|resources|js|admin to KEYCLOAK_UPSTREAM.
Operators page: how operators are discovered¶
The Operators page (/operators, backed by GET /api/operators) shows one card per Canvas operator. The backend scans the Deployments it can read and decides which ones are operators:
Labels (preferred). A Deployment that carries the opt-in label
oda.tmforum.org/operator: "true"or anoda.tmforum.org/operatorIdlabel is listed as one operator.Built-in signatures (fallback). Otherwise, the backend matches the container names, images and Deployment name against a built-in list of known Canvas operators (
OPERATOR_SIGNATURESinbackend/k8s/resources/operators.py). A Deployment that hosts several known operators produces one card per operator.Deployments that match neither are ignored.
Labelled operators therefore appear on the page as soon as they are installed. The portal needs no code change and no rebuild.
Label contract¶
All keys go on the Deployment’s own metadata, not on the Pod template.
Key |
Kind |
Meaning |
|---|---|---|
|
label |
|
|
label |
Operator name, used in the detail page URL. Defaults to the Deployment name. The card shows a readable form of it (see below). |
|
label |
TMF operator ID shown as a badge (for example |
|
annotation |
Container used for the image and readiness when the Deployment has several containers. Defaults to the container named after the operator or the Deployment, else the first container. |
Label values must be 63 characters or fewer and may contain only letters, digits, -, _ and ., so use a slug such as api-operator-kong for operatorName. The portal turns it into a readable name for the card title, the detail page heading and the badge tooltip: it splits the slug on -, _ and ., starts each word with a capital letter, and writes a few known abbreviations (API, APISIX, AI, PDB, ODA, TMF, OAuth2) in their usual case. For example, api-operator-kong becomes API Operator Kong. The portal doesn’t use its built-in list of operator names for labelled operators.
Example¶
Add the labels to the operator’s Deployment template in its Helm chart:
apiVersion: apps/v1
kind: Deployment
metadata:
name: acme-operator
labels:
oda.tmforum.org/operator: "true"
oda.tmforum.org/operatorName: acme-operator # shown as "Acme Operator"
oda.tmforum.org/operatorId: TMFOP0xx # optional badge
annotations:
oda.tmforum.org/operatorContainer: acme-operator # optional
To try it on a running operator without changing its chart:
kubectl label deployment acme-operator -n canvas oda.tmforum.org/operator=true
Notes¶
The labels affect only what the portal displays. They grant no privileges, and the backend reads Deployments with its usual credentials.
The backend first lists Deployments in all namespaces. If it isn’t allowed to (403/404), it scans only a built-in list of Canvas namespaces (
CANVAS_OPERATOR_NAMESPACESinbackend/k8s/resources/operators.py). An operator in any other namespace then stays hidden until the backend’s service account can list Deployments cluster-wide.Label discovery covers Deployments only. Operators that run as a StatefulSet or DaemonSet are not listed.
Operators that share a single Deployment should keep relying on the built-in signatures, because the label path produces one card per Deployment.
The detail page, pod list and logs work the same way for operators found by either path.
Operators found by the built-in signatures keep their built-in name (for example
component-operator) and the full TMF name in the badge tooltip.
Local development¶
The backend only needs a Kubernetes API URL and a token, so you can run the backend and frontend on your machine against any cluster.
Make a service account for the portal. Reuse the chart’s RBAC by installing the chart once, then read the backend service account’s token:
kubectl -n <ns> create token <backend-serviceaccount> --duration=8h kubectl config view --raw --minify -o jsonpath='{.clusters[0].cluster.server}' kubectl config view --raw --minify -o jsonpath='{.clusters[0].cluster.certificate-authority-data}'
K8S_REMOTE_CA_CERTtakes the base64 value as printed.Install
helmlocally (v3). The Helm routes call it, and all other features work without it.Run the backend from
backend/with the variables below, plusHELM_REPOSITORY_CATALOG_PATH=./data/helm-repositories.jsonand the other paths inconfig.py:APP_ENV=development K8S_MODE=outofcluster \ K8S_REMOTE_API_URL=<server> K8S_REMOTE_SA_TOKEN=<token> K8S_REMOTE_CA_CERT=<b64-ca> \ KEYCLOAK_URL=<keycloak-url>/auth KEYCLOAK_REALM=<realm> \ AUTH_COOKIE_SECURE=false CORS_ORIGINS='["http://localhost:3000"]' \ INSTALL_TARGET_NAMESPACES_JSON='["components"]' \ CONFORMANCE_RUN_STORE_PATH=./data/conformance-runs.json \ CONFORMANCE_WORK_DIR=./data/conformance-work \ CONFORMANCE_SCRATCH_DIR=./data/conformance-scratch \ uvicorn main:app --port 8080 --reload
The
CONFORMANCE_*defaults point at/app/dataand/var/conformance-scratch, which only exist in the container. Settings come from environment variables or a.envfile (seebackend/config.py). WithAPP_ENV=development, Swagger is served at/docs. To use the Helm and conformance pages, log in as a user with the admin role (see Admin access), or setAUTHZ_ALLOW_ALL_AUTHENTICATED=truefor local testing.Run the frontend from
frontend/:cp .env.example .env # set VITE_KEYCLOAK_*, VITE_DEV_KEYCLOAK_PROXY_TARGET; remove VITE_API_URL npm ci && npm run dev # http://localhost:3000
The production nginx image is configured instead with
APP_*variables, which its entrypoint writes intoconfig.js.Gotchas.
The Vite dev server proxies
/api,/healthand all/auth/*session endpoints to the backend (VITE_DEV_BACKEND_URL, defaulthttp://localhost:8080), and/auth/realms|resources|js|adminto Keycloak (VITE_DEV_KEYCLOAK_PROXY_TARGET). LeaveVITE_API_URLunset in dev so requests stay same-origin and the cookie works.The refresh cookie has
SameSite=strictand path/auth. For a cross-origin dev setup, useAUTH_COOKIE_SAMESITE=laxor run both onlocalhost.A port-forward also works:
kubectl port-forward svc/<backend-svc> 8080:8080lets you run only the frontend locally.The Keycloak realm must be reachable from the backend host.
Tests¶
Backend unit tests use pytest:
cd backend
pip install -r requirements-dev.txt
pytest