Merge pull request #48 from ccremer/watch

Watch Kubernetes resources for efficient change detection

Author: ccremer

packages/kubernetes-client-example-fetch/README.md

@@ -30,7 +30,8 @@ Configure our cluster
 
 ```bash
 kubectl -n default create sa browser-client
-kubectl create clusterrolebinding browser-client --serviceaccount=default:browser-client --clusterrole cluster-admin 
+kubectl create clusterrolebinding browser-client --serviceaccount=default:browser-client --clusterrole cluster-admin
+echo "VITE_KUBERNETES_API_URL=${VITE_KUBERNETES_API_URL}" > packages/kubernetes-client-example-fetch/.env
 ```
 
 ## Create a token

packages/kubernetes-client-example-fetch/src/index.html

@@ -39,6 +39,7 @@ <h3>Demo</h3>
 
               <button id="getBtn" class="btn btn-primary">Get</button>
               <button id="listBtn" class="btn btn-secondary">List</button>
+              <button id="watchBtn" class="btn btn-secondary">Watch</button>
             </div>
           </div>
         </div>
@@ -48,6 +49,7 @@ <h3>Demo</h3>
               <input id="hideManagedFields" type="checkbox" role="switch" class="form-check-input" value="checked" />
               <label for="hideManagedFields" class="form-check-label">Hide Managed Fields</label>
             </div>
+            <button id="clearOutputBtn" type="button" class="btn btn-outline-secondary">Clear Output</button>
           </div>
         </div>
         <div class="row mb-3">

packages/kubernetes-client-example-fetch/src/js/main.ts

@@ -2,13 +2,17 @@ import '../styles.scss'
 import { Client, KubeClientBuilder } from '@ccremer/kubernetes-client/fetch'
 import { newSelfSubjectRulesReview } from './types'
 import { createAlert } from './alerts'
