ResourcesApi
Base interface for all resource API operations.
Provides type-safe methods for interacting with Kubernetes and Rancher resources. Used by both cluster-scoped and management-scoped APIs, and can be extended by custom store implementations (e.g. Harvester, Epinio).
Example
import { useResources, K8S } from '@shell/apis';
const resources = useResources();
const deployment = await resources.cluster.find(K8S.DEPLOYMENT, 'default/my-app');
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
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
any
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
any
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?
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
any
The type of the resources to find (examples in K8S). See also ResourceType.
options?
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
Requires ui-sql-cache to be enabled.
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
any
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
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, {
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.
Requires ui-sql-cache to be enabled.
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
any
The type of the resources to find (examples in K8S). See also ResourceType.
options
Pagination options with server-side filtering and sorting via the Steve API's pagination cache. See FindFilteredPageOptions.
Returns
Promise<I[]>
Response containing resource items
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, I>(resourceType, options): Promise<I>;
Finds resources using label selector matching.
Filters resources by Kubernetes labels. The store automatically handles pagination:
- If
ui-sql-cacheis enabled: uses server-side pagination - Otherwise: uses native Kubernetes API pagination
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
any
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
any
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
any
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' }
});