PeprStore, K8s Fluent API & Watch Action

.eslintrc.json

@@ -11,7 +11,7 @@
   },
   "rules": {
     "class-methods-use-this": "warn",
-    "consistent-this":"warn",
+    "consistent-this": "warn",
     "no-invalid-this": "warn",
     "@typescript-eslint/no-floating-promises": ["warn"]
   },
@@ -22,7 +22,10 @@
     "node_modules",
     "dist",
     "hack",
-    "pepr-test-module"
+    "pepr-test-module",
+    "build.mjs",
+    "journey",
+    "__mocks__"
   ],
   "root": true
 }

.npmignore

@@ -9,7 +9,11 @@ adr
 /docs/
 /hack
 build.mjs
-
+/journey
+/__mocks__
+/coverage
+jest.config.json
+/prettierignore
 /dist/cli/**/*.d.*
 /dist/fixtures
 /dist/test

README.md

@@ -12,10 +12,15 @@
 
 Pepr is on a mission to save Kubernetes from the tyranny of YAML, intimidating glue code, bash scripts, and other makeshift solutions. As a Kubernetes controller, Pepr empowers you to define Kubernetes transformations using TypeScript, without software development expertise thanks to plain-english configurations. Pepr transforms a patchwork of forks, scripts, overlays, and other chaos into a cohesive, well-structured, and maintainable system. With Pepr, you can seamlessly transition IT ops tribal knowledge into code, simplifying documentation, testing, validation, and coordination of changes for a more predictable outcome.
 
+#### _Note: Pepr is still in active development so breaking changes may occur, but will be documented in release notes._
+
 ## Features
 