+import { WatchEvent } from '@ccremer/kubernetes-client/api'
+import { KubeObject } from '@ccremer/kubernetes-client/types/core'
 
 console.debug('Starting up...')
 
 window.onload = function () {
   document.getElementById('createClient')?.addEventListener('click', createClient)
   document.getElementById('listBtn')?.addEventListener('click', listObjects)
   document.getElementById('getBtn')?.addEventListener('click', getObject)
+  document.getElementById('watchBtn')?.addEventListener('click', watchObjects)
+  document.getElementById('clearOutputBtn')?.addEventListener('click', clearOutput)
   const tokenElement = document.getElementById('token')
   if (tokenElement instanceof HTMLInputElement) {
     tokenElement.value = localStorage.getItem('token') ?? ''
@@ -62,7 +66,7 @@ function getObject(): void {
   const name = getName()
 
   if (name) {
-    console.debug('Fetching Object', `${kind}${namespace}/${name}`)
+    console.debug('Fetching Object', `${kind}/${namespace}/${name}`)
     kubeClient
       .getById('v1', kind, name, namespace, { hideManagedFields: hideManagedFields() })
       .then((cm) => fillTextArea(cm))
@@ -72,6 +76,53 @@ function getObject(): void {
   }
 }
 
+let abortController: AbortController | undefined
+
+function watchObjects(): void {
+  if (!kubeClient) return
+  if (abortController) {
+    abortController.abort('Stop')
+    abortController = undefined
+    toggleWatchButton(false)
+    return
+  }
+
+  const kind = getKind()
+  const namespace = getNamespace()
+  const name = getName()
+
+  const events: WatchEvent<KubeObject>[] = []
+
+  console.debug('Watching Objects in', `${kind}/${namespace}`)
+  kubeClient
+    .watchByID(
+      {
+        onUpdate: (event) => {
+          if (event) {
+            events.push(event)
+            fillTextArea(events)
+          }
+        },
+        onError: (err, effect) => {
+          console.log('received err', err)
+          if (err instanceof Error) createAlert(`Watch failed: ${err.message}`, 'danger')
+          if (typeof err === 'string' && err === 'Stop') createAlert('Watch stopped', 'warning', 3000)
+          if (effect?.closed) toggleWatchButton(false)
+        },
+      },
+      'v1',
+      kind,
+      name,
+      namespace,
+      { hideManagedFields: hideManagedFields() }
+    )
+    .then((result) => {
+      abortController = result.abortController
+      toggleWatchButton(true)
+    })
+    .catch((err) => createAlert(err.message, 'danger'))
+}
+
 function getNamespace(): string {
   const namespaceInput = document.getElementById('namespace')
   return namespaceInput instanceof HTMLInputElement ? namespaceInput.value : 'default'
@@ -100,9 +151,22 @@ function fillTextArea(value: unknown): void {
   }
 }
 
+function clearOutput(): void {
+  const textArea = document.getElementById('kubeobject')
+  if (textArea instanceof HTMLTextAreaElement) {
+    textArea.value = ''
+  }
+}
+
 function enableDemo(): void {
   const container = document.getElementById('demo-container')
   if (container) {
     container.className = container.className.replace('visually-hidden', '')
   }
 }
+
+function toggleWatchButton(isWatching: boolean): void {
+  const btn = document.getElementById('watchBtn')
+  if (!btn) return
+  btn.innerText = isWatching ? 'Stop' : 'Watch'
+}

packages/kubernetes-client-example-fetch/tests/demo.spec.ts

@@ -61,4 +61,44 @@ test.describe('demo form', () => {
     }
     await expect(value).toEqual(expected)
   })
+
+  test('should watch configmaps', async ({ page }) => {
+    await page.locator('#resourceKind').selectOption('ConfigMap')
+    await page.locator('#namespace').type('default')
+    await page.locator('#watchBtn').click()
+    const area = page.locator('#kubeobject')
+    await expect(area).toBeEnabled()
+    const value = await area
+      .inputValue()
+      .then((v) => JSON.parse(v))
+      .then((json) => {
+        const obj = json[0].object
+        delete obj.metadata.resourceVersion
+        delete obj.metadata.managedFields
+        delete obj.metadata.uid
+        delete obj.metadata.annotations
+        delete obj.metadata.creationTimestamp
+        obj.data['ca.crt'] = ''
+        return json[0]
+      })
+    const expected = {
+      type: 'ADDED',
+      object: {
+        kind: 'ConfigMap',
+        apiVersion: 'v1',
+        metadata: {
+          name: 'kube-root-ca.crt',
+          namespace: 'default',
+        },
+        data: {
+          'ca.crt': '',
+        },
+      },
+    }
+    await expect(value).toEqual(expected)
+    await page.locator('#watchBtn').click()
+
+    const res = await page.locator('#alerts')
+    await expect(res).toHaveText(['Watch stopped'])
+  })
 })

packages/kubernetes-client-example-fetch/tsconfig.json

@@ -4,7 +4,7 @@
     "outDir": "./dist",
     "baseUrl": ".",
     "paths": {
-      "@ccremer/kubernetes-client/*": ["../kubernetes-client/dist/*"]
+      "@ccremer/kubernetes-client/*": ["../kubernetes-client/src/*"]
     }
   },
   "include": ["src/**/*"],

packages/kubernetes-client/package.json

@@ -10,6 +10,7 @@
     "test": "vitest run",
     "clean": "rm -rf types fetch api index.*",
     "build": "rm -rf dist && tsc",
