typekro 0.3.1 → 0.5.0

package/dist/core/kubernetes/client-provider.js

@@ -1,16 +1,41 @@
 /**
  * Kubernetes Client Provider
  *
- * Single source of truth for all Kubernetes API interactions.
- * Manages KubeConfig loading and KubernetesObjectApi client instantiation
- * with consistent configuration across the entire application.
+ * Manages KubeConfig loading and Kubernetes API client instantiation
+ * with consistent configuration, security settings, and lifecycle management.
  *
- * This provider implements the singleton pattern and serves as the central
- * authority for all Kubernetes API client creation, ensuring consistent
- * configuration, security settings, and lifecycle management.
+ * ## Usage Patterns
+ *
+ * ### Recommended: Deployment-Scoped Providers
+ *
+ * Create a fresh provider per deployment/factory to ensure isolation between
+ * concurrent deployments. Use `KubernetesClientManager` (in
+ * `deployment/client-provider-manager.ts`) which handles this automatically:
+ *
+ * ```ts
+ * // Via factory options (handles provider lifecycle for you)
+ * const factory = graph.factory('direct', { namespace: 'prod' });
+ *
+ * // Manual scoped provider
+ * const provider = createKubernetesClientProvider({ skipTLSVerify: false });
+ * const api = provider.getKubernetesApi();
+ * ```
+ *
+ * ### Deprecated: Singleton Pattern
+ *
+ * The `getInstance()` / `getKubernetesClientProvider()` singleton and its
+ * convenience functions (`getKubernetesApi()`, `getCoreV1Api()`, etc.) are
+ * deprecated. They share a single provider instance across all deployments,
+ * preventing concurrent deployments from using different configurations and
+ * making cleanup error-prone. Use `createKubernetesClientProvider()` or
+ * `createKubernetesClientProviderWithKubeConfig()` instead.
  */
 import * as k8s from '@kubernetes/client-node';
+import { DEFAULT_BACKOFF_MULTIPLIER, DEFAULT_CLUSTER_READY_TIMEOUT, DEFAULT_FAST_POLL_INTERVAL, DEFAULT_MAX_RETRIES, DEFAULT_READINESS_MAX_BACKOFF, DEFAULT_RETRY_BASE_DELAY, } from '../config/defaults.js';
+import { isTestEnvironment } from '../config/index.js';
+import { ensureError, KubernetesClientError } from '../errors.js';
 import { getComponentLogger } from '../logging/index.js';
