Cluster Console¶

The Cluster Console is a built-in Kubernetes UI (Headlamp) for inspecting and repairing the objects that make up your Pixee Enterprise Server deployment, from a browser. It exists for operators who cannot reach a shell on the server and therefore cannot run kubectl at all. When Pixee Support asks you to check an annotation or delete a stuck workload, this is where you do it.

It is disabled by default, requires a license entitlement, and is only ever reachable behind the same Authentik SSO as the rest of the platform.

What You Can Do With It¶

Read-only access covers the diagnosis half of a support conversation: browsing Deployments, StatefulSets, DaemonSets, Services, ConfigMaps, Ingresses, Gateway API routes, PersistentVolumeClaims and database clusters; reading their full YAML, including annotations and labels; and tailing pod logs.

Full access adds the repair half, across everything in the Pixee namespace: editing any object's YAML in place, creating one that does not exist yet, restarting, scaling and rolling back workloads, deleting one so its controller recreates it, opening a shell in a pod, and revealing a Secret's value.

An edit here lasts until your next deploy, and blocks it

Anything Pixee's own charts set, such as a memory limit, a replica count or an environment variable, is written again on every deploy. Editing it here does not just get overwritten: Kubernetes records the console as the owner of that field, and the next deploy fails rather than quietly reverting your change, with an error naming a conflict on the field you edited.

This is not specific to the console. kubectl edit on the server does exactly the same thing.

To recover, set the value back to what it was and deploy again. Matching values stop the conflict. Removing the ownership record does not help, and neither does deleting the object.

So treat edits here as temporary, for getting through an incident. If you need a setting changed permanently, change it in the Admin Console's configuration, or ask us to expose it there.

What It Can Never Do¶

Two limits are enforced by the console's Kubernetes permissions rather than by its user interface:

At Read-only it cannot read Secrets. Each Secret value in the console sits behind a reveal toggle that decodes it on click, so the read permission is withheld entirely and Secrets do not appear at all. Full access can read them, in the Pixee namespace only, never in cert-manager, kube-system or anywhere else.
It cannot delete a database cluster, or any volume claim that holds your data. These are readable, because their status is diagnostically useful, but they cannot be modified or deleted, because a mistake there is not recoverable.

There is one deliberate exception. At Full access the console can delete the three telemetry volume claims, the ones behind local logs, metrics and traces, because losing one costs you the retention window and nothing else: the StatefulSet creates a fresh claim the next time its pod starts. Those three are named individually in the console's permissions, so no other claim in the deployment is reachable even by accident, and our build fails if that list is ever pointed at a data-bearing volume.

Because the permission names those three claims individually, the console checks the specific claim you are looking at before it offers a Delete control: the button appears on the three telemetry claims and is absent on every other one, so there is no wrong claim to click. Delete from the claim's own page, not from the list. See the note on bulk actions below.

Deleting a claim that is still mounted only marks it for deletion, so the sequence is: scale the store to zero replicas, delete the claim, scale it back. All three steps are available at Full access.

Only Read-only is a boundary

At Read-only these hold absolutely: there is no sequence of clicks that reaches a credential or removes a volume.

At Full access the database and volume-claim limits are guardrails against mistakes, not walls against intent. That is a property of Kubernetes rather than of this console: permission to change a Deployment or a ConfigMap is permission to change what a pod runs and which identity it runs as, and the workload controller then starts that pod for you. Several components here run a script mounted from a ConfigMap, so editing one is enough. This is exactly why the write side is not subdivided; a narrower grant would have implied a protection it could not deliver.

Full access is best understood as root on the server. Its Kubernetes permissions do stop at the Pixee namespace, and it cannot change nodes, kube-system, custom resource definitions or anything else cluster-scoped. But that edge is not a security boundary on an embedded cluster, because the admin console itself runs in the Pixee namespace and mounts the host's cluster directory: a shell in that pod reaches the cluster's administrator credentials. Grant Full access only to people you would trust with root on the machine.

The console does refuse to create a pod that mounts the host filesystem or joins the host's process, IPC or network namespaces, so the one-click route is closed. That narrows the level; it does not bound it.

