@backstage/plugin-kubernetes-node 0.4.7 → 0.4.8-next.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @backstage/plugin-kubernetes-node
 
+## 0.4.8-next.0
+
+### Patch Changes
+
+- d9a57de: Add `KubernetesWatcher` interface for streaming Kubernetes resource changes via an async iterator. The watcher is separated from `KubernetesFetcher` because watching is a long-lived streaming connection that only works with server-side auth providers. Watch supports all event types (ADDED, MODIFIED, DELETED, BOOKMARK, ERROR) with errors yielded as data rather than thrown.
+- Updated dependencies
+  - @backstage/plugin-kubernetes-common@0.9.13-next.0
+
 ## 0.4.7
 
 ### Patch Changes

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { BackstageCredentials, LoggerService } from '@backstage/backend-plugin-a
 import { AuthenticationStrategy as AuthenticationStrategy$1, KubernetesClustersSupplier as KubernetesClustersSupplier$1, KubernetesFetcher as KubernetesFetcher$1, KubernetesObjectsProvider as KubernetesObjectsProvider$1, KubernetesServiceLocator as KubernetesServiceLocator$1, CustomResource as CustomResource$1, ObjectToFetch as ObjectToFetch$1 } from '@backstage/plugin-kubernetes-node';
 import express from 'express';
 import { Entity } from '@backstage/catalog-model';
-import { CustomResourceMatcher, KubernetesRequestAuth, KubernetesFetchError, FetchResponse, ObjectsByEntityResponse } from '@backstage/plugin-kubernetes-common';
+import { CustomResourceMatcher, KubernetesRequestAuth, KubernetesFetchError, FetchResponse, ObjectsByEntityResponse, KubernetesWatchOptions, KubernetesWatchEvent } from '@backstage/plugin-kubernetes-common';
 import { JsonObject } from '@backstage/types';
 
 /**
@@ -317,6 +317,22 @@ interface FetchResponseWrapper {
     errors: KubernetesFetchError[];
     responses: FetchResponse[];
 }
+/**
+ * Parameters identifying the Kubernetes resource to watch
+ * @public
+ */
+interface KubernetesWatchParams {
+    /** Cluster connection details */
+    clusterDetails: ClusterDetails;
+    /** Authentication credentials */
+    credential: KubernetesCredential;
+    /** API group (empty string for core resources) */
+    group: string;
+    /** API version (e.g., 'v1', 'v1beta1') */
+    apiVersion: string;
+    /** Resource plural name (e.g., 'pods', 'deployments') */
+    plural: string;
+}
 /**
  * Fetches information from a kubernetes cluster using the cluster details object to target a specific cluster
  *
@@ -326,6 +342,32 @@ interface KubernetesFetcher {
     fetchObjectsForService(params: ObjectFetchParams): Promise<FetchResponseWrapper>;
     fetchPodMetricsByNamespaces(clusterDetails: ClusterDetails, credential: KubernetesCredential, namespaces: Set<string>, labelSelector?: string): Promise<FetchResponseWrapper>;
 }
+/**
+ * Watches Kubernetes resources for changes.
+ *
+ * Separated from {@link KubernetesFetcher} because watching is a long-lived
+ * streaming connection that only works with server-side auth providers.
+ *
+ * @public
+ */
+interface KubernetesWatcher {
+    /**
+     * Watch Kubernetes resources for changes.
+     *
+     * Returns an AsyncGenerator whose three type parameters are:
+     *   - Yield (`KubernetesWatchEvent`): each `yield` produces a watch event.
+     *     Errors are yielded as `{ type: 'ERROR', error }` (errors-as-data),
+     *     not thrown, so consumers handle them in the same `for await` loop.
+     *   - Return (`void`): the generator never produces a meaningful completion
+     *     value — it ends with bare `return` or by exhausting the stream.
+     *   - Next (`undefined`): the consumer cannot send values into the generator
+     *     via `.next(value)`; this is a produce-only stream.
+     *
+     * @param params - Cluster, credentials, and resource identification
+     * @param options - Optional watch parameters (filters, signal, etc.)
+     */
+    watchResource(params: KubernetesWatchParams, options?: KubernetesWatchOptions): AsyncGenerator<KubernetesWatchEvent, void, undefined>;
+}
 /**
  * @public
  */
