Skip to main content
Version: v3

ClusterApi

Provides access to the Cluster API which can be used for managing cluster resources in Rancher UI

Example​

import { useResources, K8S } from '@shell/apis';

// Cluster-scoped resources (current cluster context)
const pod = await resources.cluster.find(K8S.POD, 'default/my-pod-123');

// Management/global resources
const user = await resources.mgmt.find(K8S.USER, 'u-xyz789');

Methods​

find()​

find<T>(
   resourceType, 
   resourceId, 
options?): Promise<T>;

Finds a specific resource by its type and ID.

Type Parameters​

T​

T = SteveGetResponse

The type of the resource (defaults to SteveGetResponse)

Parameters​

resourceType​

any

The type of the resource to find (use K8S constant). See also ResourceType.

resourceId​

string

The unique identifier of the resource to find. If the resource is namespaced, this should be in the format namespace/name.

options?​

FindMethodOptions

Optional find arguments

Returns​

Promise<T>

The found resource item or null if not found.

Example​

import { useResources, K8S } from '@shell/apis';

const resources = useResources();

// Namespaced resource - ID must be in "namespace/name" format
const pod = await resources.cluster.find(K8S.POD, 'default/my-pod-123');

// Cluster-scoped resource - ID is just the name
const node = await resources.cluster.find(K8S.NODE, 'worker-1');

findAll()​

findAll<T>(resourceType, options?): Promise<T[]>;

Fetches all resources of a specific type with advanced options. This method provides additional capabilities like incremental loading and namespace filtering.

Type Parameters​

T​

T = SteveListResponse<SteveGetResponse>

The type of the resources (defaults to SteveListResponse)

Parameters​

resourceType​

any

The type of the resources to find (use K8S constant). See also ResourceType.

options?​

FindAllMethodOptions

Optional advanced fetch options (incremental loading, namespace filtering, etc.)

Returns​

Promise<T[]>

An array of resource items or an empty array if none are found.

Example​

import { useResources, K8S } from '@shell/apis';

const resources = useResources();
const allPods = await resources.cluster.findAll(K8S.POD, {
  namespaced: ['default', 'kube-system']
});

findFiltered()​

Call Signature​

findFiltered<T>(resourceType, options): Promise<FindFilteredPageResponse<T>>;

Finds resources using pagination mode with server-side filtering, sorting, and pagination.

Requires ui-sql-cache to be enabled.

Type Parameters​
T​

T = SteveListResponse<SteveGetResponse>

The type of the resources (defaults to SteveListResponse)

Parameters​
resourceType​

any

The type of the resources to find (use K8S constant). See also ResourceType.

options​

FindFilteredPageOptions

Pagination options with server-side filtering and sorting via the Steve API's pagination cache. See FindFilteredPageOptions.

Returns​

Promise<FindFilteredPageResponse<T>>

Response containing resource items (may be transient if requested, otherwise cached array).

Throws​

Error if pagination mode is requested but ui-sql-cache is not enabled.

Example​
import { useResources, K8S } from '@shell/apis';

const resources = useResources();

const pods = await resources.cluster.findFiltered(K8S.POD, {
  pagination: {
    page: 1,
    pageSize: 10,
    filters: [],
    sort: []
  }
});

Call Signature​

findFiltered<T>(resourceType, options): Promise<FindFilteredLabelSelectorResponse<T>>;

Finds resources using label selector matching.

Filters resources by Kubernetes labels. The store automatically handles pagination:

  • If ui-sql-cache is enabled: uses server-side pagination
  • Otherwise: uses native Kubernetes API pagination
Type Parameters​
T​

T = SteveListResponse<SteveGetResponse>

The type of the resources (defaults to SteveListResponse)

Parameters​
resourceType​

any

The type of the resources to find (use K8S constant). See also ResourceType.

options​

FindFilteredLabelSelectorOptions

Label selector options for filtering. See FindFilteredLabelSelectorOptions.

Returns​

Promise<FindFilteredLabelSelectorResponse<T>>

Response containing resource items (may be transient if requested, otherwise cached array).

Example​
import { useResources, K8S } from '@shell/apis';

const resources = useResources();

const pods = await resources.cluster.findFiltered(K8S.POD, {
  labelSelector: { matchLabels: { type: 'my-type' } }
});