The console also cannot reach outside your cluster. Its plugin catalog, which would fetch from the public internet, is switched off, so it works identically on an air-gapped install.

It does not show Helm releases. Its Helm view is switched off deliberately: turning it on would also expose install, upgrade, rollback and uninstall for the deployment's own releases, which is not something we want a click away (and upstream reports the view failing under the sign-in method used here in any case). See Seeing Helm Release State below for where that information lives instead.

What It Cannot Do That `kubectl` Can¶

The console is not a replacement for a shell, and it is worth knowing the edges before you need them. The gaps fall into three kinds, which matter differently: some are deliberate and permanent, some are a scope we can widen if you have a reason, and some are simply features the tool does not have.

Deliberate and permanent¶

The console offers none of these. Read the danger note above before treating the first two as a boundary at the write levels.

With the CLI	In the console	Why
`kubectl get secret -o yaml`	Full access, Pixee namespace only	Read-only cannot see Secrets at all. Full access reveals them here, never in another namespace.
`kubectl delete pvc …`	Telemetry claims only	The three logs/metrics/traces claims are deletable and regenerate. Data-bearing claims are not.
`kubectl delete cluster.postgresql.cnpg.io …`	Read-only	Same: the database cluster is not something to remove by mistake.
`kubectl exec …`	Full access	A pod shell, in the Pixee namespace only.
A root shell on the server (Headlamp's node-shell button, on a node's page)	Not available	It works by creating a pod that mounts the host's filesystem and joins its process and network namespaces. The console is refused that by an admission policy, so the button reports a permission error.

Outside the namespace, and not adjustable¶

The namespace edge is where Full access stops, and that limit is not configurable. Read the danger note above before relying on it as a security boundary: it confines what the console's permissions reach, not what a determined operator at that level can do.

With the CLI	In the console	Why
`kubectl -n cert-manager delete pod …`	Read-only	Changes are confined to the Pixee namespace; other namespaces are visible but fixed.
`kubectl cordon` / `drain` / `label node`	Read-only	Node-level changes affect the whole machine, not just Pixee.
`kubectl edit crd` / `clusterrole` / `namespace` / `storageclass`	Read-only	Cluster-wide objects are readable but not editable.

Not features of the tool¶

No permission change makes these work:

With the CLI	In the console	Instead
`helm status` / `list` / `history` / `rollback`	Not available	Seeing Helm Release State below.
`kubectl port-forward`	Not available	Only the Headlamp desktop app has this, not an in-cluster deployment.
`kubectl cp`	Not available	Copy through a pod shell at Full access instead.
`kubectl top pod` / `top node`	Shows nothing	Embedded installs run no metrics-server. Use the Metrics UI at `/o11y/metrics`.
`kubectl diff` / `--dry-run=server`	Not available	Edits apply when you save, with no preview step.
`kubectl port-forward` — see above	Not available	Desktop-app only upstream, whatever the permissions.

One rough edge: bulk actions in list views¶

Almost every control in the console checks your permissions before it appears, so an action you cannot perform is simply not offered, and an object you may view but not edit opens its YAML in read-only mode rather than showing a Save button that fails.

The multi-select actions in list views are the exception. Select several rows and the Delete, Restart and Scale buttons appear regardless of what you are allowed to do, then fail with a permission error on the objects you cannot touch. Nothing is harmed and nothing is half-applied per object, but the error is confusing if you are not expecting it.

Use the individual object's page for anything the list-view bulk action refuses. That path is permission-checked and will only offer what you can actually do.

Anything else: a pod with `kubectl` in it¶

For a gap with no button, such as a delete with a flag the UI does not offer, a SQL query, or shaping output with -o jsonpath, Full access can run the real thing. Create this pod from the + Create button, then open its Terminal tab:

apiVersion: v1
kind: Pod
metadata:
  name: kubectl-scratch
  namespace: <your Pixee namespace>
spec:
  restartPolicy: Never
  serviceAccountName: pixee-enterprise-server-cluster-ui
  containers:
    - name: shell
      image: <the pixee-utility-alpine image this install already runs>
      command: ["sleep", "infinity"]
  imagePullSecrets:
    - name: pixee-registry