@@ -381,4 +423,4 @@ declare class PinnipedHelper {
 }
 
 export { PinnipedHelper, kubernetesAuthStrategyExtensionPoint, kubernetesClusterSupplierExtensionPoint, kubernetesFetcherExtensionPoint, kubernetesObjectsProviderExtensionPoint, kubernetesRouterExtensionPoint, kubernetesServiceLocatorExtensionPoint };
-export type { AuthMetadata, AuthenticationStrategy, ClusterDetails, CustomResource, CustomResourcesByEntity, FetchResponseWrapper, KubernetesAuthStrategyExtensionPoint, KubernetesClusterSupplierExtensionPoint, KubernetesClusterSupplierFactory, KubernetesClustersSupplier, KubernetesCredential, KubernetesFetcher, KubernetesFetcherExtensionPoint, KubernetesFetcherFactory, KubernetesObjectTypes, KubernetesObjectsByEntity, KubernetesObjectsProvider, KubernetesObjectsProviderExtensionPoint, KubernetesObjectsProviderFactory, KubernetesRouterExtensionPoint, KubernetesRouterFactory, KubernetesServiceLocator, KubernetesServiceLocatorExtensionPoint, KubernetesServiceLocatorFactory, ObjectFetchParams, ObjectToFetch, PinnipedClientCerts, PinnipedParameters, ServiceLocatorRequestContext };
+export type { AuthMetadata, AuthenticationStrategy, ClusterDetails, CustomResource, CustomResourcesByEntity, FetchResponseWrapper, KubernetesAuthStrategyExtensionPoint, KubernetesClusterSupplierExtensionPoint, KubernetesClusterSupplierFactory, KubernetesClustersSupplier, KubernetesCredential, KubernetesFetcher, KubernetesFetcherExtensionPoint, KubernetesFetcherFactory, KubernetesObjectTypes, KubernetesObjectsByEntity, KubernetesObjectsProvider, KubernetesObjectsProviderExtensionPoint, KubernetesObjectsProviderFactory, KubernetesRouterExtensionPoint, KubernetesRouterFactory, KubernetesServiceLocator, KubernetesServiceLocatorExtensionPoint, KubernetesServiceLocatorFactory, KubernetesWatchParams, KubernetesWatcher, ObjectFetchParams, ObjectToFetch, PinnipedClientCerts, PinnipedParameters, ServiceLocatorRequestContext };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-kubernetes-node",
-  "version": "0.4.7",
+  "version": "0.4.8-next.0",
   "description": "Node.js library for the kubernetes plugin",
   "backstage": {
     "role": "node-library",
@@ -38,20 +38,20 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage/backend-plugin-api": "^1.10.0",
-    "@backstage/catalog-model": "^1.10.0",
-    "@backstage/plugin-kubernetes-common": "^0.9.12",
-    "@backstage/types": "^1.2.2",
+    "@backstage/backend-plugin-api": "1.10.0",
+    "@backstage/catalog-model": "1.10.0",
+    "@backstage/plugin-kubernetes-common": "0.9.13-next.0",
+    "@backstage/types": "1.2.2",
     "@kubernetes/client-node": "1.4.0",
     "@types/express": "^4.17.6",
     "node-fetch": "^2.7.0"
   },
   "devDependencies": {
-    "@backstage/backend-app-api": "^1.7.3",
-    "@backstage/backend-defaults": "^0.17.7",
-    "@backstage/backend-test-utils": "^1.11.6",
-    "@backstage/cli": "^0.36.5",
-    "@backstage/plugin-kubernetes-backend": "^0.21.7",
+    "@backstage/backend-app-api": "1.7.3",
+    "@backstage/backend-defaults": "0.17.7",
+    "@backstage/backend-test-utils": "1.11.6",
+    "@backstage/cli": "0.36.6-next.0",
+    "@backstage/plugin-kubernetes-backend": "0.21.10-next.0",
     "msw": "^1.3.1",
     "supertest": "^7.0.0"
   },