@stolostron/multicluster-sdk
Advanced tools
Provides extensions and APIs that dynamic plugins can use to leverage multicluster capabilities provided by Red Hat Advanced Cluster Management.
A React SDK for working with multicluster OpenShift/Kubernetes resources from the OpenShift Console.
This SDK provides extensions and APIs that dynamic plugins can use to leverage multicluster capabilities provided by Red Hat Advanced Cluster Management (RHACM). It aims to provide similar functionality to the dynamic plugin(https://www.npmjs.com/package/@openshift-console/dynamic-plugin-sdk) SDK but for multicluster scenarios.
npm install @stolostron/multicluster-sdk
The multicluster SDK provides components and hooks that enable your dynamic plugins to work with resources across multiple clusters.
Setup depends on your usage scenarios.
useIsFleetAvailable hook to check if support is available. Because it is not permitted to call hooks conditionally, if you are using these multicluster SDK hooks, then you must call them with arguments that render the hook in a disabled state when fleet support is unavailable. Otherwise you will get empty results or errors. See the API Reference for details.REQUIRED_PROVIDER_FLAG constant.// Example code will be added after API stabilization
A fleet version of k8sCreate from
the dynamic plugin SDK that creates a resource on the specified cluster.
The cluster name can be specified in options or the payload, with the value from options taking precedence. If the cluster name is not specified or matches the name of the hub cluster, the implementation from the dynamic plugin SDK is used.
| Function | Type |
|---|---|
fleetK8sCreate | <R extends FleetK8sResourceCommon>(options: FleetK8sCreateUpdateOptions<R>) => Promise<R> |
Parameters:
options: Which are passed as key-value pairs in the mapoptions.cluster: - the cluster on which to create the resourceoptions.model: - Kubernetes modeloptions.data: - payload for the resource to be createdoptions.path: - Appends as subpath if providedoptions.queryParams: - The query parameters to be included in the URL.Returns:
A promise that resolves to the response of the resource created. In case of failure, the promise gets rejected with HTTP error response.
A fleet version of k8sDelete from
the dynamic plugin SDK that deletes resources from the specified cluster, based on the provided model and resource.
The cluster name can be specified in options or the resource, with the value from options taking precedence. If the cluster name is not specified or matches the name of the hub cluster, the implementation from the dynamic plugin SDK is used.
The garbage collection works based on 'Foreground' | 'Background', can be configured with propagationPolicy property in provided model or passed in json.
| Function | Type |
|---|---|
fleetK8sDelete | <R extends FleetK8sResourceCommon>(options: FleetK8sDeleteOptions<R>) => Promise<R> |
Parameters:
options: which are passed as key-value pair in the map.options.cluster: - the cluster from which to delete the resourceoptions.model: - Kubernetes modeloptions.resource: - The resource to be deleted.options.path: - Appends as subpath if provided.options.queryParams: - The query parameters to be included in the URL.options.requestInit: - The fetch init object to use. This can have request headers, method, redirect, etc. See more https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules_typedoc_node_modules_typescript_lib_lib_dom_d_.requestinit.htmloptions.json: - Can control garbage collection of resources explicitly if provided else will default to model's propagationPolicy.Returns:
A promise that resolves to the response of kind Status. In case of failure promise gets rejected with HTTP error response.
Examples:
{ kind: 'DeleteOptions', apiVersion: 'v1', propagationPolicy }
A fleet version of k8sGet from
the dynamic plugin SDK that fetches a resource from the specified cluster, based on the provided options.
If the cluster name is not specified or matches the name of the hub cluster, the implementation from the dynamic plugin SDK is used.
If the name is provided it returns resource, else it returns all the resources matching the model.
| Function | Type |
|---|---|
fleetK8sGet | <R extends FleetK8sResourceCommon>(options: FleetK8sGetOptions) => Promise<R> |
Parameters:
options: Which are passed as key-value pairs in the mapoptions.cluster: - the cluster from which to fetch the resourceoptions.model: - Kubernetes modeloptions.name: - The name of the resource, if not provided then it looks for all the resources matching the model.options.ns: - The namespace to look into, should not be specified for cluster-scoped resources.options.path: - Appends as subpath if providedoptions.queryParams: - The query parameters to be included in the URL.options.requestInit: - The fetch init object to use. This can have request headers, method, redirect, etc. See more https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules_typedoc_node_modules_typescript_lib_lib_dom_d_.requestinit.htmlReturns:
A promise that resolves to the response as JSON object with a resource if the name is provided, else it returns all the resources matching the model. In case of failure, the promise gets rejected with HTTP error response.
A fleet version of k8sList from
the dynamic plugin SDK that lists the resources as an array in the specified cluster, based on the provided options.
If the cluster name is not specified or matches the name of the hub cluster, the implementation from the dynamic plugin SDK is used.
| Function | Type |
|---|---|
fleetK8sList | <R extends FleetK8sResourceCommon>(options: FleetK8sListOptions) => Promise<R[]> |
Parameters:
options: Which are passed as key-value pairs in the map.options.cluster: - the cluster from which to list the resourcesoptions.model: - Kubernetes modeloptions.queryParams: - The query parameters to be included in the URL. It can also pass label selectors by using the labelSelector key.options.requestInit: - The fetch init object to use. This can have request headers, method, redirect, and so forth. See more https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules_typedoc_node_modules_typescript_lib_lib_dom_d_.requestinit.htmlReturns:
A promise that resolves to the response
A fleet version of k8sListItems from
the dynamic plugin SDK that lists the resources as an array in the specified cluster, based on the provided options.
If the cluster name is not specified or matches the name of the hub cluster, the implementation from the dynamic plugin SDK is used.
| Function | Type |
|---|---|
fleetK8sListItems | <R extends FleetK8sResourceCommon>(options: FleetK8sListOptions) => Promise<R[]> |
Parameters:
options: Which are passed as key-value pairs in the map.options.cluster: - the cluster from which to list the resourcesoptions.model: - Kubernetes modeloptions.queryParams: - The query parameters to be included in the URL. It can also pass label selectors by using the labelSelector key.options.requestInit: - The fetch init object to use. This can have request headers, method, redirect, and so forth. See more https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules_typedoc_node_modules_typescript_lib_lib_dom_d_.requestinit.htmlReturns:
A promise that resolves to the response
A fleet version of k8sPatch from
the dynamic plugin SDK that patches any resource on the specified cluster, based on the provided options.
The cluster name can be specified in options or the resource, with the value from options taking precedence. If the cluster name is not specified or matches the name of the hub cluster, the implementation from the dynamic plugin SDK is used.
When a client needs to perform the partial update, the client can use fleetK8sPatch.
Alternatively, the client can use fleetK8sUpdate to replace an existing resource entirely.
See more https://datatracker.ietf.org/doc/html/rfc6902
| Function | Type |
|---|---|
fleetK8sPatch | <R extends FleetK8sResourceCommon>(options: FleetK8sPatchOptions<R>) => Promise<R> |
Parameters:
options: Which are passed as key-value pairs in the map.options.cluster: - the cluster on which to patch the resourceoptions.model: - Kubernetes modeloptions.resource: - The resource to be patched.options.data: - Only the data to be patched on existing resource with the operation, path, and value.options.path: - Appends as subpath if provided.options.queryParams: - The query parameters to be included in the URL.Returns:
A promise that resolves to the response of the resource patched. In case of failure promise gets rejected with HTTP error response.
A fleet version of k8sPatch from
the dynamic plugin SDK that updates the entire resource on the specified cluster, based on the provided options.
The cluster name can be specified in options or the payload, with the value from options taking precedence. If the cluster name is not specified or matches the name of the hub cluster, the implementation from the dynamic plugin SDK is used.
When a client needs to replace an existing resource entirely, the client can use fleetK8sUpdate.
Alternatively, the client can use fleetK8sPatch to perform the partial update.
| Function | Type |
|---|---|
fleetK8sUpdate | <R extends FleetK8sResourceCommon>(options: FleetK8sCreateUpdateOptions<R>) => Promise<R> |
Parameters:
options: which are passed as key-value pair in the mapoptions.cluster: - the cluster on which to update the resourceoptions.model: - Kubernetes modeloptions.data: - payload for the Kubernetes resource to be updatedoptions.ns: - namespace to look into, it should not be specified for cluster-scoped resources.options.name: - resource name to be updated.options.path: - appends as subpath if provided.options.queryParams: - The query parameters to be included in the URL.Returns:
A promise that resolves to the response of the resource updated. In case of failure promise gets rejected with HTTP error response.
A multicluster-aware ResourceEventStream component that displays real-time Kubernetes events for resources on managed clusters. Provides equivalent functionality to the OpenShift console's ResourceEventStream for resources on managed clusters.
For managed cluster resources, this component establishes a websocket connection to stream events from the specified cluster. For hub cluster resources or when no cluster is specified, it falls back to the standard OpenShift console ResourceEventStream component.
| Function | Type |
|---|---|
FleetResourceEventStream | FC<FleetResourceEventStreamProps> |
Parameters:
props: - Component propertiesprops.resource: - The Kubernetes resource to show events for.
Must include standard K8s metadata (name, namespace, uid, kind) and an optional cluster property.Returns:
A rendered event stream component showing real-time Kubernetes events
Examples:
// Display events for a resource on a managed cluster <FleetResourceEventStream resource={{ metadata: { name: 'my-pod', namespace: 'default', uid: '123' }, kind: 'Pod', cluster: 'managed-cluster-1' }} /> // Display events for a hub cluster resource (falls back to OpenShift console component) <FleetResourceEventStream resource={{ metadata: { name: 'my-deployment', namespace: 'openshift-gitops', uid: '456' }, kind: 'Deployment' // No cluster property - uses hub cluster }} /> // Display events for a cluster-scoped resource on a managed cluster <FleetResourceEventStream resource={{ metadata: { name: 'my-node', uid: '789' }, kind: 'Node', cluster: 'edge-cluster-2' }} />
Enhanced ResourceLink component for ACM fleet environments.
Unlike the standard OpenShift ResourceLink which always links to the OpenShift console, FleetResourceLink provides intelligent routing based on cluster context:
This prevents users from having to jump between different consoles when managing multi-cluster resources.
| Function | Type |
|---|---|
FleetResourceLink | React.FC<FleetResourceLinkProps> |
Parameters:
props: - FleetResourceLinkProps extending ResourceLinkProps with cluster informationprops.cluster: - the target cluster name for the resourceprops.groupVersionKind: - K8s GroupVersionKind for the resourceprops.name: - the resource nameprops.namespace: - the resource namespace (required for namespaced resources)props.displayName: - optional display name overrideprops.className: - additional CSS classesprops.inline: - whether to display inlineprops.hideIcon: - whether to hide the resource iconprops.children: - additional content to renderExamples:
// Hub cluster VirtualMachine - routes to ACM VM page via extension system
<FleetResourceLink
name="my-vm"
namespace="default"
groupVersionKind={{ group: 'kubevirt.io', version: 'v1', kind: 'VirtualMachine' }}
/>
// Managed cluster VirtualMachine - routes to ACM search results
<FleetResourceLink
name="remote-vm"
namespace="default"
cluster="prod-cluster"
groupVersionKind={{ group: 'kubevirt.io', version: 'v1', kind: 'VirtualMachine' }}
/>
// ManagedCluster resource (lives on hub) - cluster prop omitted
<FleetResourceLink
name="prod-cluster"
groupVersionKind={{ group: 'cluster.open-cluster-management.io', version: 'v1', kind: 'ManagedCluster' }}
/>
Function that provides the k8s API path for the fleet.
| Function | Type |
|---|---|
getFleetK8sAPIPath | (cluster?: string or undefined) => Promise<string> |
Parameters:
cluster: - The cluster name.Returns:
The k8s API path for the fleet.
Hook that provides information about user access to a given resource.
| Function | Type |
|---|---|
useFleetAccessReview | ({ group, resource, subresource, verb, name, namespace, cluster, }: FleetAccessReviewResourceAttributes) => [boolean, boolean] |
Parameters:
resourceAttributes: resource attributes for access reviewresourceAttributes.group: the name of the group to check access forresourceAttributes.resource: the name of the resource to check access forresourceAttributes.subresource: the name of the subresource to check access forresourceAttributes.verb: the "action" to perform; one of 'create' | 'get' | 'list' | 'update' | 'patch' | 'delete' | 'deletecollection' | 'watch' | 'impersonate'resourceAttributes.name: the nameresourceAttributes.namespace: the namespaceresourceAttributes.cluster: the cluster name to find the resource inReturns:
Array with isAllowed and loading values.
Hook that returns names of managed clusters with optional filtering by cluster proxy addon and availability status.
This hook watches ManagedCluster resources and by default filters them to only include clusters
that have both the label feature.open-cluster-management.io/addon-cluster-proxy: available AND
the condition ManagedClusterConditionAvailable with status True.
| Function | Type |
|---|---|
useFleetClusterNames | (returnAllClusters?: boolean) => [string[], boolean, any] |
Parameters:
returnAllClusters: - Optional boolean to return all cluster names regardless of labels and conditions.
Defaults to false. When false (default), only returns clusters with the
'feature.open-cluster-management.io/addon-cluster-proxy: available' label AND
'ManagedClusterConditionAvailable' status: 'True'.
When true, returns all cluster names regardless of labels and conditions.Returns:
A tuple containing:
Examples:
// Get only clusters with cluster proxy addon available AND ManagedClusterConditionAvailable: 'True' (default behavior)
const [availableClusterNames, loaded, error] = useFleetClusterNames()
// Get all cluster names regardless of labels and conditions
const [allClusterNames, loaded, error] = useFleetClusterNames(true)
// Explicitly filter by cluster proxy addon and availability (same as default)
const [filteredClusterNames, loaded, error] = useFleetClusterNames(false)
if (!loaded) {
return <Loading />
}
if (error) {
return <ErrorState error={error} />
}
return (
<div>
{availableClusterNames.map(name => (
<div key={name}>{name}</div>
))}
</div>
)
Hook that provides the k8s API path for the fleet.
| Function | Type |
|---|---|
useFleetK8sAPIPath | (cluster?: string or undefined) => [k8sAPIPath: string or undefined, loaded: boolean, error: Error or undefined] |
Parameters:
cluster: - The cluster name.Returns:
Array with k8sAPIPath, loaded and error values.
A hook for watching Kubernetes resources with support for multi-cluster environments.
It is equivalent to the useK8sWatchResource
hook from the OpenShift Console Dynamic Plugin SDK
but allows you to retrieve data from any cluster managed by Red Hat Advanced Cluster Management.
It automatically detects the hub cluster and handles resource watching on both hub and remote clusters using WebSocket connections for real-time updates.
| Function | Type |
|---|---|
useFleetK8sWatchResource | <R extends FleetK8sResourceCommon or FleetK8sResourceCommon[]>(initResource: FleetWatchK8sResource or null) => WatchK8sResult<R> or [undefined, boolean, any] |
Parameters:
initResource: - The resource to watch. Can be null to disable the watch.initResource.cluster: - The managed cluster on which the resource resides; null for the hub clusterReturns:
A tuple containing the watched resource data, a boolean indicating if the data is loaded, and any error that occurred. The hook returns live-updating data.
Examples:
// Watch pods on a remote cluster
const [pods, loaded, error] = useFleetK8sWatchResource({
groupVersionKind: { version: 'v1', kind: 'Pod' },
isList: true,
cluster: 'remote-cluster',
namespace: 'default'
})
// Watch a specific deployment on hub cluster
const [deployment, loaded, error] = useFleetK8sWatchResource({
groupVersionKind: { group: 'apps', version: 'v1', kind: 'Deployment' },
name: 'my-app',
namespace: 'default'
})
| Function | Type |
|---|---|
useFleetPrometheusPoll | (props: PrometheusPollProps and { cluster?: string or undefined; } and { allClusters?: boolean or undefined; }) => [response: PrometheusResponse or undefined, loaded: boolean, error: unknown] |
A React hook that provides fleet-wide search functionality using the ACM search API.
| Function | Type |
|---|---|
useFleetSearchPoll | <T extends K8sResourceCommon or K8sResourceCommon[]>(watchOptions: WatchK8sResource, advancedSearchFilters?: AdvancedSearchFilter or undefined, pollInterval?: number or ... 1 more ... or undefined) => [...] |
Parameters:
watchOptions: - Configuration options for the resource watchwatchOptions.groupVersionKind: - The group, version, and kind of the resource to search forwatchOptions.limit: - Maximum number of results to return (defaults to -1 for no limit)watchOptions.namespace: - Namespace to search in (only used if namespaced is true)watchOptions.namespaced: - Whether the resource is namespacedwatchOptions.name: - Specific resource name to search for (exact match)watchOptions.isList: - Whether to return results as a list or single itemadvancedSearch: - Optional array of additional search filtersadvancedSearch[].property: - The property name to filter onadvancedSearch[].values: - Array of values to match for the propertypollInterval: - Optional polling interval in seconds. Defaults to 30 seconds (polling enabled).30: polls at the given interval in seconds
Returns:
A tuple containing:
data: The search results formatted as Kubernetes resources, or undefined if no resultsloaded: Boolean indicating if the search has completed (opposite of loading)error: Any error that occurred during the search, or undefined if successfulrefetch: A callback that enables you to re-execute the queryExamples:
// Search for all Pods in a specific namespace with default 30-second polling
const [pods, loaded, error] = useFleetSearchPoll({
groupVersionKind: { group: '', version: 'v1', kind: 'Pod' },
namespace: 'default',
namespaced: true,
isList: true
});
// Search for a specific Deployment with polling every 60 seconds
const [deployment, loaded, error] = useFleetSearchPoll({
groupVersionKind: { group: 'apps', version: 'v1', kind: 'Deployment' },
name: 'my-deployment',
namespace: 'default',
namespaced: true,
isList: false
}, [
{ property: 'label', values: ['app=my-app'] }
], 60);
// Search without polling (one-time query)
const [services, loaded, error] = useFleetSearchPoll({
groupVersionKind: { group: '', version: 'v1', kind: 'Service' },
namespaced: true,
isList: true
}, undefined, false);
Hook that provides hub cluster name.
| Function | Type |
|---|---|
useHubClusterName | () => [hubClusterName: string or undefined, loaded: boolean, error: any] |
Returns:
Array with hubclustername, loaded and error values.
Hook that determines if the fleet support is available.
Checks if the feature flag with the name corresponding to the REQUIRED_PROVIDER_FLAG constant is enabled.
Red Hat Advanced Cluster Management enables this feature flag in versions that provide all of the dependencies
required by this version of the multicluster SDK.
| Function | Type |
|---|---|
useIsFleetAvailable | () => boolean |
Returns:
true if a version of Red Hat Advanced Cluster Management that is compatible with the multicluster SDK is available; false otherwise
Hook that provides is observability installed.
| Function | Type |
|---|---|
useIsFleetObservabilityInstalled | () => [isObservabilityInstalled: boolean or undefined, loaded: boolean, error: unknown] |
Returns:
Array with isObservabilityInstalled, loaded and error values.
| Constant | Type |
|---|---|
REQUIRED_PROVIDER_FLAG | "MULTICLUSTER_SDK_PROVIDER_1" |
| Constant | Type |
|---|---|
RESOURCE_ROUTE_TYPE | "acm.resource/route" |
| Type | Type |
|---|---|
AdvancedSearchFilter | { property: string; values: string[] }[] |
| Type | Type |
|---|---|
Fleet | T and { cluster?: string } |
| Type | Type |
|---|---|
FleetAccessReviewResourceAttributes | Fleet<AccessReviewResourceAttributes> |
| Type | Type |
|---|---|
FleetK8sCreateUpdateOptions | { model: K8sModel name?: string ns?: string path?: string cluster?: string queryParams?: QueryParams data: R } |
| Type | Type |
|---|---|
FleetK8sDeleteOptions | { model: K8sModel name?: string ns?: string path?: string cluster?: string queryParams?: QueryParams resource: R requestInit?: RequestInit json?: Record<string, any> } |
| Type | Type |
|---|---|
FleetK8sGetOptions | { model: K8sModel name?: string ns?: string path?: string cluster?: string queryParams?: QueryParams requestInit?: RequestInit } |
| Type | Type |
|---|---|
FleetK8sListOptions | { model: K8sModel queryParams: { [key: string]: any } requestInit?: RequestInit } |
| Type | Type |
|---|---|
FleetK8sPatchOptions | { model: K8sModel name?: string ns?: string path?: string cluster?: string queryParams?: QueryParams resource: R data: Patch[] } |
| Type | Type |
|---|---|
FleetK8sResourceCommon | Fleet<K8sResourceCommon> |
| Type | Type |
|---|---|
FleetResourceEventStreamProps | { resource: FleetK8sResourceCommon } |
| Type | Type |
|---|---|
FleetResourceLinkProps | Fleet<ResourceLinkProps> |
| Type | Type |
|---|---|
FleetWatchK8sResource | Fleet<WatchK8sResource> |
This extension allows plugins to customize the route used for resources of the given kind. Search results and resource links will direct to the route returned by the implementing function.
| Type | Type |
|---|---|
ResourceRoute | ExtensionDeclaration<typeof RESOURCE_ROUTE_TYPE, ResourceRouteProps> |
| Type | Type |
|---|---|
ResourceRouteHandler | (props: { /** The cluster where the resource is located. */ cluster: string /** The namespace where the resource is located (if the resource is namespace-scoped). */ namespace?: string /** The name of the resource. */ name: string /** The resource, augmented with cluster property. */ resource: FleetK8sResourceCommon /** The model for the resource. */ model: ExtensionK8sModel }) => string or undefined |
| Type | Type |
|---|---|
ResourceRouteProps | { /** The model for which this resource route should be used. */ model: ExtensionK8sGroupKindModel /** The handler function that returns the route path for the resource. */ handler: CodeRef<ResourceRouteHandler> } |
| Type | Type |
|---|---|
SearchResult | R extends (infer T)[] ? Fleet<T>[] : Fleet<R> |
| Type | Type |
|---|---|
UseFleetK8sWatchResource | <R extends FleetK8sResourceCommon or FleetK8sResourceCommon[]>( initResource: FleetWatchK8sResource or null ) => WatchK8sResult<R> or [undefined, boolean, any] |
All contributions to the repository must be submitted under the terms of the Apache Public License 2.0. For contribution guidelines, see CONTRIBUTING.md.
FAQs
Provides extensions and APIs that dynamic plugins can use to leverage multicluster capabilities provided by Red Hat Advanced Cluster Management.
The npm package @stolostron/multicluster-sdk receives a total of 164 weekly downloads. As such, @stolostron/multicluster-sdk popularity was classified as not popular.
We found that @stolostron/multicluster-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ruby Central’s incident report on the RubyGems.org access dispute sparks backlash from former maintainers and renewed debate over project governance.
Research
/Security News
Socket researchers uncover how threat actors weaponize Discord across the npm, PyPI, and RubyGems ecosystems to exfiltrate sensitive data.
Security News
Socket now integrates with Bun 1.3’s Security Scanner API to block risky packages at install time and enforce your organization’s policies in local dev and CI.