pepr 0.13.2 → 0.13.3

package/package.json

@@ -9,7 +9,7 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "version": "0.13.2",
+  "version": "0.13.3",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
   "scripts": {
@@ -32,7 +32,7 @@
     "fast-json-patch": "3.1.1",
     "http-status-codes": "2.2.0",
     "node-fetch": "2.7.0",
-    "pino": "8.15.0",
+    "pino": "8.15.1",
     "pino-pretty": "10.2.0",
     "prom-client": "14.2.0",
     "ramda": "0.29.0"

package/src/lib/filter.ts

@@ -12,13 +12,14 @@ import { Binding, Event } from "./types";
  * @param req the incoming request
  * @returns
  */
-export function shouldSkipRequest(binding: Binding, req: Request) {
+export function shouldSkipRequest(binding: Binding, req: Request, capabilityNamespaces: string[]) {
   const { group, kind, version } = binding.kind || {};
   const { namespaces, labels, annotations, name } = binding.filters || {};
   const operation = req.operation.toUpperCase();
   // Use the old object if the request is a DELETE operation
   const srcObject = operation === Operation.DELETE ? req.oldObject : req.object;
   const { metadata } = srcObject || {};
+  const combinedNamespaces = [...namespaces, ...capabilityNamespaces];
 
   // Test for matching operation
   if (!binding.event.includes(operation) && !binding.event.includes(Event.Any)) {
@@ -46,7 +47,7 @@ export function shouldSkipRequest(binding: Binding, req: Request) {
   }
 
   // Test for matching namespaces
-  if (namespaces.length && !namespaces.includes(req.namespace || "")) {
+  if (combinedNamespaces.length && !combinedNamespaces.includes(req.namespace || "")) {
     logger.debug("Namespace does not match");
     return true;
   }

package/src/lib/mutate-processor.ts

@@ -40,7 +40,7 @@ export async function mutateProcessor(
 
   Log.info(reqMetadata, `Processing request`);
 
-  for (const { name, bindings } of capabilities) {
+  for (const { name, bindings, namespaces } of capabilities) {
     const actionMetadata = { ...reqMetadata, name };
 
     for (const action of bindings) {
@@ -50,7 +50,7 @@ export async function mutateProcessor(
       }
 
       // Continue to the next action without doing anything if this one should be skipped
-      if (shouldSkipRequest(action, req)) {
+      if (shouldSkipRequest(action, req, namespaces)) {
         continue;
       }
 

package/src/lib/validate-processor.ts

@@ -28,7 +28,7 @@ export async function validateProcessor(
 
   Log.info(reqMetadata, `Processing validation request`);
 
-  for (const { name, bindings } of capabilities) {
+  for (const { name, bindings, namespaces } of capabilities) {
     const actionMetadata = { ...reqMetadata, name };
 
     for (const action of bindings) {
@@ -38,7 +38,7 @@ export async function validateProcessor(
       }
 
       // Continue to the next action without doing anything if this one should be skipped
-      if (shouldSkipRequest(action, req)) {
+      if (shouldSkipRequest(action, req, namespaces)) {
         continue;
       }
 

package/src/runtime/controller.ts

@@ -9,7 +9,7 @@ import fs from "fs";
 import { gunzipSync } from "zlib";
 
 import Log from "../lib/logger";
-import { packageJSON } from "../cli/init/templates/data.json";
+import { packageJSON } from "../templates/data.json";
 
 const { version } = packageJSON;
 

package/src/templates/.prettierrc.json

@@ -0,0 +1,13 @@
+{
+  "arrowParens": "avoid",
+  "bracketSameLine": false,
+  "bracketSpacing": true,
+  "embeddedLanguageFormatting": "auto",
+  "insertPragma": false,
+  "printWidth": 80,
+  "quoteProps": "as-needed",
+  "requirePragma": false,
+  "semi": true,
+  "tabWidth": 2,
+  "useTabs": false
+}

package/src/templates/README.md

@@ -0,0 +1,21 @@
+# Pepr Module
+
+This is a Pepr Module. [Pepr](https://github.com/defenseunicorns/pepr) is a type-safe Kubernetes middleware system.
+
+The `capabilities` directory contains all the capabilities for this module. By default,
+a capability is a single typescript file in the format of `capability-name.ts` that is
+imported in the root `pepr.ts` file as `import { HelloPepr } from "./capabilities/hello-pepr";`.
+Because this is typescript, you can organize this however you choose, e.g. creating a sub-folder
+per-capability or common logic in shared files or folders.
+
+Example Structure:
+
+```
+Module Root
+├── package.json
+├── pepr.ts
+└── capabilities
+    ├── example-one.ts
+    ├── example-three.ts
+    └── example-two.ts
+```

package/src/templates/capabilities/hello-pepr.samples.json

@@ -0,0 +1,160 @@
+[
+  {
+    "apiVersion": "v1",
+    "kind": "Namespace",
+    "metadata": {
+      "name": "pepr-demo",
+      "labels": {
+        "keep-me": "please",
+        "remove-me": "please"
+      }
+    }
+  },
+  {
+    "apiVersion": "v1",
+    "kind": "Namespace",
+    "metadata": {
+      "name": "pepr-demo-2"
+    }
+  },
+  {
+    "apiVersion": "v1",
+    "kind": "Secret",
+    "metadata": {
+      "name": "secret-1",
+      "namespace": "pepr-demo"
+    },
+    "data": {
+      "example": "dW5pY29ybiBtYWdpYw==",
+      "binary-data": "iCZQUg8xYucNUqD+8lyl2YcKjYYygvTtiDSEV9b9WKUkxSSLFJTgIWMJ9GcFFYs4T9JCdda51u74jfq8yHzRuEASl60EdTS/NfWgIIFTGqcNRfqMw+vgpyTMmCyJVaJEDFq6AA==",
+      "ascii-with-white-space": "VGhpcyBpcyBzb21lIHJhbmRvbSB0ZXh0OgoKICAgIC0gd2l0aCBsaW5lIGJyZWFrcwogICAgLSBhbmQgdGFicw=="
+    }
+  },
+  {
+    "apiVersion": "v1",
+    "kind": "ConfigMap",
+    "metadata": {
+      "name": "example-1",
+      "namespace": "pepr-demo"
+    },
+    "data": {
+      "key": "ex-1-val"
+    }
+  },
+  {
+    "apiVersion": "v1",
+    "kind": "ConfigMap",
+    "metadata": {
+      "name": "example-2",
+      "namespace": "pepr-demo"
+    },
+    "data": {
+      "key": "ex-2-val"
+    }
+  },
+  {
+    "apiVersion": "v1",
+    "kind": "ConfigMap",
+    "metadata": {
+      "name": "example-evil-cm",
+      "namespace": "pepr-demo",
+      "annotations": {
+        "evil": "true"
+      }
+    },
+    "data": {
+      "key": "ex-evil-cm-val"
+    }
+  },
+  {
+    "apiVersion": "v1",
+    "kind": "ConfigMap",
+    "metadata": {
+      "name": "example-3",
+      "namespace": "pepr-demo",
+      "labels": {
+        "change": "by-label"
+      }
+    },
+    "data": {
+      "key": "ex-3-val"
+    }
+  },
+  {
+    "apiVersion": "v1",
+    "kind": "ConfigMap",
+    "metadata": {
+      "name": "example-4",
+      "namespace": "pepr-demo"
+    },
+    "data": {
+      "key": "ex-4-val"
+    }
+  },
+  {
+    "apiVersion": "v1",
+    "kind": "ConfigMap",
+    "metadata": {
+      "name": "example-4a",
+      "namespace": "pepr-demo-2"
+    },
+    "data": {
+      "key": "ex-4-val"
+    }
+  },
+  {
+    "apiVersion": "v1",
+    "kind": "ConfigMap",
+    "metadata": {
+      "name": "example-5",
+      "namespace": "pepr-demo",
+      "labels": {
+        "chuck-norris": "test"
+      }
+    },
+    "data": {
+      "key": "ex-5-val"
+    }
+  },
+  {
+    "apiVersion": "apiextensions.k8s.io/v1",
+    "kind": "CustomResourceDefinition",
+    "metadata": {
+      "name": "unicorns.pepr.dev"
+    },
+    "spec": {
+      "group": "pepr.dev",
+      "versions": [
+        {
+          "name": "v1",
+          "served": true,
+          "storage": true,
+          "schema": {
+            "openAPIV3Schema": {
+              "type": "object",
+              "properties": {
+                "spec": {
+                  "type": "object",
+                  "properties": {
+                    "message": {
+                      "type": "string"
+                    },
+                    "counter": {
+                      "type": "number"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      ],
+      "scope": "Namespaced",
+      "names": {
+        "plural": "unicorns",
+        "singular": "unicorn",
+        "kind": "Unicorn"
+      }
+    }
+  }
+]

package/src/templates/capabilities/hello-pepr.ts

@@ -0,0 +1,372 @@
+import {
+  Capability,
+  Log,
+  PeprMutateRequest,
+  RegisterKind,
+  a,
+  fetch,
+  fetchStatus,
+} from "pepr";
+
+/**
+ *  The HelloPepr Capability is an example capability to demonstrate some general concepts of Pepr.
+ *  To test this capability you run `pepr dev`and then run the following command:
+ *  `kubectl apply -f capabilities/hello-pepr.samples.yaml`
+ */
+export const HelloPepr = new Capability({
+  name: "hello-pepr",
+  description: "A simple example capability to show how things work.",
+  namespaces: ["pepr-demo", "pepr-demo-2"],
+});
+
+// Use the 'When' function to create a new Action
+const { When } = HelloPepr;
+
+/**
+ * ---------------------------------------------------------------------------------------------------
+ *                                   Mutate Action (Namespace)                                   *
+ * ---------------------------------------------------------------------------------------------------
+ *
+ * This action removes the label `remove-me` when a Namespace is created.
+ * Note we don't need to specify the namespace here, because we've already specified
+ * it in the Capability definition above.
+ */
+When(a.Namespace)
+  .IsCreated()
+  .Mutate(ns => ns.RemoveLabel("remove-me"));
+
+/**
+ * ---------------------------------------------------------------------------------------------------
+ *                                   Mutate Action (CM Example 1)                                *
+ * ---------------------------------------------------------------------------------------------------
+ *
+ * This is a single action. They can be in the same file or put imported from other files.
+ * In this example, when a ConfigMap is created with the name `example-1`, then add a label and annotation.
+ *
+ * Equivalent to manually running:
+ * `kubectl label configmap example-1 pepr=was-here`
+ * `kubectl annotate configmap example-1 pepr.dev=annotations-work-too`
+ */
+When(a.ConfigMap)
+  .IsCreated()
+  .WithName("example-1")
+  .Mutate(request => {
+    request
+      .SetLabel("pepr", "was-here")
+      .SetAnnotation("pepr.dev", "annotations-work-too");
+  });
+
+/**
+ * ---------------------------------------------------------------------------------------------------
+ *                                   Mutate & Validate Actions (CM Example 2)                                *
+ * ---------------------------------------------------------------------------------------------------
+ *
+ * This combines 2 different types of actions: 'Mutate', and 'Validate'. The order
+ * of the actions is required, but each action is optional. In this example, when a ConfigMap is created
+ * with the name `example-2`, then add a label and annotation and finally validate that the ConfigMap has the label
+ * `pepr`.
+ */
+When(a.ConfigMap)
+  .IsCreated()
+  .WithName("example-2")
+  .Mutate(request => {
+    // This Mutate Action will mutate the request before it is persisted to the cluster
+
+    // Use `request.Merge()` to merge the new data with the existing data
+    request.Merge({
+      metadata: {
+        labels: {
+          pepr: "was-here",
+        },
+        annotations: {
+          "pepr.dev": "annotations-work-too",
+        },
+      },
+    });
+  })
+  .Validate(request => {
+    // This Validate Action will validate the request before it is persisted to the cluster
+
+    // Approve the request if the ConfigMap has the label 'pepr'
+    if (request.HasLabel("pepr")) {
+      return request.Approve();
+    }
+
+    // Otherwise, deny the request with an error message (optional)
+    return request.Deny("ConfigMap must have label 'pepr'");
+  });
+
+/**
+ * ---------------------------------------------------------------------------------------------------
+ *                                   Mutate Action (CM Example 2a)                               *
+ * ---------------------------------------------------------------------------------------------------
+ *
+ * This action shows a simple validation that will deny any ConfigMap that has the
+ * annotation `evil`. Note that the `Deny()` function takes an optional second parameter that is a
+ * user-defined status code to return.
+ */
+When(a.ConfigMap)
+  .IsCreated()
+  .Validate(request => {
+    if (request.HasAnnotation("evil")) {
+      return request.Deny("No evil CM annotations allowed.", 400);
+    }
+
+    return request.Approve();
+  });
+
+/**
+ * ---------------------------------------------------------------------------------------------------
+ *                                   Mutate Action (CM Example 3)                                *
+ * ---------------------------------------------------------------------------------------------------
+ *
+ * This action combines different styles. Unlike the previous actions, this one will look
+ * for any ConfigMap in the `pepr-demo` namespace that has the label `change=by-label` during either
+ * CREATE or UPDATE. Note that all conditions added such as `WithName()`, `WithLabel()`, `InNamespace()`,
+ * are ANDs so all conditions must be true for the request to be processed.
+ */
+When(a.ConfigMap)
+  .IsCreatedOrUpdated()
+  .WithLabel("change", "by-label")
+  .Mutate(request => {
+    // The K8s object e are going to mutate
+    const cm = request.Raw;
+
+    // Get the username and uid of the K8s request
+    const { username, uid } = request.Request.userInfo;
+
+    // Store some data about the request in the configmap
+    cm.data["username"] = username;
+    cm.data["uid"] = uid;
+
+    // You can still mix other ways of making changes too
+    request.SetAnnotation("pepr.dev", "making-waves");
+  });
+
+// This action validates the label `change=by-label` is deleted
+When(a.ConfigMap)
+  .IsDeleted()
+  .WithLabel("change", "by-label")
+  .Validate(request => {
+    // Log and then always approve the request
+    Log.info("CM with label 'change=by-label' was deleted.");
+    return request.Approve();
+  });
+
+/**
+ * ---------------------------------------------------------------------------------------------------
+ *                                   Mutate Action (CM Example 4)                                *
+ * ---------------------------------------------------------------------------------------------------
+ *
+ * This action show how you can use the `Mutate()` function without an inline function.
+ * This is useful if you want to keep your actions small and focused on a single task,
+ * or if you want to reuse the same function in multiple actions.
+ */
+When(a.ConfigMap).IsCreated().WithName("example-4").Mutate(example4Cb);
+
+// This function uses the complete type definition, but is not required.
+function example4Cb(cm: PeprMutateRequest<a.ConfigMap>) {
+  cm.SetLabel("pepr.dev/first", "true");
+  cm.SetLabel("pepr.dev/second", "true");
+  cm.SetLabel("pepr.dev/third", "true");
+}
+
+/**
+ * ---------------------------------------------------------------------------------------------------
+ *                                   Mutate Action (CM Example 4a)                                *
+ * ---------------------------------------------------------------------------------------------------
+ *
+ * This is the same as Example 4, except this only operates on a CM in the `pepr-demo-2` namespace.
+ * Note because the Capability defines namespaces, the namespace specified here must be one of those.
+ * Alternatively, you can remove the namespace from the Capability definition and specify it here.
+ */
+When(a.ConfigMap)
+  .IsCreated()
+  .InNamespace("pepr-demo-2")
+  .WithName("example-4a")
+  .Mutate(example4Cb);
+
+/**
+ * ---------------------------------------------------------------------------------------------------
+ *                                   Mutate Action (CM Example 5)                                *
+ * ---------------------------------------------------------------------------------------------------
+ *
+ * This action is a bit more complex. It will look for any ConfigMap in the `pepr-demo`
+ * namespace that has the label `chuck-norris` during CREATE. When it finds one, it will fetch a
+ * random Chuck Norris joke from the API and add it to the ConfigMap. This is a great example of how
+ * you can use Pepr to make changes to your K8s objects based on external data.
+ *
+ * Note the use of the `async` keyword. This is required for any action that uses `await` or `fetch()`.
+ *
+ * Also note we are passing a type to the `fetch()` function. This is optional, but it will help you
+ * avoid mistakes when working with the data returned from the API. You can also use the `as` keyword to
+ * cast the data returned from the API.
+ *
+ * These are equivalent:
+ * ```ts
+ * const joke = await fetch<TheChuckNorrisJoke>("https://api.chucknorris.io/jokes/random?category=dev");
+ * const joke = await fetch("https://api.chucknorris.io/jokes/random?category=dev") as TheChuckNorrisJoke;
+ * ```
+ *
+ * Alternatively, you can drop the type completely:
+ *
+ * ```ts
+ * fetch("https://api.chucknorris.io/jokes/random?category=dev")
+ * ```
+ */
+interface TheChuckNorrisJoke {
+  icon_url: string;
+  id: string;
+  url: string;
+  value: string;
+}
+
+When(a.ConfigMap)
+  .IsCreated()
+  .WithLabel("chuck-norris")
+  .Mutate(async change => {
+    // Try/catch is not needed as a response object will always be returned
+    const response = await fetch<TheChuckNorrisJoke>(
+      "https://api.chucknorris.io/jokes/random?category=dev",
+    );
+
+    // Instead, check the `response.ok` field
+    if (response.ok) {
+      // Add the Chuck Norris joke to the configmap
+      change.Raw.data["chuck-says"] = response.data.value;
+      return;
+    }
+
+    // You can also assert on different HTTP response codes
+    if (response.status === fetchStatus.NOT_FOUND) {
+      // Do something else
+      return;
+    }
+  });
+
+/**
+ * ---------------------------------------------------------------------------------------------------
+ *                                   Mutate Action (Secret Base64 Handling)                      *
+ * ---------------------------------------------------------------------------------------------------
+ *
+ * The K8s JS client provides incomplete support for base64 encoding/decoding handling for secrets,
+ * unlike the GO client. To make this less painful, Pepr automatically handles base64 encoding/decoding
+ * secret data before and after the action is executed.
+ */
+When(a.Secret)
+  .IsCreated()
+  .WithName("secret-1")
+  .Mutate(request => {
+    const secret = request.Raw;
+
+    // This will be encoded at the end of all processing back to base64: "Y2hhbmdlLXdpdGhvdXQtZW5jb2Rpbmc="
+    secret.data.magic = "change-without-encoding";
+
+    // You can modify the data directly, and it will be encoded at the end of all processing
+    secret.data.example += " - modified by Pepr";
+  });
+
+/**
+ * ---------------------------------------------------------------------------------------------------
+ *                                   Mutate Action (Untyped Custom Resource)                     *
+ * ---------------------------------------------------------------------------------------------------
+ *
+ * Out of the box, Pepr supports all the standard Kubernetes objects. However, you can also create
+ * your own types. This is useful if you are working with an Operator that creates custom resources.
+ * There are two ways to do this, the first is to use the `When()` function with a `GenericKind`,
+ * the second is to create a new class that extends `GenericKind` and use the `RegisterKind()` function.
+ *
+ * This example shows how to use the `When()` function with a `GenericKind`. Note that you
+ * must specify the `group`, `version`, and `kind` of the object (if applicable). This is how Pepr knows
+ * if the action should be triggered or not. Since we are using a `GenericKind`,
+ * Pepr will not be able to provide any intellisense for the object, so you will need to refer to the
+ * Kubernetes API documentation for the object you are working with.
+ *
+ * You will need to wait for the CRD in `hello-pepr.samples.yaml` to be created, then you can apply
+ *
+ * ```yaml
+ * apiVersion: pepr.dev/v1
+ * kind: Unicorn
+ * metadata:
+ *   name: example-1
+ *   namespace: pepr-demo
+ * spec:
+ *   message: replace-me
+ *   counter: 0
+ * ```
+ */
+When(a.GenericKind, {
+  group: "pepr.dev",
+  version: "v1",
+  kind: "Unicorn",
+})
+  .IsCreated()
+  .WithName("example-1")
+  .Mutate(request => {
+    request.Merge({
+      spec: {
+        message: "Hello Pepr without type data!",
+        counter: Math.random(),
+      },
+    });
+  });
+
+/**
+ * ---------------------------------------------------------------------------------------------------
+ *                                   Mutate Action (Typed Custom Resource)                       *
+ * ---------------------------------------------------------------------------------------------------
+ *
+ * This example shows how to use the `RegisterKind()` function to create a new type. This is useful
+ * if you are working with an Operator that creates custom resources and you want to have intellisense
+ * for the object. Note that you must specify the `group`, `version`, and `kind` of the object (if applicable)
+ * as this is how Pepr knows if the action should be triggered or not.
+ *
+ * Once you register a new Kind with Pepr, you can use the `When()` function with the new Kind. Ideally,
+ * you should register custom Kinds at the top of your Capability file or Pepr Module so they are available
+ * to all actions, but we are putting it here for demonstration purposes.
+ *
+ * You will need to wait for the CRD in `hello-pepr.samples.yaml` to be created, then you can apply
+ *
+ * ```yaml
+ * apiVersion: pepr.dev/v1
+ * kind: Unicorn
+ * metadata:
+ *   name: example-2
+ *   namespace: pepr-demo
+ * spec:
+ *   message: replace-me
+ *   counter: 0
+ * ```*
+ */
+class UnicornKind extends a.GenericKind {
+  spec: {
+    /**
+     * JSDoc comments can be added to explain more details about the field.
+     *
+     * @example
+     * ```ts
+     * request.Raw.spec.message = "Hello Pepr!";
+     * ```
+     * */
+    message: string;
+    counter: number;
+  };
+}
+
+RegisterKind(UnicornKind, {
+  group: "pepr.dev",
+  version: "v1",
+  kind: "Unicorn",
+});
+
+When(UnicornKind)
+  .IsCreated()
+  .WithName("example-2")
+  .Mutate(request => {
+    request.Merge({
+      spec: {
+        message: "Hello Pepr with type data!",
+        counter: Math.random(),
+      },
+    });
+  });

package/src/templates/gitignore

@@ -0,0 +1,4 @@
+# Ignore node_modules and Pepr build artifacts
+node_modules
+dist
+insecure*

package/src/templates/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "pepr-dev-module",
+  "description": "static test package.json for local pepr core development",
+  "pepr": {
+    "name": "Development Module",
+    "uuid": "20e17cf6-a2e4-46b2-b626-75d88d96c88b",
+    "description": "Development module for pepr",
+    "onError": "ignore",
+    "alwaysIgnore": {
+      "namespaces": [],
+      "labels": []
+    }
+  }
+}