Cluster Access

Grant teammates scoped, SSO-backed kubectl access to a cluster - without distributing static kubeconfigs or cluster credentials.

Cluster Access lets organisation admins grant teammates scoped Kubernetes access to a cluster. Instead of handing out long-lived kubeconfigs or shared service-account tokens, you create a grant that maps an Ankra user to a role and scope. Ankra reconciles that grant into native Kubernetes RBAC on the cluster, and the user reaches the cluster through Ankra’s authenticated kubeconfig and API proxy.

Access is SSO-backed and ephemeral. Members authenticate as themselves (via ankra login or the portal), and the credentials their kubeconfig uses are short-lived tokens minted on demand - there are no static cluster secrets to leak or rotate.

---

How it works

1. An admin grants a member a role at a chosen scope.
2. Ankra reconciles the grant into Kubernetes RBAC (a RoleBinding or ClusterRoleBinding) on the cluster.
3. The member adds an Ankra context to their kubeconfig and runs kubectl - every request flows through the Ankra proxy and is bound by the RBAC the grant created.

---

Roles and scopes

Each grant combines a role with a scope:

Role	Kubernetes capability
view	Read-only access
edit	Read/write to most namespaced resources
admin	Full control within the scope, including RBAC
cluster-admin	Full control of the cluster

Scope	Applies to
cluster	The whole cluster (cluster-wide binding)
namespace	A single namespace (the namespace field is required and must be a valid DNS-1123 label)

Grant the narrowest role and scope that gets the job done - for example view on a single namespace for someone triaging one team’s workloads, rather than cluster-admin.

---

Managing access

Open a cluster and go to its Access view. The page adapts to your role:

• Admins can list organisation members, view existing grants and their reconcile status, create new grants, and revoke them.
• Members see whether they have access and can generate a kubeconfig if they do.

A grant is required to mint tokens and reach the cluster for every user, including organisation admins. Being able to manage access does not itself include kubectl access - admins who want to use kubectl must create a grant for themselves too.

The one exception is whoever created or imported the cluster: they are given a cluster-scoped cluster-admin grant at create time, so they can generate a kubeconfig straight away. It is an ordinary grant - it appears in the Access view and in ankra cluster access list, and it can be revoked like any other.

Grant access

1. Pick a member

   Choose an active organisation member by email. The target must already be a member of the organisation.

2. Choose role and scope

   Select a role (view/edit/admin/cluster-admin) and a scope (whole cluster or a single namespace).

3. Create the grant

   Ankra records the grant and begins reconciling it onto the cluster.

4. Wait for the grant to apply

   The grant starts as pending while the RBAC is applied on the cluster. A token can be minted as soon as the grant exists, but kubectl returns Forbidden until the status reaches applied - check it in the Access view or with ankra cluster access list.

5. Share the kubeconfig step

   The member adds an Ankra context to their kubeconfig - see Accessing clusters with kubectl. For a namespace-scoped grant, they should pass --namespace with the granted namespace.

Reconcile status

Because RBAC is applied on the cluster by the agent, each grant carries a reconcile status:

Status	Meaning
pending	The grant has been created and is waiting to be applied
applied	RBAC is live on the cluster
failed	Reconcile failed - see the grant’s error detail
cluster_offline	The cluster is offline; the grant will apply once it reconnects

Revoke access

Delete an individual grant to remove that binding, or use revoke all to clear every grant and invalidate any tokens minted for the cluster in one action.

From the CLI

Admins can manage grants from the Ankra CLI (v0.4.0 or later) instead of the portal:

# List grants and their reconcile status
ankra cluster access list --cluster my-cluster

# Grant a member access (cluster-wide view by default)
ankra cluster access grant [e-mail] --role view

# Limit a grant to one namespace
ankra cluster access grant [e-mail] --role edit --namespace staging

# Revoke a single grant by ID, or every grant a member has on the cluster
ankra cluster access revoke [e-mail]

---

Availability

• Cluster Access requires the access gateway to be enabled for your deployment. When it is not enabled, the access endpoints return 404 and the Access view reports the feature as unavailable.
• Sandbox clusters do not support Cluster Access.

---

API

All endpoints are organisation-scoped and operate on a specific cluster. Managing grants requires organisation admin; write operations require a CSRF header for browser-originated requests.

The table below lists the session-authenticated portal endpoints. The CLI and API tokens use token-authenticated equivalents under /api/v1/clusters/{cluster_id}/... (/access/grants for managing grants, /k8s-token and /kubeconfig for consuming access) - see the kubectl access API table.

Method	Path	Purpose
GET	/org/clusters/{cluster_id}/access/capabilities	Whether access is enabled, and if the caller can manage / already has access
GET	/org/clusters/{cluster_id}/access/members	Organisation members eligible for a grant
GET	/org/clusters/{cluster_id}/access/grants	List existing grants and their reconcile status
POST	/org/clusters/{cluster_id}/access/grants	Create a grant
DELETE	/org/clusters/{cluster_id}/access/grants/{grant_id}	Delete a grant
POST	/org/clusters/{cluster_id}/access/kubeconfig	Generate a kubeconfig for the caller
POST	/org/clusters/{cluster_id}/access/revoke-all	Revoke all grants and tokens for the cluster

See Accessing clusters with kubectl for how members consume their access, and the API Reference for full schemas.