Access cluster Grafana through Portal

Use Portal to open a managed cluster’s Grafana and query metrics and logs before cluster ingress is available. No local port-forward or Grafana password is needed for this browser route. Grafana is currently the supported service behind the generic Portal access proxy; other internal services are not enabled.

Before you start

The cluster must use native management with the observability add-on installed and a working VPN connector. Its component status must report the current managed configuration as ready. Observation-only and legacy monitoring installations keep their existing access method.

The Portal deployment must enable its packaged Portal access gateway. The UI Pod runs Next.js and the gateway in separate containers using the same image. Its ingress sends /access/ to the gateway and ordinary Portal traffic directly to Next.js; the internal authorization callback prefix must remain blocked from public access. Both containers need the shared callback capability. The API’s configured public Portal URL must match that HTTPS origin. Control Agent must advertise grafana-access-v1, and the matching connector and observability chart versions must be installed. This configures Grafana’s external subpath and trusted proxy authentication automatically.

The cluster needs an enforcing NetworkPolicy implementation. The Grafana Service accepts connections from its trusted VPN connector and Prometheus in the system namespace. Prometheus collects Grafana metrics; it is part of the trusted observability stack. Do not expose this auth-proxy Service through another ingress or generic forwarding service. Grafana and its installed plugins are trusted to serve code on the Portal browser origin in this deployment.

Open Grafana

1. Sign in to Portal and select the Context containing the cluster.
2. Open the cluster’s detail view.
3. Find its observability component and select Open Grafana.
4. Start with Cluster overview, or select another dashboard in the Cluster folder. Each dashboard shows the registered cluster ID. See Inspect cluster health for the investigation flow.
5. For ad hoc queries, open Explore and select Prometheus or Loki.

You have Viewer access. Explore and temporary panel edits are available; saving dashboards or administering users, plugins and data sources requires separate operator access. The five provisioned cluster dashboards are managed with the add-on; they do not install the legacy monitoring dashboards.

Application detail views also provide Grafana and logs links for deployment stages. These open Explore with the corresponding namespace selected. If a stage has more than one eligible cluster, choose the cluster to inspect. The filter is editable and does not limit the telemetry available to your Context.

Open logs from a workload

In the cluster detail view, open Workloads and use the logs icon in a row’s Logs column. This opens Grafana Explore in a new tab with Loki selected, the workload’s namespace and its currently observed pods selected, and a time range covering the last hour. This works for both application and system workloads.

The selection includes exact observed pod names. Replaced pods and historical pods absent from the current inventory are not automatically included. Refresh the cluster view to get a new selection, or edit the query and time range in Grafana. These filters help find logs; they do not restrict telemetry access.

A row without observed pods explains that logs cannot be selected. If Portal Grafana access is unavailable, the column shows the access reason instead of a link. The same managed observability and gateway prerequisites apply as above.

For example, inspect scrape status with:

up{namespace="APP_NAMESPACE"}

For application logs, select Loki and use:

{namespace="APP_NAMESPACE"}

Sharing and snapshots

Managed Grafana disables public dashboards, external snapshot publication and Grafana feedback links. Operators with separate Grafana permissions can still create local snapshots.

Bookmarks and Context changes

The URL identifies the immutable Context and cluster registration:

https://portal.example/access/contexts/CONTEXT_ID/clusters/CLUSTER_ID/grafana/
https://portal.example/access/contexts/CONTEXT_ID/clusters/CLUSTER_ID/grafana/explore

Existing dashboards use the same prefix followed by d/DASHBOARD_UID/SLUG. Copy the URL from the browser to preserve its query and time range. It contains no access credential.

A bookmark stays bound to its original Context. Select that Context in Portal before using the bookmark; switching Context does not silently change its cluster. If your Portal session has expired, sign in again and return to the saved URL.

Portal access uses the same renewable, credential-capped five-minute maximum lease as corectl tunnels. While a request, response body or WebSocket remains active, the gateway refreshes authentication and renews before three minutes of lease remain. Successful fresh authentication can extend that same stream beyond its original access token expiry. It never extends the original browser login cookie’s absolute lifetime or rolls the cookie in the private callback.