+    "watch": "tsc --watch",
     "prepack": "cp package.json README.md dist/"
   },
   "repository": {

packages/kubernetes-client/src/api/client.ts

@@ -1,5 +1,5 @@
 import { KubeList, KubeObject } from '../types/core'
-import { DeleteOptions, GetOptions, ListOptions, MutationOptions, PatchOptions } from './options'
+import { DeleteOptions, GetOptions, ListOptions, MutationOptions, PatchOptions, WatchOptions } from './options'
 
 export interface ClientWithGet {
   /**
@@ -85,7 +85,7 @@ export interface ClientWithPatch {
 
 export interface ClientWithDelete {
   /**
-   * Deletess the resource identified by the given metadata.
+   * Deletes the resource identified by the given metadata.
    * @param apiVersion case-sensitive API group and version of the resource. E.g. `v1` for core resources, `apps/v1` for "apps" resources.
    * @param kind `kind` of the resource in singular form, case-insensitive.
    * @param name `metadata.name` of the resource
@@ -109,3 +109,73 @@ export interface ClientWithDelete {
    */
   delete<K extends KubeObject>(fromBody: K, options?: DeleteOptions): Promise<void>
 }
+
+export interface WatchEvent<K extends KubeObject> {
+  object: K
+  type: 'ADDED' | 'MODIFIED' | 'DELETED'
+}
+
+export interface WatchHandlers<K extends KubeObject> {
+  /**
+   * Callback function that gets called for each event returned by the `watch` operation.
+   * @param event the event as returned by Kubernetes.
+   */
+  onUpdate: (event: WatchEvent<K>) => void
+  /**
+   * Callback function for any errors occurring in the `watch` operation.
+   * @param err the error payload.
+   * @param effect contains additional information about the error.
+   */
+  onError?: (
+    err: unknown,
+    effect?: {
+      /**
+       * Closed indicates whether the operation has been cancelled, and there won't be any updates anymore.
+       */
+      closed?: boolean
+      /**
+       * Continue indicates whether the operation continues
+       */
+      continue?: boolean
+    }
+  ) => void
+}
+
+export interface WatchResult {
+  abortController: AbortController
+}
+
+export interface ClientWithWatch {
+  /**
+   * Starts a Kubernetes `watch` operation.
+   * @param handlers contains the callback with which the updates are propagated.
+   * @param apiVersion case-sensitive API group and version of the resource. E.g. `v1` for core resources, `apps/v1` for "apps" resources.
+   * @param kind `kind` of the resource in singular form, case-insensitive.
+   * @param name `metadata.name` of the resource.
+   * Note: Watching a single resource doesn't work in Kubernetes, only in lists.
+   * Therefore, you most likely need the `list` RBAC permission along with `watch`.
+   * If a name is given, the callback is only called with updates that match the given `name`(client-side filtering).
+   * @param namespace `metadata.namespace` of the resource, if resource is namespaced.
+   * @param options settings to influence the request.
+   * Consult the Kubernetes API docs for reference.
+   * @return Promise with the {@link WatchResult}.
+   * The Promise is resolved early as soon as the status code is 2xx and contains a body.
+   * It's rejected if the request fails immediately.
+   * Note: Even though the Promise is resolved, the request continues in the background, calling the handler functions.
+   * Use the given {@link WatchResult.abortController} to manually cancel an ongoing watch request.
+   */
+  watchByID<K extends KubeObject>(
+    handlers: WatchHandlers<K>,
+    apiVersion: string,
+    kind: string,
+    name?: string,
+    namespace?: string,
+    options?: WatchOptions
+  ): Promise<WatchResult>
+
+  /**
+   * Starts a Kubernetes `watch` operation, but the object's metadata (apiVersion, kind, name, namespace) is extracted from the given body.
+   * @see watchByID
+   */
+  watch<K extends KubeObject>(handlers: WatchHandlers<K>, fromBody: K, options?: WatchOptions): Promise<WatchResult>
+}

packages/kubernetes-client/src/api/options.ts

@@ -41,3 +41,7 @@ export interface MutationOptions extends CommonOptions {
 export interface PatchOptions extends MutationOptions {
   force?: boolean
 }
+
+export interface WatchOptions extends CommonOptions {
+  allowWatchBookmarks?: boolean
+}

packages/kubernetes-client/src/fetch/builder.ts

@@ -5,6 +5,7 @@ import {
   ClientWithList,
   ClientWithPatch,
   ClientWithUpdate,
+  ClientWithWatch,
   Config,
   KubeConfig,
   KubernetesUrlGenerator,
@@ -19,7 +20,8 @@ export interface Client
     ClientWithList,
     ClientWithDelete,
     ClientWithUpdate,
-    ClientWithPatch {}
+    ClientWithPatch,
+    ClientWithWatch {}
 
 /**
  * KubeClientBuilder constructs a {@link Client} instance using the Fetch API as implementation.