It carries kubectl, psql, curl and jq. The serviceAccountName line is the important one: it gives the pod the console's own permissions, so kubectl inside it can do exactly what the console can do and no more. It still cannot read Secrets in another namespace, and it still cannot create a pod that reaches the host.

Delete the pod when you are finished; nothing removes it for you.

What does work¶

For balance, the things people most often assume are missing are not: reading any object's full YAML including annotations and labels, tailing pod logs (including a crashed container's previous logs), reading events, editing a resource's YAML in place, restarting and scaling a workload, rolling one back to its previous revision, deleting one so its controller recreates it, and evicting a pod, which, unlike deleting it, respects any disruption budget the workload has. At Full access you can also attach a debug container to a running pod, which is how you get a shell with tools in it alongside a container that has none, such as a distroless image or one that has crashed.

Access Levels¶

Level	What it allows
Disabled	The console is not deployed at all. This is the default.
Read-only	Inspect any object in the cluster and read pod logs. No changes, and no credentials.
Full access	Administrator of the Pixee namespace: edit, create and delete anything there, open a shell in any pod, and read credentials. Nodes, other namespaces and cluster-wide objects stay read-only.

There are two levels rather than a graded ladder because there were only ever two things to offer. Read-only is an enforceable boundary. Anything able to write in the namespace can reach everything in it, so subdividing the write side described a distinction that did not exist. A level that withheld the pod shell still reached every credential by other means, and the narrower grant mostly produced Headlamp controls that were greyed out for no defensible reason.

Read-only is the right choice for day-to-day use. Raise it when you have a specific change to make, then lower it again.

Full access is administrator access

It can open a shell inside any pod, including the database, and commands typed there are not recorded anywhere. It can reveal every credential the deployment holds. Anyone who can sign in with SSO has all of it.

Grant it the way you would grant a shell on the server: to people you would trust with one, for as long as the task takes.

Enabling the Console¶

Embedded ClusterHelm Deployment

Navigate to the admin console
Select the Config tab
Go to the Observability section
Under Cluster Console, set Cluster console access to the level you want
Save and redeploy the application

If the Cluster Console section does not appear, your license does not include this feature. Contact Pixee Support.

The console lives in the pixee-enterprise-server-observability chart. Add the following to that chart's values.yaml:

clusterUi:
  enabled: true
  # readonly | full
  accessLevel: readonly

# Both are required for the console to be reachable.
eg:
  enabled: true
authentik:
  enabled: true

Authentik is required, not optional: the forward-auth policy in front of the console is the only thing authenticating visitors, and the console signs every visitor in as one shared Kubernetes identity. Installing with clusterUi.enabled: true and authentik.enabled: false fails with an explanatory error rather than deploying an unauthenticated console. Envoy Gateway is what serves the route; without it the workload runs but nothing is published.

Finding It¶

Once enabled, the console is at /o11y/cluster/ on your Pixee Enterprise Server domain, and it is linked from the observability landing page at /o11y. Signing in uses your normal SSO credentials.

Who Can Open It¶

Only members of the pixee-admins group in Authentik. Signing in to the platform is not enough. The Authentik outpost checks group membership before a request ever reaches the console, and the same restriction covers the metrics, logs and traces interfaces alongside it.

Grant or revoke access by changing that group's membership in Authentik. Nothing needs redeploying.

That group is the only lever, and it is worth understanding why. Every visitor who clears the door shares one set of Kubernetes permissions, the access level you chose above. The console does not map individual identities onto Kubernetes permissions, so it cannot give one member of the group more than another. Deciding who may use it is entirely a question of who is in pixee-admins.

Seeing Helm Release State¶

If you have no shell on the server you also have no helm CLI, so helm status and helm list are not available to you, and, as above, the console cannot show them either.

Every support bundle now carries that state instead. Generate one from the Support Bundles section of the admin console and look in helm/kotsadm.json, which lists each of the deployment's Helm releases with its chart version, app version, current revision, and the status and timestamp of every revision in its history. That covers what helm status and helm list would have told you. Release values are deliberately excluded, because they carry the credentials the charts are configured with.

Support Bundles¶

The console's own logs, its Deployment, and the exact permissions your chosen access level granted are all captured in a support bundle, so Pixee Support can see what was enabled without asking you to describe it.