Skip to main content
Version: v3

ClusterApi

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

Requests are scoped to the cluster currently being viewed. For global Rancher resources (Users, Projects, Settings, etc.) use the Management API instead - see MgmtApi.

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

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();

// Substitute `resources.cluster` for the API you want, e.g. `resources.mgmt` for management resources
const api = resources.cluster;

const configMap = await api.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();

// Substitute `resources.cluster` for the API you want, e.g. `resources.mgmt` for management resources
const api = resources.cluster;

await api.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();

// Substitute `resources.cluster` for the API you want, e.g. `resources.mgmt` for management resources
const api = resources.cluster;

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

// Cluster-scoped resource - ID is just the name
const node = await api.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();

// Substitute `resources.cluster` for the API you want, e.g. `resources.mgmt` for management resources
const api = resources.cluster;

const allPods = await api.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();

// Substitute `resources.cluster` for the API you want, e.g. `resources.mgmt` for management resources
const api = resources.cluster;

const pods = await api.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();

// Substitute `resources.cluster` for the API you want, e.g. `resources.mgmt` for management resources
const api = resources.cluster;

const pods = await api.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();

// Substitute `resources.cluster` for the API you want, e.g. `resources.mgmt` for management resources
const api = resources.cluster;

const pods = await api.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();

// Substitute `resources.cluster` for the API you want, e.g. `resources.mgmt` for management resources
const api = resources.cluster;

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

const result = await api.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.

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.

Strategic merge patch is attempted first, which merges list fields by key. Resources that reject it (CRDs, which is most of Rancher) are retried with merge patch, which replaces list fields instead.

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();

// Substitute `resources.cluster` for the API you want, e.g. `resources.mgmt` for management resources
const api = resources.cluster;

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