-- Zero-config K8s webhook mutations and validations.
+- Zero-config K8s webhook mutations and validations
+- Automatic leader-elected K8s resource watching
+- Lightweight async key-value store backed by K8s for stateful operations with the [Pepr Store](./docs/store.md)
 - Human-readable fluent API for generating [Pepr Capabilities](#capability)
+- A fluent API for creating/modifying/watching and server-side applying K8s resources via [Kubernetes Fluent Client](https://github.com/defenseunicorns/kubernetes-fluent-client)
 - Generate new K8s resources based off of cluster resource changes
 - Perform other exec/API calls based off of cluster resources changes or any other arbitrary schedule
 - Out of the box airgap support with [Zarf](https://zarf.dev)
@@ -27,7 +32,7 @@ Pepr is on a mission to save Kubernetes from the tyranny of YAML, intimidating g
 
 ## Example Pepr Action
 
-This quick sample shows how to react to a ConfigMap being created or updated in the cluster. It adds a label and annotation to the ConfigMap and adds some data to the ConfigMap. Finally, it logs a message to the Pepr controller logs. For more see [actions](./docs/actions.md).
+This quick sample shows how to react to a ConfigMap being created or updated in the cluster. It adds a label and annotation to the ConfigMap and adds some data to the ConfigMap. It also creates a Validating Webhook to make sure the "pepr" label still exists. Finally, after the ConfigMap is created, it logs a message to the Pepr controller and creates or updates a separate ConfigMap with the [kubernetes-fluent-client](https://github.com/defenseunicorns/kubernetes-fluent-client) using server-side apply. For more details see [actions](./docs/actions.md) section.
 
 ```ts
 When(a.ConfigMap)
@@ -37,7 +42,9 @@ When(a.ConfigMap)
   // Create a Mutate Action for the ConfigMap
   .Mutate(request => {
     // Add a label and annotation to the ConfigMap
-    request.SetLabel("pepr", "was-here").SetAnnotation("pepr.dev", "annotations-work-too");
+    request
+      .SetLabel("pepr", "was-here")
+      .SetAnnotation("pepr.dev", "annotations-work-too");
 
     // Add some data to the ConfigMap
     request.Raw.data["doug-says"] = "Pepr is awesome!";
@@ -54,6 +61,21 @@ When(a.ConfigMap)
 
     // Reject the ConfigMap if it doesn't have the label
     return request.Deny("ConfigMap must have a unicorn label");
+  })
+  // Watch behaves like controller-runtime's Manager.Watch()
+  .Watch(async (cm, phase) => {
+    Log.info(cm, `ConfigMap was ${phase}.`);
+
+    // Apply the ConfigMap using K8s server-side apply
+    await K8s(kind.ConfigMap).Apply({
+      metadata: {
+        name: "pepr-ssa-demo",
+        namespace: "pepr-demo-2",
+      },
+      data: {
+        uid: cm.metadata.uid,
+      },
+    });
   });
 ```
 
@@ -104,7 +126,7 @@ Action is a discrete set of behaviors defined in a single function that acts on
 
 For example, an action could be responsible for adding a specific label to a Kubernetes resource, or for modifying a specific field in a resource's metadata. Actions can be grouped together within a Capability to provide a more comprehensive set of operations that can be performed on Kubernetes resources.
 
-There are both `Mutate()` and `Validate()` Actions that can be used to modify or validate Kubernetes resources.
+There are both `Mutate()` and `Validate()` Actions that can be used to modify or validate Kubernetes resources within the admission controller lifecycle. There is also a `Watch()` Action that can be used to watch for changes to Kubernetes resources that already exist.
 
 See [actions](./docs/actions.md) for more details.
 
@@ -116,4 +138,3 @@ See [actions](./docs/actions.md) for more details.
 ## TypeScript
 
 [TypeScript](https://www.typescriptlang.org/) is a strongly typed, object-oriented programming language built on top of JavaScript. It provides optional static typing and a rich type system, allowing developers to write more robust code. TypeScript is transpiled to JavaScript, enabling it to run in any environment that supports JavaScript. Pepr allows you to use JavaScript or TypeScript to write capabilities, but TypeScript is recommended for its type safety and rich type system. You can learn more about TypeScript [here](https://www.typescriptlang.org/docs/handbook/typescript-from-scratch.html).
-

__mocks__/pino.ts

@@ -0,0 +1,10 @@
+import { jest } from "@jest/globals";
+
+export const pino = () => {
+  return {
+    info: jest.fn(),
+    error: jest.fn(),
+    warn: jest.fn(),
+    debug: jest.fn(),
+  };
+};

build.mjs

@@ -5,7 +5,7 @@ import { analyzeMetafile, build } from "esbuild";
 import packageJSON from "./package.json" assert { type: "json" };
 
 const { dependencies, peerDependencies } = packageJSON;
-const external = Object.keys(dependencies).concat(Object.keys(peerDependencies));
+const external = Object.keys(dependencies).concat(Object.keys(peerDependencies), "@kubernetes/client-node");
 
 const buildOpts = {
   bundle: true,

docs/actions.md

@@ -4,7 +4,7 @@ An action is a discrete set of behaviors defined in a single function that acts
 
 For example, an action could be responsible for adding a specific label to a Kubernetes resource, or for modifying a specific field in a resource's metadata. Actions can be grouped together within a Capability to provide a more comprehensive set of operations that can be performed on Kubernetes resources.
 
-Actions are either `Mutate()` or `Validate()` actions. Mutate actions are used to modify Kubernetes resources, while Validate actions are used to validate Kubernetes resources.
+Actions are `Mutate()`, `Validate()`, or `Watch()`. Both Mutate and Validate actions run during the admission controller lifecycle, while Watch actions run in a separate controller that tracks changes to resources, including existing resources.
 
 Let's look at some example actions that are included in the `HelloPepr` capability that is created for you when you [`pepr init`](./cli.md#pepr-init):
 
@@ -52,6 +52,18 @@ When(a.ConfigMap)
   });
 ```
 
+---
+
+In this example, a Watch action on the name and phase of any ConfigMap.
+
+```ts
+When(a.ConfigMap)
+  // Watch() is where we define the actual behavior of this action.
+  .Watch((cm, phase) => {
+    Log.info(cm, `ConfigMap ${cm.metadata.name} was ${phase}`);
+  });
+```
+
 ```
 There are many more examples in the `HelloPepr` capability that you can use as a reference when creating your own actions. Note that each time you run [`pepr update`](./cli.md#pepr-update), Pepr will automatically update the `HelloPepr` capability with the latest examples and best practices for you to reference and test directly in your Pepr Module.
 ```

docs/store.md

@@ -0,0 +1,42 @@
+# Pepr Store: A Lightweight Key-Value Store for Pepr Modules
+
+The nature of admission controllers and general watch operations (the `Mutate`, `Validate` and `Watch` actions in Pepr) make some types of complex and long-running operations difficult. There are also times when you need to share data between different actions. While you could manually create your own K8s resources and manage their cleanup, this can be very hard to track and keep performant at scale. 
+
+The Pepr Store solves this by exposing a simple, [Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Storage)-compatible mechanism for use within capabilities. Additionally, as Pepr runs multiple replicas of the admission controller along with a watch controller, the Pepr Store provides a unique way to share data between these different instances automatically.
+
+Each Pepr Capability has a `Store` instance that can be used to get, set and delete data as well as subscribe to any changes to the Store. Behind the scenes, all capability store instances in a single Pepr Module are stored within a single CRD in the cluster. This CRD is automatically created when the Pepr Module is deployed. Care is taken to make the read and write operations as efficient as possible by using K8s watches, batch processing and patch operations for writes.
+
+## Key Features
+
+- **Asynchronous Key-Value Store**: Provides an asynchronous interface for storing small amounts of data, making it ideal for sharing information between various actions and capabilities.
+- **Web Storage API Compatibility**: The store's API is aligned with the standard [Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Storage), simplifying the learning curve.
+- **Real-time Updates**: The `.subscribe()` and `onReady()` methods enable real-time updates, allowing you to react to changes in the data store instantaneously.
+
+- **Automatic CRD Management**: Each Pepr Module has its data stored within a single Custom Resource Definition (CRD) that is automatically created upon deployment.
+- **Efficient Operations**: Pepr Store uses Kubernetes watches, batch processing, and patch operations to make read and write operations as efficient as possible.
+
+## Quick Start
+
+```typescript
+// Example usage for Pepr Store
+Store.setItem("example-1", "was-here");
+Store.setItem("example-1-data", JSON.stringify(request.Raw.data));
+Store.onReady(data => {
+  Log.info(data, "Pepr Store Ready");
+});
+const unsubscribe = Store.subscribe(data => {
+  Log.info(data, "Pepr Store Updated");
+  unsubscribe();
+});
+```
+
+## API Reference
+
+### Methods
+
+- `getItem(key: string)`: Retrieves a value by its key. Returns `null` if the key doesn't exist.
+- `setItem(key: string, value: string)`: Sets a value for a given key. Creates a new key-value pair if the key doesn't exist.
+- `removeItem(key: string)`: Deletes a key-value pair by its key.
+- `clear()`: Clears all key-value pairs from the store.
+- `subscribe(listener: DataReceiver)`: Subscribes to store updates.
+- `onReady(callback: DataReceiver)`: Executes a callback when the store is ready.

journey/entrypoint.test.ts

@@ -10,6 +10,9 @@ import { peprDev } from "./pepr-dev";
 import { peprFormat } from "./pepr-format";
 import { peprInit } from "./pepr-init";
 
+// Unmock unit test things
+jest.deepUnmock("pino");
+
 // The working directory for the tests after `npx pepr init` is run
 export const cwd = "pepr-test-module";
 

journey/k8s.ts

@@ -1,52 +1,50 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
-import { AppsV1Api, CoreV1Api, KubeConfig, V1ConfigMap } from "@kubernetes/client-node";
+import { K8s, kind } from "kubernetes-fluent-client";
 
-const kc = new KubeConfig();
-kc.loadFromDefault();
+import { PeprStore } from "../src/lib/k8s";
 
-const k8sApi = kc.makeApiClient(AppsV1Api);
-const k8sCoreApi = kc.makeApiClient(CoreV1Api);
-
-function delay2Secs() {
-  return new Promise(resolve => setTimeout(resolve, 2000));
-}
-
-export async function createOrReplaceConfigMap(cm: V1ConfigMap) {
-  const ns = cm.metadata?.namespace || "default";
-  try {
-    const resp = await k8sCoreApi.createNamespacedConfigMap(ns, cm);
-    return resp.body;
-  } catch (error) {
-    const resp = await k8sCoreApi.replaceNamespacedConfigMap(cm.metadata?.name || "", ns, cm);
-    return resp.body;
-  }
+export function sleep(seconds: number) {
+  return new Promise(resolve => setTimeout(resolve, seconds*1000));
 }
 
 export async function deleteConfigMap(namespace: string, name: string) {
   try {
-    await k8sCoreApi.deleteNamespacedConfigMap(name, namespace);
+    await K8s(kind.ConfigMap).InNamespace(namespace).Delete(name);
   } catch (error) {
     // Do nothing
   }
 }
 
 export async function waitForDeploymentReady(namespace: string, name: string) {
-  const deployment = await k8sApi.readNamespacedDeployment(name, namespace);
-  const replicas = deployment.body.spec?.replicas || 1;
-  const readyReplicas = deployment.body.status?.readyReplicas || 0;
+  const deployment = await K8s(kind.Deployment).InNamespace(namespace).Get(name);
+  const replicas = deployment.spec?.replicas || 1;
+  const readyReplicas = deployment.status?.readyReplicas || 0;
 
   if (replicas !== readyReplicas) {
     await delay2Secs();
     return waitForDeploymentReady(namespace, name);
   }
 }
 
+export async function waitForPeprStoreKey(name: string, matchKey: string) {
+  try {
+    const store = await K8s(PeprStore).InNamespace("pepr-system").Get(name);
+    if (store.data[matchKey]) {
+      return store.data[matchKey];
+    }
+
+    throw new Error("Key not found");
+  } catch (error) {
+    await delay2Secs();
+    return waitForPeprStoreKey(name, matchKey);
+  }
+}
+
 export async function waitForNamespace(namespace: string) {
   try {
-    const resp = await k8sCoreApi.readNamespace(namespace);
-    return resp.body;
+    return await K8s(kind.Namespace).Get(namespace);
   } catch (error) {
     await delay2Secs();
     return waitForNamespace(namespace);
@@ -55,8 +53,7 @@ export async function waitForNamespace(namespace: string) {
 
 export async function waitForConfigMap(namespace: string, name: string) {
   try {
-    const resp = await k8sCoreApi.readNamespacedConfigMap(name, namespace);
-    return resp.body;
+    return await K8s(kind.ConfigMap).InNamespace(namespace).Get(name);
   } catch (error) {
     await delay2Secs();
     return waitForConfigMap(namespace, name);
@@ -65,36 +62,9 @@ export async function waitForConfigMap(namespace: string, name: string) {
 
 export async function waitForSecret(namespace: string, name: string) {
   try {
-    const resp = await k8sCoreApi.readNamespacedSecret(name, namespace);
-    return resp.body;
+    return await K8s(kind.Secret).InNamespace(namespace).Get(name);
   } catch (error) {
     await delay2Secs();
     return waitForSecret(namespace, name);
   }
 }
-
-export async function getPodLogs(namespace: string, labelSelector: string) {
-  let allLogs = "";
-
-  try {
-    const res = await k8sCoreApi.listNamespacedPod(
-      namespace,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      labelSelector,
-    );
-    const pods = res.body.items;
-
-    for (const pod of pods) {
-      const podName = pod.metadata?.name || "unknown";
-      const log = await k8sCoreApi.readNamespacedPodLog(podName, namespace);
-      allLogs += log.body;
-    }
-  } catch (err) {
-    console.error("Error: ", err);
-  }
-
-  return allLogs;
-}