> ## Documentation Index
> Fetch the complete documentation index at: https://docs.andromeda.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cluster API calls are made as a signed-in person with an OIDC bearer token. There are no API keys, and service-account tokens are refused (Business returns 401, Platform returns 403).
> Platform takes the organization as the query parameter businessOrgId on most cluster routes, but as organizationId on /clusters/{clusterId}/ssh-access and /clusters/{clusterId}/kubeconfig.
> The Business API uses snake_case. The Platform API uses camelCase, except /ssh-access and /machines, which use snake_case.
> Business write requests need Idempotency-Key and Audit-Reason headers.
> Storage capacity can grow but cannot shrink, including disk and PVC resizing. Each purchase adds capacity.
> A cluster's storage can be Ceph, WEKA, or both, or NFS on its own. The Ceph quota, the purchased bytes, and Slurm's default 100 GiB shared-volume request are three different quantities.
> Organization permissions cover every cluster the organization owns. A Kubernetes resource grant shares one cluster or namespace, possibly with someone outside the organization, and lets them read that cluster and fetch its kubeconfig. A grant does not give Slurm SSH, Slurm configuration, or organization storage inventory access. Slurm SSH requires organization membership and clusters.ssh.
> The SSH login name is <cluster-id>.<username>. The gateway supports shells, commands, SFTP (including modern scp), and forwarding to loopback ports on the login node. Legacy scp and rsync need their programs on the login node. Remote forwarding and non-loopback destinations are refused.
> Use POST /me/ssh-keys for personal key registration. POST /organizations/{orgID}/ssh-keys is a deprecated alias and requires no membership. Read the preferred shell from GET /me as user.login_shell; update it with PUT /me/login-preferences.
> GET /clusters/{clusterId}/ssh-access returns 200 with ready and reason, even when access is not ready. ready: true does not mean compute nodes or Slurm accounting are ready. To confirm a key or shell change reached a cluster, require observation_current: true and compare ssh_key_set_generation with generation from GET /me/ssh-keys, and shell with user.login_shell from GET /me.
> Adding or removing a login account restarts the cluster's login nodes, Slurm controller, and accounting service, then its compute nodes one at a time; jobs running on a restarting node end. An account is added or removed when a person with an active key gains or loses SSH access, or a person with SSH access registers their first key or revokes their last. Other key changes and shell changes restart no nodes.

# Connect with kubectl

> Fetch a kubeconfig, sign in with kubelogin, and see which Kubernetes role each permission grants.

Every Andromeda cluster runs Kubernetes, including clusters that run Slurm. You fetch a kubeconfig for the cluster
from the Platform API, and `kubectl` signs you in to the cluster's Kubernetes API with your own Andromeda account.

## Before you start

You need:

* The `clusters.kubernetes` organization permission, `clusters.kubernetes.admin` for full control, or a Kubernetes
  resource grant naming this cluster or a namespace in it. See
  [Permissions](/clusters/permissions).
* `ORG_ID` and `CLUSTER_ID` set as in the [quickstart](/clusters/quickstart).
* [`kubectl`](https://kubernetes.io/docs/tasks/tools/).
* The [`kubelogin`](https://github.com/int128/kubelogin) plugin, which adds `kubectl oidc-login`. Install it with
  Homebrew (`brew install kubelogin`) or krew (`kubectl krew install oidc-login`).

Check the plugin is installed:

```sh theme={null}
kubectl oidc-login --help
```

If you are outside the owning organization, use the granted cluster ID and the owning organization ID supplied by
the person sharing it; see [Access to a shared cluster](/clusters/permissions#access-to-a-shared-cluster).

## Fetch the kubeconfig

```sh theme={null}
mkdir -p ~/.kube
andromeda call platform GET "/clusters/$CLUSTER_ID/kubeconfig?organizationId=$ORG_ID" |
  jq -r .kubeconfig > ~/.kube/andromeda-$CLUSTER_ID.yaml
export KUBECONFIG=~/.kube/andromeda-$CLUSTER_ID.yaml
```

The kubeconfig holds no credentials, so you can keep it anywhere and share it with other members of your
organization. Each person signs in as themselves. The cluster, context, and user in it are all named after the
cluster ID.

## Sign in

Run a `kubectl` command allowed by your access. Set `NAMESPACE` to a namespace your grant or organization permission
covers, then list its pods:

```sh theme={null}
kubectl get pods -n "$NAMESPACE"
```

The first time, `kubectl oidc-login` prints a URL and a code. Open the URL, sign in with your Andromeda account, and
enter the code. The plugin caches the token, so later commands run without prompting until it expires.

```text theme={null}
NAME       READY   STATUS    RESTARTS   AGE
trainer    1/1     Running   0          5m
```

## What you can do

| Permission | Kubernetes role |
| - | - |
| `clusters.kubernetes` | [`edit`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) in every namespace: create and change most workload resources, but not roles or role bindings. |
| `clusters.kubernetes.admin` | `cluster-admin`: full control of the cluster. |

Resource grants use `kubernetes.viewer`, `kubernetes.developer`, or `kubernetes.admin`. They map to `view`, `edit`,
and `admin` within a granted namespace; a whole-cluster `kubernetes.admin` grant maps to `cluster-admin`. A custom
role can narrow these further. The kubeconfig itself gives no permissions, so with a namespace grant you may not be
able to list nodes or other namespaces.

If your grant has an expiry, the kubeconfig response includes it as `accessExpiresAt`. When the grant expires or is revoked,
your access ends as the cluster applies the change, even if `kubectl` still holds a cached sign-in.

On a Slurm cluster, Slurm and the components Andromeda manages also run in Kubernetes. Changing them with
`cluster-admin` can break the cluster; use the [Slurm configuration API](/clusters/slurm-configuration) to change Slurm.

## Troubleshooting

| Symptom | Cause and fix |
| - | - |
| The kubeconfig request returns `403` | You have neither an applicable organization permission nor a live Kubernetes resource grant. See [Permissions](/clusters/permissions). |
| The kubeconfig request returns `409` | The cluster is not `active` yet, or its Kubernetes API is not ready. Check [cluster options](/api-reference/platform/clusters#read-cluster-options) and try again. |
| The kubeconfig request returns `503` with `customer_kubernetes_login_not_configured` | This environment does not offer Kubernetes sign-in. Contact [Andromeda Support](/support). |
| `kubectl` says `oidc-login` is not a command | Install kubelogin, above. |
| `kubectl` returns `Forbidden` | The action or namespace is outside your role, your grant expired or was revoked, or the permission update has not reached the cluster yet. |

## Reference

* [`GET /clusters/{clusterId}/kubeconfig`](/api-reference/platform/access#read-a-kubeconfig)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.