Xeonr Developer Docs
API Specificationcontainers.api.v1.ClusterService

List Clusters

POST
/containers.api.v1.ClusterService/ListClusters

Lists the clusters visible to the caller, ordered by display name: those owned by a team they are in, those granting such a team, and every GLOBAL cluster (all of them for a platform admin; for a namespace API key, the clusters its namespaces are placed on). With team set, only the clusters that team owns or may place a namespace on; a team the caller is not in is NotFound. limit 0 means 50 and is at most 500; cursor is opaque, from next_cursor.

Access: any authenticated caller; results are filtered to what the caller can see.

Authorization

BearerAuth
AuthorizationBearer <token>

A namespace-scoped API key (cpk_…) for machines, or a Xeonr Auth OIDC token for humans. The key's namespace and role are pinned server-side.

In: header

Header Parameters

Connect-Protocol-Version?number

Define the version of the Connect protocol

Connect-Timeout-Ms?number

Define the timeout, in ms

Request Body

application/json

team?string

Restrict to the clusters this team owns or may place a namespace on.

Match^(urn:xeonr:auth:team:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})?$
Lengthlength <= 255
cursor?string
Lengthlength <= 512
limit?integer
Rangevalue <= 500
[key: string]?never

Response Body

application/json

application/json

curl -X POST "https://containers.xeonr.io/containers.api.v1.ClusterService/ListClusters" \  -H "Connect-Protocol-Version: 1" \  -H "Connect-Timeout-Ms: 1000" \  -H "Content-Type: application/json" \  -d '{}'
{
  "clusters": [
    {
      "clusterId": "string",
      "displayName": "string",
      "ownerTeam": "string",
      "visibility": "CLUSTER_VISIBILITY_UNSPECIFIED",
      "grants": [
        {
          "team": "string",
          "quotaCpuMillis": 0,
          "quotaMemoryMb": 0,
          "quotaMaxPods": 0,
          "quotaStorageMb": 0,
          "quotaMaxVolumes": 0
        }
      ],
      "default": true,
      "allowRunc": true,
      "state": "CLUSTER_STATE_UNSPECIFIED",
      "lastSeen": "2023-01-15T01:30:15.01Z",
      "operatorVersion": "string",
      "capabilities": {
        "gvisor": true,
        "cpCsi": true,
        "previewIngress": true,
        "appIngress": true,
        "previewDomain": "string",
        "appDomain": "string"
      },
      "labels": {
        "property1": "string",
        "property2": "string"
      },
      "createdAt": "2023-01-15T01:30:15.01Z",
      "capacity": {
        "observedAt": "2023-01-15T01:30:15.01Z",
        "nodes": [
          {
            "name": "string",
            "ready": true,
            "allocatableCpuMillis": "string",
            "allocatableMemoryMb": "string",
            "allocatablePods": 0,
            "requestedCpuMillis": "string",
            "requestedMemoryMb": "string",
            "pods": 0,
            "volumeDiskFreeMb": "string"
          }
        ],
        "installCap": {
          "cpuMillis": "string",
          "memoryMb": "string",
          "pods": 0,
          "storageMb": "string",
          "volumes": 0
        },
        "installRequested": {
          "cpuMillis": "string",
          "memoryMb": "string",
          "pods": 0,
          "storageMb": "string",
          "volumes": 0
        }
      },
      "conditions": [
        {
          "type": "TYPE_UNSPECIFIED",
          "message": "string",
          "since": "2023-01-15T01:30:15.01Z",
          "pods": [
            "string"
          ]
        }
      ],
      "archiveIntervalSec": 0,
      "archivedBytes": "string"
    }
  ],
  "nextCursor": "string"
}
{
  "code": "not_found",
  "message": "string",
  "details": [
    {
      "type": "string",
      "value": "string",
      "debug": {}
    }
  ]
}

Get Cluster POST

Returns a cluster record. A cluster the caller cannot see is reported as NotFound. **Access:** a member of the owner team or of a team holding a grant, any caller for a GLOBAL cluster, a namespace API key for the cluster its namespace is placed on, or a platform admin.

Update Cluster POST

Updates the fields named in `update_mask` and nothing else; an empty mask is InvalidArgument. The owner team's admins may change `display_name`, `labels`, `grants` and switch `visibility` between PRIVATE and SHARED. Setting `visibility` to GLOBAL, `default`, `allow_runc` and the everyone-grant (a grant with an empty `team`) are platform-admin-only; naming them in the mask otherwise is PermissionDenied. At most one cluster is `default`, and it must be GLOBAL. `archive_interval_sec` (how often mounted volumes are archived; 0 disables, unset in the mask restores the 6-hour default) is the owner team's on its own cluster and platform-admin-only on a GLOBAL one. **Access:** admin of the owner team, or a platform admin. Other callers get NotFound.