Brief Portal or broker interruptions can pause traffic while existing streams retain their last verified lease. Failed checks and cached admission never extend that deadline. Explicit denial and hard expiry close both sides of the stream. A quiet open WebSocket remains active; idle pooled sockets alone do not. The gateway disposes of a session after 60 seconds without active work.

Opening the page again may need a new session. Portal automatically retries one temporary session-creation failure, allowing up to 20 seconds for that stage; establishing the tunnel can take additional time. Keep the page open while it is loading. Refreshing does not extend your access rights, and setup retries do not repeat dashboard operations.

Signing out prevents further credential refresh once logout succeeds; an already issued token can remain usable until its expiry. Changing Context does not retarget existing streams. Sign in again when the absolute browser login expires. Application timeouts and gateway/connector process restarts can still end streams.

Upgrade Portal, broker, connector, gateway and corectl together and reconnect existing sessions. Shared gateway configuration uses PORTAL_ACCESS_* names; Grafana’s concrete target URL retains its /grafana/ suffix.

If access is unavailable

• If the page reports Portal access unavailable, session setup or admission failed. Confirm your sign-in and Context, then retry after a short pause. If it persists, give the operator the cluster name and time of the failure.
• Portal service is temporarily unavailable means forwarding to the service failed. Check the connector and service status; the message alone does not establish that the service restarted.
• Check that you selected the Context named by the bookmarked URL and are still a member of it.
• Check the cluster’s VPN and observability component status. Installation, upgrades, stale observations or an unavailable connector can prevent access.
• Ask the Portal operator to check the gateway route and public Portal URL when all eligible clusters are unavailable.
• A reachable Grafana with empty query results can indicate a collection, namespace or time-range problem. Check the application deployment and collector status separately.

Platform operators with Kubernetes access can still diagnose Grafana through:

kubectl -n core-platform-system port-forward \
  service/core-platform-addon-cluster-observability-grafana 3300:3000

When Portal access is enabled, use the same full Grafana subpath on http://localhost:3300. Operator administration uses separately managed Grafana credentials. Do not share those credentials to grant ordinary Portal access.

Prepare before downgrading

Before downgrading to a Control Agent version without dashboard identity support, set controlAgent.observability.dashboards.enabled=false in the Cluster System values while the current agent is still running. Wait for it to remove grafana.dashboards.clusterId from the observability Application and for Argo to be Synced and Healthy. This switch removes the identity parameter; it does not disable collection or dashboards. Restore it after returning to the current version.

If the target version also lacks Portal Grafana access, complete the following additional steps.

Before downgrading to a Control Agent version without grafana-access-v1, remove the access configuration using the current agent. Older agents reject the Grafana Helm parameters already stored on the observability Argo Application; they cannot remove those parameters after the downgrade.

1. Set the API’s PORTAL_ACCESS_PORTAL_URL to an empty value in the deployment configuration and complete the rollout of every API replica. Keep the current Control Agent and observability chart running, with reconciliation enabled. This disables Portal Grafana access for all clusters served by that API.

2. In each affected cluster, wait for Control Agent to remove the parameters from the owned observability Application. Inspect it with:

   kubectl -n core-platform-system get applications.argoproj.io \
     core-platform-addon-cluster-observability -o yaml

   Confirm spec.source.helm.parameters is absent or empty. Wait for Argo’s current desired state to be Synced and Healthy. Do not proceed while any affected cluster is offline or has not completed this reconciliation.

3. Confirm the Grafana Deployment has rolled out successfully and its current container configuration no longer includes GF_AUTH_PROXY_ENABLED or GF_SERVER_ROOT_URL:

   kubectl -n core-platform-system rollout status \
     deployment/core-platform-addon-cluster-observability-grafana
   kubectl -n core-platform-system get \
     deployment/core-platform-addon-cluster-observability-grafana -o yaml

4. Stop reconciliation and roll back the coordinated API, Control Agent and chart versions. Keep the Portal URL disabled throughout the rollback.

If the agent was already downgraded and reports an ownership conflict, temporarily restore the matching access-capable API, Control Agent and chart versions with PORTAL_ACCESS_PORTAL_URL empty, resume reconciliation and complete steps 2–4. Preserve the existing registration and Application ownership metadata; do not delete or recreate the observability Application to bypass the conflict.