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​

create()​

create<T, I>(data): Promise<I>;

Creates a new resource.

The data object must include a type property identifying the resource type. This is a raw HTTP operation — it does not check permissions or update the store cache.

Type Parameters​

T​

T = Record<string, any>

Your specific resource type. Rancher will supplement the response with additional properties and methods

I​

I = SteveResource<T>

An override for the response type. By default this uses T and supplements the response, or by supplying a value ignores T

Parameters​

data​

CreateResourceData

The resource data to create. Must include a type property (examples in K8S). See also CreateResourceData.

Returns​

Promise<I>

The created resource instance.

Example​

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

const resources = useResources();

const configMap = await resources.cluster.create({
  type:     K8S.CONFIG_MAP,
  metadata: { name: 'my-config', namespace: 'default' },
  data:     { key: 'value' }
});

delete()​

delete(resourceType, resourceId): Promise<void>;

Deletes a resource by type and ID using HTTP DELETE.

This is a raw HTTP operation — it does not check permissions or update the store cache.

Parameters​

resourceType​

string

The type of the resource (examples in K8S). See also ResourceType.

resourceId​

string

The unique identifier. If namespaced, use namespace/name format.

Returns​

Promise<void>

Example​

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

const resources = useResources();

await resources.cluster.delete(K8S.CONFIG_MAP, 'default/my-config');

find()​

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

Finds a specific resource by its type and ID.

Type Parameters​

T​

T = Record<string, any>

Your specific resource type. Rancher will supplement the response with additional properties and methods

I​

I = ResourceInstance<T>

An override for the response type. By default this uses T and supplements the response, or by supplying a value ignores T

Parameters​

resourceType​

string

The type of the resource to find (examples in K8S). 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<I>

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, I>(resourceType, options?): Promise<I[]>;

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 = Record<string, any>

Your specific resource type. Rancher will supplement the response with additional properties and methods

I​

I = ResourceInstance<T>

An override for the response type. By default this uses T and supplements the response, or by supplying a value ignores T

Parameters​

resourceType​

string

The type of the resources to find (examples in K8S). See also ResourceType.

options?​

FindAllMethodOptions

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

Returns​

Promise<I[]>

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, I>(resourceType, options): Promise<I>;

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

The response is not cached

Type Parameters​
T​

T = Record<string, any>

Your specific resource type. Rancher will supplement the response with additional properties and methods

I​

I = ActionFindPageTransientResponse<ResourceInstance<T>>

An override for the response type. By default this uses T and supplements the response, or by supplying a value ignores T

Parameters​
resourceType​

string

The type of the resources to find (examples in K8S). See also ResourceType.

options​

FindFilteredPageOptionsTransient

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

Returns​

Promise<I>

Response containing resource items

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

const resources = useResources();

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

Call Signature​

findFiltered<T, I>(resourceType, options): Promise<I[]>;

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

The response is cached.

Type Parameters​
T​

T = Record<string, any>

Your specific resource type. Rancher will supplement the response with additional properties and methods

I​

I = ResourceInstance<T>

An override for the response type. By default this uses T and supplements the response, or by supplying a value ignores T

Parameters​
resourceType​

string

The type of the resources to find (examples in K8S). See also ResourceType.

options​

FindFilteredPageOptions

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

Returns​

Promise<I[]>

Response containing resource items

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, I>(resourceType, options): Promise<I>;

Finds resources using label selector matching.

Type Parameters​
T​

T = Record<string, any>

Your specific resource type. Rancher will supplement the response with additional properties and methods

I​

I = FindFilteredLabelSelectorResponse<ResourceInstance<T>>

An override for the response type. By default this uses T and supplements the response, or by supplying a value ignores T

Parameters​
resourceType​

string

The type of the resources to find (examples in K8S). See also ResourceType.

options​

FindFilteredLabelSelectorOptions

Label selector options for filtering. See FindFilteredLabelSelectorOptions.

Returns​

Promise<I>

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' } }
});

replace()​

replace<T, I>(
   resourceType, 
   resourceId, 
data): Promise<I>;

Performs a full replacement update of a resource using HTTP PUT.

Runs cleanForSave on the data before sending. This is a raw HTTP operation — it does not check permissions or update the store cache.

Type Parameters​

T​

T = Record<string, any>

Your specific resource type. Rancher will supplement the response with additional properties and methods

I​

I = SteveResource<T>

An override for the response type. By default this uses T and supplements the response, or by supplying a value ignores T

Parameters​

resourceType​

string

The type of the resource (examples in K8S). See also ResourceType.

resourceId​

string

The unique identifier. If namespaced, use namespace/name format.

data​

Record<string, any>

The complete resource data to send as the replacement.

Returns​

Promise<I>

The server response.

Example​

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

const resources = useResources();
const configMapData = await resources.cluster.find(K8S.CONFIG_MAP, 'default/my-config');
configMapData.someField = { newKey: 'newValue' };

const result = await resources.cluster.replace(K8S.CONFIG_MAP, 'default/my-config', configMapData);

update()​

update<T, I>(
   resourceType, 
   resourceId, 
data): Promise<I>;

Applies a partial update to a resource using HTTP PATCH (merge-patch).

Only the fields provided in data are sent to the server. This is a raw HTTP operation — it does not check permissions or update the store cache.

Type Parameters​

T​

T = Record<string, any>

Your specific resource type. Rancher will supplement the response with additional properties and methods

I​

I = SteveResource<T>

An override for the response type. By default this uses T and supplements the response, or by supplying a value ignores T

Parameters​

resourceType​

string

The type of the resource (examples in K8S). See also ResourceType.

resourceId​

string

The unique identifier. If namespaced, use namespace/name format.

data​

Record<string, any>

An object containing only the fields to update.

Returns​

Promise<I>

The server response.

Example​

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

const resources = useResources();

const result = await resources.cluster.update(K8S.CONFIG_MAP, 'default/my-config', {
  someField: { newKey: 'newValue' }
});