+import { createBunCompatibleApiClient, createBunCompatibleKubernetesObjectApi, isBunRuntime, } from './bun-api-client.js';
 /**
  * Kubernetes Client Provider - Single source of truth for Kubernetes API access
  *
@@ -29,7 +54,11 @@ export class KubernetesClientProvider {
     clientCache = new Map();
     constructor() { }
     /**
-     * Get the singleton instance of KubernetesClientProvider
+     * Get the singleton instance of KubernetesClientProvider.
+     *
+     * @deprecated Use {@link createInstance} for deployment-scoped provider instances.
+     * The singleton pattern prevents concurrent deployments from using different
+     * configurations. See `KubernetesClientManager` for the recommended pattern.
      */
     static getInstance() {
         if (!KubernetesClientProvider.instance) {
@@ -69,11 +98,14 @@ export class KubernetesClientProvider {
         try {
             this.config = config || {};
             this.kubeConfig = this.createKubeConfig(this.config);
-            this.k8sApi = this.kubeConfig.makeApiClient(k8s.KubernetesObjectApi);
+            // Use createBunCompatibleKubernetesObjectApi which handles both Bun and Node.js
+            // This works around Bun's fetch TLS issues (https://github.com/oven-sh/bun/issues/10642)
+            // Pass HTTP timeout configuration if provided
+            this.k8sApi = createBunCompatibleKubernetesObjectApi(this.kubeConfig, config?.httpTimeouts);
             this.initialized = true;
-            const isTestEnvironment = process.env.NODE_ENV === 'test' || process.env.VITEST === 'true';
+            const isTest = isTestEnvironment();
             // Use debug level in test environments to reduce noise, info level in production
-            const logLevel = isTestEnvironment ? 'debug' : 'info';
+            const logLevel = isTest ? 'debug' : 'info';
             this.logger[logLevel]('Kubernetes client provider initialized successfully', {
                 currentContext: this.kubeConfig.getCurrentContext(),
                 server: this.kubeConfig.getCurrentCluster()?.server,
@@ -83,11 +115,9 @@ export class KubernetesClientProvider {
             });
         }
         catch (error) {
-            this.logger.error('Failed to initialize Kubernetes client provider', error);
+            this.logger.error('Failed to initialize Kubernetes client provider', ensureError(error));
             this.reset();
-            const enhancedError = new Error(`Failed to initialize Kubernetes client provider: ${error.message}`);
-            enhancedError.cause = error;
-            throw enhancedError;
+            throw new KubernetesClientError(`Failed to initialize Kubernetes client provider: ${ensureError(error).message}`, 'initialization', ensureError(error));
         }
     }
     /**
@@ -98,21 +128,22 @@ export class KubernetesClientProvider {
         this.logger.debug('Initializing Kubernetes client provider with pre-configured KubeConfig');
         try {
             this.kubeConfig = kubeConfig;
-            this.k8sApi = this.kubeConfig.makeApiClient(k8s.KubernetesObjectApi);
+            // Use createBunCompatibleKubernetesObjectApi which handles both Bun and Node.js
+            // This works around Bun's fetch TLS issues (https://github.com/oven-sh/bun/issues/10642)
+            this.k8sApi = createBunCompatibleKubernetesObjectApi(this.kubeConfig);
             this.initialized = true;
             this.config = null; // No config object when using pre-configured KubeConfig
             this.logger.info('Kubernetes client provider initialized with pre-configured KubeConfig', {
                 currentContext: this.kubeConfig.getCurrentContext(),
                 server: this.kubeConfig.getCurrentCluster()?.server,
                 skipTLSVerify: this.kubeConfig.getCurrentCluster()?.skipTLSVerify,
+                runtime: isBunRuntime() ? 'bun' : 'node',
             });
         }
         catch (error) {
-            this.logger.error('Failed to initialize with pre-configured KubeConfig', error);
+            this.logger.error('Failed to initialize with pre-configured KubeConfig', ensureError(error));
             this.reset();
-            const enhancedError = new Error(`Failed to initialize with pre-configured KubeConfig: ${error.message}`);
-            enhancedError.cause = error;
-            throw enhancedError;
+            throw new KubernetesClientError(`Failed to initialize with pre-configured KubeConfig: ${ensureError(error).message}`, 'initialization', ensureError(error));
         }
     }
     /**
@@ -260,7 +291,7 @@ export class KubernetesClientProvider {
         }
         catch (error) {
             this.logger.debug('Cluster availability check failed', {
-                error: error.message,
+                error: ensureError(error).message,
             });
             return false;
         }
@@ -273,7 +304,7 @@ export class KubernetesClientProvider {
      * @param retryInterval - Interval between retry attempts in milliseconds (default: 1000ms)
      * @throws Error if cluster doesn't become available within timeout
      */
-    async waitForClusterReady(timeout = 30000, retryInterval = 1000) {
+    async waitForClusterReady(timeout = DEFAULT_CLUSTER_READY_TIMEOUT, retryInterval = DEFAULT_FAST_POLL_INTERVAL) {
         const startTime = Date.now();
         while (Date.now() - startTime < timeout) {
             if (await this.isClusterAvailable()) {
@@ -288,7 +319,7 @@ export class KubernetesClientProvider {
             });
             await new Promise((resolve) => setTimeout(resolve, retryInterval));
         }
-        throw new Error(`Cluster did not become available within ${timeout}ms timeout`);
+        throw new KubernetesClientError(`Cluster did not become available within ${timeout}ms timeout`, 'cluster-availability');
     }
     /**
      * Execute an operation with retry logic and exponential backoff
@@ -300,7 +331,7 @@ export class KubernetesClientProvider {
      * @throws Error if all retry attempts fail
      */
     async withRetry(operation, options = {}) {
-        const { maxAttempts = 3, baseDelay = 1000, maxDelay = 10000, backoffFactor = 2, retryableErrors = this.defaultRetryableErrorCheck, } = options;
+        const { maxAttempts = DEFAULT_MAX_RETRIES, baseDelay = DEFAULT_RETRY_BASE_DELAY, maxDelay = DEFAULT_READINESS_MAX_BACKOFF, backoffFactor = DEFAULT_BACKOFF_MULTIPLIER, retryableErrors = this.defaultRetryableErrorCheck, } = options;
         let lastError;
         for (let attempt = 1; attempt <= maxAttempts; attempt++) {
             try {
@@ -314,7 +345,7 @@ export class KubernetesClientProvider {
                 return result;
             }
             catch (error) {
-                lastError = error;
+                lastError = ensureError(error);
                 if (attempt === maxAttempts || !retryableErrors(lastError)) {
                     this.logger.error('Operation failed after all retry attempts', lastError, {
                         attempt,
@@ -333,12 +364,17 @@ export class KubernetesClientProvider {
                 await new Promise((resolve) => setTimeout(resolve, delay));
             }
         }
-        throw lastError;
+        // Unreachable when maxAttempts >= 1: either the operation succeeds (return)
+        // or the last attempt's catch block throws. This handles maxAttempts === 0.
+        throw lastError ?? new Error(`Retry failed: maxAttempts was ${maxAttempts}`);
     }
     /**
      * Get a cached API client instance or create a new one
      * This method implements client caching to avoid recreating clients unnecessarily
      *
+     * When running in Bun, uses a custom HTTP library that properly handles
+     * TLS certificates (workaround for https://github.com/oven-sh/bun/issues/10642)
+     *
      * @param clientType - String identifier for the client type
      * @param clientClass - The API client class constructor
      * @returns Cached or new API client instance
@@ -351,34 +387,37 @@ export class KubernetesClientProvider {
         }
         let client;
         try {
-            // Use the standard makeApiClient approach
-            client = this.kubeConfig?.makeApiClient(clientClass);
-            this.logger.debug('Created API client using makeApiClient', {
-                clientType,
-                constructorName: client.constructor.name,
-                hasValidPrototype: Object.getPrototypeOf(client) !== null,
-                hasSetDefaultAuth: typeof client.setDefaultAuthentication === 'function',
-            });
+            // Use Bun-compatible client creation when running in Bun
+            // This works around Bun's fetch TLS issues
+            if (isBunRuntime() && this.kubeConfig) {
+                client = createBunCompatibleApiClient(this.kubeConfig, clientClass, this.config?.httpTimeouts);
+                this.logger.debug('Created API client using Bun-compatible HTTP library', {
+                    clientType,
+                    runtime: 'bun',
+                    hasCustomTimeouts: !!this.config?.httpTimeouts,
+                });
+            }
+            else {
+                // Use the standard makeApiClient approach for Node.js
+                client = this.kubeConfig?.makeApiClient(clientClass);
+                this.logger.debug('Created API client using makeApiClient', {
+                    clientType,
+                    runtime: 'node',
+                });
+            }
         }
         catch (error) {
-            // Log detailed information about why makeApiClient failed
-            this.logger.error('makeApiClient failed - this indicates a serious issue with the Kubernetes client library', error, {
+            // Log detailed information about why client creation failed
+            this.logger.error('API client creation failed', ensureError(error), {
                 clientType,
-                clientClass: typeof clientClass,
                 clientClassName: clientClass?.name,
-                clientClassString: String(clientClass),
-                hasPrototype: !!clientClass?.prototype,
-                prototypeType: typeof clientClass?.prototype,
-                prototypeHasSetDefaultAuth: clientClass?.prototype
-                    ? typeof clientClass.prototype.setDefaultAuthentication === 'function'
-                    : 'no prototype',
-                classHasSetDefaultAuth: typeof clientClass?.setDefaultAuthentication === 'function',
+                isBun: isBunRuntime(),
                 kubeConfigValid: !!this.kubeConfig,
                 currentCluster: this.kubeConfig?.getCurrentCluster()?.name,
                 currentUser: this.kubeConfig?.getCurrentUser()?.name,
             });
             // Re-throw the error instead of falling back
-            throw new Error(`Failed to create ${clientType} API client: ${error.message}`);
+            throw new KubernetesClientError(`Failed to create ${clientType} API client: ${ensureError(error).message}`, 'client-creation', ensureError(error));
         }
         // Cache the client for future use
         this.clientCache.set(clientType, client);
@@ -431,9 +470,7 @@ export class KubernetesClientProvider {
                 {
                     name: config.cluster.name,
                     server: config.cluster.server,
-                    ...(config.cluster.skipTLSVerify !== undefined && {
-                        skipTLSVerify: config.cluster.skipTLSVerify,
-                    }),
+                    skipTLSVerify: config.cluster.skipTLSVerify ?? false,
                     ...(config.cluster.caData && { caData: config.cluster.caData }),
                     ...(config.cluster.caFile && { caFile: config.cluster.caFile }),
                 },
@@ -473,10 +510,18 @@ export class KubernetesClientProvider {
                 this.applyConfigModifications(kc, config);
             }
             catch (error) {
-                // If loading from default fails (e.g., in test environments), create a minimal mock config
+                /**
+                 * @security Mock credentials are only used in test environments.
+                 * In production, kubeconfig loading failures are fatal to prevent
+                 * accidentally connecting with mock/insecure credentials.
+                 */
+                const isTestEnv = isTestEnvironment();
+                if (!isTestEnv) {
+                    this.logger.error('Failed to load kubeconfig in non-test environment, re-throwing', ensureError(error));
+                    throw error;
+                }
                 this.logger.warn('Failed to load kubeconfig, creating minimal mock configuration for testing', {
-                    error: error.message,
-                    isTestEnvironment: process.env.NODE_ENV === 'test' || process.env.VITEST === 'true',
+                    error: ensureError(error).message,
                 });
                 // Create a minimal mock configuration for testing
                 kc.clusters = [
@@ -503,7 +548,7 @@ export class KubernetesClientProvider {
             }
         }
         else {
-            throw new Error('Either complete cluster/user configuration must be provided, or loadFromDefault must be true');
+            throw new KubernetesClientError('Either complete cluster/user configuration must be provided, or loadFromDefault must be true', 'configuration');
         }
         // Validate and log security configuration
         this.validateAndLogSecurityConfiguration(kc, config);
@@ -546,11 +591,11 @@ export class KubernetesClientProvider {
                 });
             }
             catch (error) {
-                this.logger.error('Failed to set context', error, {
+                this.logger.error('Failed to set context', ensureError(error), {
                     requestedContext: config.context,
                     availableContexts: kc.getContexts().map((c) => c.name),
                 });
-                throw new Error(`Context '${config.context}' not found in kubeconfig`);
+                throw new KubernetesClientError(`Context '${config.context}' not found in kubeconfig`, 'configuration', ensureError(error));
             }
         }
     }
@@ -583,27 +628,61 @@ export class KubernetesClientProvider {
             catch (error) {
                 this.logger.warn('Invalid server URL format', {
                     server: cluster.server,
-                    error: error.message,
+                    error: ensureError(error).message,
                 });
             }
         }
+        // Check for bearer token over HTTP (unencrypted)
+        const user = kc.getCurrentUser();
+        if (cluster?.server?.startsWith('http://') && user?.token) {
+            this.logger.warn('Bearer token configured for unencrypted HTTP connection - token may be intercepted', {
+                server: cluster.server,
+                security: 'bearer-token-over-http',
+                recommendation: 'Use HTTPS endpoint to protect bearer token in transit',
+                securityRisk: 'Bearer tokens sent over HTTP are visible to network observers',
+            });
+        }
     }
     /**
-     * Check if two configurations are the same
+     * Check if two configurations are structurally equivalent.
+     * Compares identity fields without serializing sensitive credential material
+     * (tokens, certificates, keys) to avoid leaking secrets into memory strings.
+     *
+     * NOTE: Token comparison is presence-only (has token vs. no token), not value-based.
+     * A rotated token with the same presence (e.g. refreshed service account tokens) will
+     * NOT trigger a new client — the cached client continues with the old token.
+     * This is a known limitation: callers that rotate credentials should call invalidateClient()
+     * explicitly or create a new provider instance.
      */
     isSameConfig(config) {
         if (!this.config && !config)
             return true;
         if (!this.config || !config)
             return false;
-        return JSON.stringify(this.config) === JSON.stringify(config);
+        return (this.config.server === config.server &&
+            this.config.context === config.context &&
+            this.config.skipTLSVerify === config.skipTLSVerify &&
+            this.config.loadFromDefault === config.loadFromDefault &&
+            this.config.kubeconfigPath === config.kubeconfigPath &&
+            this.config.cluster?.name === config.cluster?.name &&
+            this.config.cluster?.server === config.cluster?.server &&
+            this.config.cluster?.skipTLSVerify === config.cluster?.skipTLSVerify &&
+            this.config.user?.name === config.user?.name &&
+            // Compare credential presence without serializing values
+            !!this.config.user?.token === !!config.user?.token &&
+            !!this.config.user?.certData === !!config.user?.certData &&
+            !!this.config.user?.certFile === !!config.user?.certFile &&
+            !!this.config.user?.keyData === !!config.user?.keyData &&
+            !!this.config.user?.keyFile === !!config.user?.keyFile &&
+            !!this.config.cluster?.caData === !!config.cluster?.caData &&
+            !!this.config.cluster?.caFile === !!config.cluster?.caFile);
     }
     /**
      * Ensure the provider is initialized
      */
     ensureInitialized() {
         if (!this.initialized || !this.kubeConfig || !this.k8sApi) {
-            throw new Error('KubernetesClientProvider not initialized. Call initialize() first.');
+            throw new KubernetesClientError('KubernetesClientProvider not initialized. Call initialize() first.', 'initialization');
         }
     }
     /**
@@ -653,7 +732,14 @@ export class KubernetesClientProvider {
     }
 }
 /**
- * Convenience function to get the singleton instance
+ * Convenience function to get the singleton instance.
+ *
+ * @deprecated Use {@link createKubernetesClientProvider} or
+ * {@link createKubernetesClientProviderWithKubeConfig} instead to create
+ * deployment-scoped provider instances. The singleton pattern prevents
+ * concurrent deployments from using different configurations and makes
+ * cleanup error-prone. See `KubernetesClientManager` for the recommended
+ * per-factory pattern.
  */
 export function getKubernetesClientProvider() {
     return KubernetesClientProvider.getInstance();
@@ -677,8 +763,11 @@ export function createKubernetesClientProviderWithKubeConfig(kubeConfig) {
     return provider;
 }
 /**
- * Convenience function to get a configured Kubernetes API client
- * Uses the singleton provider and initializes it with default config if needed
+ * Convenience function to get a configured Kubernetes API client.
+ * Uses the singleton provider and initializes it with default config if needed.
+ *
+ * @deprecated Create a scoped provider with {@link createKubernetesClientProvider}
+ * and call `.getKubernetesApi()` on the instance instead.
  */
 export function getKubernetesApi(config) {
     const provider = getKubernetesClientProvider();
@@ -688,8 +777,11 @@ export function getKubernetesApi(config) {
     return provider.getKubernetesApi();
 }
 /**
- * Convenience function to get a configured KubeConfig
- * Uses the singleton provider and initializes it with default config if needed
+ * Convenience function to get a configured KubeConfig.
+ * Uses the singleton provider and initializes it with default config if needed.
+ *
+ * @deprecated Create a scoped provider with {@link createKubernetesClientProvider}
+ * and call `.getKubeConfig()` on the instance instead.
  */
 export function getKubeConfig(config) {
     const provider = getKubernetesClientProvider();
@@ -699,8 +791,11 @@ export function getKubeConfig(config) {
     return provider.getKubeConfig();
 }
 /**
- * Convenience function to get a configured CoreV1Api client
- * Uses the singleton provider and initializes it with default config if needed
+ * Convenience function to get a configured CoreV1Api client.
+ * Uses the singleton provider and initializes it with default config if needed.
+ *
+ * @deprecated Create a scoped provider with {@link createKubernetesClientProvider}
+ * and call `.getCoreV1Api()` on the instance instead.
  */
 export function getCoreV1Api(config) {
     const provider = getKubernetesClientProvider();
@@ -710,8 +805,11 @@ export function getCoreV1Api(config) {
     return provider.getCoreV1Api();
 }
 /**
- * Convenience function to get a configured AppsV1Api client
- * Uses the singleton provider and initializes it with default config if needed
+ * Convenience function to get a configured AppsV1Api client.
+ * Uses the singleton provider and initializes it with default config if needed.
+ *
+ * @deprecated Create a scoped provider with {@link createKubernetesClientProvider}
+ * and call `.getAppsV1Api()` on the instance instead.
  */
 export function getAppsV1Api(config) {
     const provider = getKubernetesClientProvider();
@@ -721,8 +819,11 @@ export function getAppsV1Api(config) {
     return provider.getAppsV1Api();
 }
 /**
- * Convenience function to get a configured CustomObjectsApi client
- * Uses the singleton provider and initializes it with default config if needed
+ * Convenience function to get a configured CustomObjectsApi client.
+ * Uses the singleton provider and initializes it with default config if needed.
+ *
+ * @deprecated Create a scoped provider with {@link createKubernetesClientProvider}
+ * and call `.getCustomObjectsApi()` on the instance instead.
  */
 export function getCustomObjectsApi(config) {
     const provider = getKubernetesClientProvider();
@@ -732,8 +833,11 @@ export function getCustomObjectsApi(config) {
     return provider.getCustomObjectsApi();
 }
 /**
- * Convenience function to get a configured BatchV1Api client
- * Uses the singleton provider and initializes it with default config if needed
+ * Convenience function to get a configured BatchV1Api client.
+ * Uses the singleton provider and initializes it with default config if needed.
+ *
+ * @deprecated Create a scoped provider with {@link createKubernetesClientProvider}
+ * and call `.getBatchV1Api()` on the instance instead.
  */
 export function getBatchV1Api(config) {
     const provider = getKubernetesClientProvider();
@@ -743,8 +847,11 @@ export function getBatchV1Api(config) {
     return provider.getBatchV1Api();
 }
 /**
- * Convenience function to get a configured NetworkingV1Api client
- * Uses the singleton provider and initializes it with default config if needed
+ * Convenience function to get a configured NetworkingV1Api client.
+ * Uses the singleton provider and initializes it with default config if needed.
+ *
+ * @deprecated Create a scoped provider with {@link createKubernetesClientProvider}
+ * and call `.getNetworkingV1Api()` on the instance instead.
  */
 export function getNetworkingV1Api(config) {
     const provider = getKubernetesClientProvider();
@@ -754,8 +861,11 @@ export function getNetworkingV1Api(config) {
     return provider.getNetworkingV1Api();
 }
 /**
- * Convenience function to get a configured RbacAuthorizationV1Api client
- * Uses the singleton provider and initializes it with default config if needed
+ * Convenience function to get a configured RbacAuthorizationV1Api client.
+ * Uses the singleton provider and initializes it with default config if needed.
+ *
+ * @deprecated Create a scoped provider with {@link createKubernetesClientProvider}
+ * and call `.getRbacAuthorizationV1Api()` on the instance instead.
  */
 export function getRbacAuthorizationV1Api(config) {
     const provider = getKubernetesClientProvider();
@@ -765,8 +875,11 @@ export function getRbacAuthorizationV1Api(config) {
     return provider.getRbacAuthorizationV1Api();
 }
 /**
- * Convenience function to get a configured StorageV1Api client
- * Uses the singleton provider and initializes it with default config if needed
+ * Convenience function to get a configured StorageV1Api client.
+ * Uses the singleton provider and initializes it with default config if needed.
+ *
+ * @deprecated Create a scoped provider with {@link createKubernetesClientProvider}
+ * and call `.getStorageV1Api()` on the instance instead.
  */
 export function getStorageV1Api(config) {
     const provider = getKubernetesClientProvider();
@@ -776,8 +889,11 @@ export function getStorageV1Api(config) {
     return provider.getStorageV1Api();
 }
 /**
- * Convenience function to get a configured ApiExtensionsV1Api client
- * Uses the singleton provider and initializes it with default config if needed
+ * Convenience function to get a configured ApiExtensionsV1Api client.
+ * Uses the singleton provider and initializes it with default config if needed.
+ *
+ * @deprecated Create a scoped provider with {@link createKubernetesClientProvider}
+ * and call `.getApiExtensionsV1Api()` on the instance instead.
  */
 export function getApiExtensionsV1Api(config) {
     const provider = getKubernetesClientProvider();
@@ -787,8 +903,11 @@ export function getApiExtensionsV1Api(config) {
     return provider.getApiExtensionsV1Api();
 }
 /**
- * Convenience function to check cluster availability
- * Uses the singleton provider and initializes it with default config if needed
+ * Convenience function to check cluster availability.
+ * Uses the singleton provider and initializes it with default config if needed.
+ *
+ * @deprecated Create a scoped provider with {@link createKubernetesClientProvider}
+ * and call `.isClusterAvailable()` on the instance instead.
  */
 export async function isClusterAvailable(config) {
     const provider = getKubernetesClientProvider();
@@ -798,8 +917,11 @@ export async function isClusterAvailable(config) {
     return provider.isClusterAvailable();
 }
 /**
- * Convenience function to wait for cluster readiness
- * Uses the singleton provider and initializes it with default config if needed
+ * Convenience function to wait for cluster readiness.
+ * Uses the singleton provider and initializes it with default config if needed.
+ *
+ * @deprecated Create a scoped provider with {@link createKubernetesClientProvider}
+ * and call `.waitForClusterReady()` on the instance instead.
  */
 export async function waitForClusterReady(timeout, retryInterval, config) {
     const provider = getKubernetesClientProvider();
@@ -809,8 +931,11 @@ export async function waitForClusterReady(timeout, retryInterval, config) {
     return provider.waitForClusterReady(timeout, retryInterval);
 }
 /**
- * Convenience function to execute operations with retry logic
- * Uses the singleton provider and initializes it with default config if needed
+ * Convenience function to execute operations with retry logic.
+ * Uses the singleton provider and initializes it with default config if needed.
+ *
+ * @deprecated Create a scoped provider with {@link createKubernetesClientProvider}
+ * and call `.withRetry()` on the instance instead.
  */
 export async function withRetry(operation, options, config) {
     const provider = getKubernetesClientProvider();