pepr 0.0.0-development

package/src/lib/validate-request.ts

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+/* eslint-disable class-methods-use-this */
+
+import { KubernetesObject } from "kubernetes-fluent-client";
+
+import { clone } from "ramda";
+import { Operation, AdmissionRequest } from "./k8s";
+import { ValidateActionResponse } from "./types";
+
+/**
+ * The RequestWrapper class provides methods to modify Kubernetes objects in the context
+ * of a mutating webhook request.
+ */
+export class PeprValidateRequest<T extends KubernetesObject> {
+  Raw: T;
+
+  #input: AdmissionRequest<T>;
+
+  /**
+   * Provides access to the old resource in the request if available.
+   * @returns The old Kubernetes resource object or null if not available.
+   */
+  get OldResource() {
+    return this.#input.oldObject;
+  }
+
+  /**
+   * Provides access to the request object.
+   * @returns The request object containing the Kubernetes resource.
+   */
+  get Request() {
+    return this.#input;
+  }
+
+  /**
+   * Creates a new instance of the Action class.
+   * @param input - The request object containing the Kubernetes resource to modify.
+   */
+  constructor(input: AdmissionRequest<T>) {
+    this.#input = input;
+
+    // If this is a DELETE operation, use the oldObject instead
+    if (input.operation.toUpperCase() === Operation.DELETE) {
+      this.Raw = clone(input.oldObject as T);
+    } else {
+      // Otherwise, use the incoming object
+      this.Raw = clone(input.object);
+    }
+
+    if (!this.Raw) {
+      throw new Error("unable to load the request object into PeprRequest.Raw");
+    }
+  }
+
+  /**
+   * Check if a label exists on the Kubernetes resource.
+   *
+   * @param key the label key to check
+   * @returns
+   */
+  HasLabel = (key: string) => {
+    return this.Raw.metadata?.labels?.[key] !== undefined;
+  };
+
+  /**
+   * Check if an annotation exists on the Kubernetes resource.
+   *
+   * @param key the annotation key to check
+   * @returns
+   */
+  HasAnnotation = (key: string) => {
+    return this.Raw.metadata?.annotations?.[key] !== undefined;
+  };
+
+  /**
+   * Create a validation response that allows the request.
+   *
+   * @returns The validation response.
+   */
+  Approve = (): ValidateActionResponse => {
+    return {
+      allowed: true,
+    };
+  };
+
+  /**
+   * Create a validation response that denies the request.
+   *
+   * @param statusMessage Optional status message to return to the user.
+   * @param statusCode Optional status code to return to the user.
+   * @returns The validation response.
+   */
+  Deny = (statusMessage?: string, statusCode?: number): ValidateActionResponse => {
+    return {
+      allowed: false,
+      statusCode,
+      statusMessage,
+    };
+  };
+}

package/src/lib/watch-processor.ts

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+import { K8s, KubernetesObject, WatchCfg, WatchEvent } from "kubernetes-fluent-client";
+import { WatchPhase } from "kubernetes-fluent-client/dist/fluent/types";
+import { Capability } from "./capability";
+import { filterNoMatchReason } from "./helpers";
+import Log from "./logger";
+import { Queue } from "./queue";
+import { Binding, Event } from "./types";
+
+// Watch configuration
+const watchCfg: WatchCfg = {
+  retryMax: process.env.PEPR_RETRYMAX ? parseInt(process.env.PEPR_RETRYMAX, 10) : 5,
+  retryDelaySec: process.env.PEPR_RETRYDELAYSECONDS ? parseInt(process.env.PEPR_RETRYDELAYSECONDS, 10) : 5,
+  resyncIntervalSec: process.env.PEPR_RESYNCINTERVALSECONDS
+    ? parseInt(process.env.PEPR_RESYNCINTERVALSECONDS, 10)
+    : 300,
+};
+
+// Map the event to the watch phase
+const eventToPhaseMap = {
+  [Event.Create]: [WatchPhase.Added],
+  [Event.Update]: [WatchPhase.Modified],
+  [Event.CreateOrUpdate]: [WatchPhase.Added, WatchPhase.Modified],
+  [Event.Delete]: [WatchPhase.Deleted],
+  [Event.Any]: [WatchPhase.Added, WatchPhase.Modified, WatchPhase.Deleted],
+};
+
+/**
+ * Entrypoint for setting up watches for all capabilities
+ *
+ * @param capabilities The capabilities to load watches for
+ */
+export function setupWatch(capabilities: Capability[]) {
+  capabilities.map(capability =>
+    capability.bindings
+      .filter(binding => binding.isWatch)
+      .forEach(bindingElement => runBinding(bindingElement, capability.namespaces)),
+  );
+}
+
+/**
+ * Setup a watch for a binding
+ *
+ * @param binding the binding to watch
+ * @param capabilityNamespaces list of namespaces to filter on
+ */
+async function runBinding(binding: Binding, capabilityNamespaces: string[]) {
+  // Get the phases to match, fallback to any
+  const phaseMatch: WatchPhase[] = eventToPhaseMap[binding.event] || eventToPhaseMap[Event.Any];
+
+  // The watch callback is run when an object is received or dequeued
+
+  Log.debug({ watchCfg }, "Effective WatchConfig");
+  const watchCallback = async (obj: KubernetesObject, type: WatchPhase) => {
+    // First, filter the object based on the phase
+    if (phaseMatch.includes(type)) {
+      try {
+        // Then, check if the object matches the filter
+        const filterMatch = filterNoMatchReason(binding, obj, capabilityNamespaces);
+        if (filterMatch === "") {
+          await binding.watchCallback?.(obj, type);
+        } else {
+          Log.debug(filterMatch);
+        }
+      } catch (e) {
+        // Errors in the watch callback should not crash the controller
+        Log.error(e, "Error executing watch callback");
+      }
+    }
+  };
+
+  const queue = new Queue();
+  queue.setReconcile(watchCallback);
+
+  // Setup the resource watch
+  const watcher = K8s(binding.model, binding.filters).Watch(async (obj, type) => {
+    Log.debug(obj, `Watch event ${type} received`);
+
+    // If the binding is a queue, enqueue the object
+    if (binding.isQueue) {
+      await queue.enqueue(obj, type);
+    } else {
+      // Otherwise, run the watch callback directly
+      await watchCallback(obj, type);
+    }
+  }, watchCfg);
+
+  // If failure continues, log and exit
+  watcher.events.on(WatchEvent.GIVE_UP, err => {
+    Log.error(err, "Watch failed after 5 attempts, giving up");
+    process.exit(1);
+  });
+
+  watcher.events.on(WatchEvent.CONNECT, url => logEvent(WatchEvent.CONNECT, url));
+
+  watcher.events.on(WatchEvent.DATA_ERROR, err => logEvent(WatchEvent.DATA_ERROR, err.message));
+  watcher.events.on(WatchEvent.RECONNECT, (err, retryCount) =>
+    logEvent(WatchEvent.RECONNECT, err ? `Reconnecting after ${retryCount} attempts` : ""),
+  );
+  watcher.events.on(WatchEvent.RECONNECT_PENDING, () => logEvent(WatchEvent.RECONNECT_PENDING));
+  watcher.events.on(WatchEvent.GIVE_UP, err => logEvent(WatchEvent.GIVE_UP, err.message));
+  watcher.events.on(WatchEvent.ABORT, err => logEvent(WatchEvent.ABORT, err.message));
+  watcher.events.on(WatchEvent.OLD_RESOURCE_VERSION, err => logEvent(WatchEvent.OLD_RESOURCE_VERSION, err));
+  watcher.events.on(WatchEvent.NETWORK_ERROR, err => logEvent(WatchEvent.NETWORK_ERROR, err.message));
+  watcher.events.on(WatchEvent.LIST_ERROR, err => logEvent(WatchEvent.LIST_ERROR, err.message));
+  watcher.events.on(WatchEvent.LIST, list => logEvent(WatchEvent.LIST, JSON.stringify(list, undefined, 2)));
+  // Start the watch
+  try {
+    await watcher.start();
+  } catch (err) {
+    Log.error(err, "Error starting watch");
+    process.exit(1);
+  }
+}
+
+export function logEvent(type: WatchEvent, message: string = "", obj?: KubernetesObject) {
+  const logMessage = `Watch event ${type} received${message ? `. ${message}.` : "."}`;
+  if (obj) {
+    Log.debug(obj, logMessage);
+  } else {
+    Log.debug(logMessage);
+  }
+}

package/src/lib.ts

@@ -0,0 +1,27 @@
+import { K8s, RegisterKind, kind as a, fetch, fetchStatus, kind } from "kubernetes-fluent-client";
+import * as R from "ramda";
+
+import { Capability } from "./lib/capability";
+import Log from "./lib/logger";
+import { PeprModule } from "./lib/module";
+import { PeprMutateRequest } from "./lib/mutate-request";
+import * as PeprUtils from "./lib/utils";
+import { PeprValidateRequest } from "./lib/validate-request";
+import * as sdk from "./sdk/sdk";
+
+export {
+  Capability,
+  K8s,
+  Log,
+  PeprModule,
+  PeprMutateRequest,
+  PeprUtils,
+  PeprValidateRequest,
+  R,
+  RegisterKind,
+  a,
+  fetch,
+  fetchStatus,
+  kind,
+  sdk,
+};

package/src/runtime/controller.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { fork } from "child_process";
+import crypto from "crypto";
+import fs from "fs";
+import { gunzipSync } from "zlib";
+import { K8s, kind } from "kubernetes-fluent-client";
+import Log from "../lib/logger";
+import { packageJSON } from "../templates/data.json";
+import { peprStoreCRD } from "../lib/assets/store";
+import { validateHash } from "../lib/helpers";
+const { version } = packageJSON;
+
+function runModule(expectedHash: string) {
+  const gzPath = `/app/load/module-${expectedHash}.js.gz`;
+  const jsPath = `/app/module-${expectedHash}.js`;
+
+  // Set the log level
+  Log.level = "info";
+
+  // Check if the path is a valid file
+  if (!fs.existsSync(gzPath)) {
+    throw new Error(`File not found: ${gzPath}`);
+  }
+
+  try {
+    Log.info(`Loading module ${gzPath}`);
+
+    // Extract the code from the file
+    const codeGZ = fs.readFileSync(gzPath);
+    const code = gunzipSync(codeGZ);
+
+    // Get the hash of the extracted code
+    const actualHash = crypto.createHash("sha256").update(code).digest("hex");
+
+    // If the hash doesn't match, exit
+    // This is a timing safe comparison to prevent timing attacks
+    // https://en.wikipedia.org/wiki/Timing_attack
+    if (!crypto.timingSafeEqual(Buffer.from(expectedHash, "hex"), Buffer.from(actualHash, "hex"))) {
+      throw new Error(`File hash does not match, expected ${expectedHash} but got ${actualHash}`);
+    }
+
+    Log.info(`File hash matches, running module`);
+
+    // Write the code to a file
+    fs.writeFileSync(jsPath, code);
+
+    // Run the module
+    fork(jsPath);
+  } catch (e) {
+    throw new Error(`Failed to decompress module: ${e}`);
+  }
+}
+
+Log.info(`Pepr Controller (v${version})`);
+
+const hash = process.argv[2];
+
+const startup = async () => {
+  try {
+    Log.info("Applying the Pepr Store CRD if it doesn't exist");
+    await K8s(kind.CustomResourceDefinition).Apply(peprStoreCRD, { force: true });
+
+    validateHash(hash);
+    runModule(hash);
+  } catch (err) {
+    Log.error(err, `Error starting Pepr Store CRD`);
+    process.exit(1);
+  }
+};
+
+startup().catch(err => Log.error(err, `Error starting Pepr Controller`));

package/src/sdk/sdk.ts

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { PeprValidateRequest } from "../lib/validate-request";
+import { PeprMutateRequest } from "../lib/mutate-request";
+import { a } from "../lib";
+import { V1OwnerReference } from "@kubernetes/client-node";
+import { GenericKind } from "kubernetes-fluent-client";
+import { K8s, kind } from "kubernetes-fluent-client";
+import Log from "../lib/logger";
+
+/**
+ * Returns all containers in a pod
+ * @param request the request/pod to get the containers from
+ * @param containerType the type of container to get
+ * @returns the list of containers in the pod
+ */
+export function containers(
+  request: PeprValidateRequest<a.Pod> | PeprMutateRequest<a.Pod>,
+  containerType?: "containers" | "initContainers" | "ephemeralContainers",
+) {
+  const containers = request.Raw.spec?.containers || [];
+  const initContainers = request.Raw.spec?.initContainers || [];
+  const ephemeralContainers = request.Raw.spec?.ephemeralContainers || [];
+
+  if (containerType === "containers") {
+    return containers;
+  }
+  if (containerType === "initContainers") {
+    return initContainers;
+  }
+  if (containerType === "ephemeralContainers") {
+    return ephemeralContainers;
+  }
+  return [...containers, ...initContainers, ...ephemeralContainers];
+}
+
+/**
+ * Write a K8s event for a CRD
+ *
+ * @param cr The custom resource to write the event for
+ * @param event The event to write, should contain a human-readable message for the event
+ * @param eventType The type of event to write, for example "Warning"
+ * @param eventReason The reason for the event, for example "ReconciliationFailed"
+ * @param reportingComponent The component that is reporting the event, for example "uds.dev/operator"
+ * @param reportingInstance The instance of the component that is reporting the event, for example process.env.HOSTNAME
+ */
+export async function writeEvent(
+  cr: GenericKind,
+  event: Partial<kind.CoreEvent>,
+  eventType: string,
+  eventReason: string,
+  reportingComponent: string,
+  reportingInstance: string,
+) {
+  Log.debug(cr.metadata, `Writing event: ${event.message}`);
+
+  await K8s(kind.CoreEvent).Create({
+    type: eventType,
+    reason: eventReason,
+    ...event,
+    // Fixed values
+    metadata: {
+      namespace: cr.metadata!.namespace,
+      generateName: cr.metadata!.name,
+    },
+    involvedObject: {
+      apiVersion: cr.apiVersion,
+      kind: cr.kind,
+      name: cr.metadata!.name,
+      namespace: cr.metadata!.namespace,
+      uid: cr.metadata!.uid,
+    },
+    firstTimestamp: new Date(),
+    reportingComponent: reportingComponent,
+    reportingInstance: reportingInstance,
+  });
+}
+
+/**
+ * Get the owner reference for a custom resource
+ * @param cr the custom resource to get the owner reference for
+ * @returns the owner reference for the custom resource
+ */
+export function getOwnerRefFrom(cr: GenericKind): V1OwnerReference[] {
+  const { name, uid } = cr.metadata!;
+
+  return [
+    {
+      apiVersion: cr.apiVersion!,
+      kind: cr.kind!,
+      uid: uid!,
+      name: name!,
+    },
+  ];
+}
+
+/**
+ * Sanitize a resource name to make it a valid Kubernetes resource name.
+ *
+ * @param name the name of the resource to sanitize
+ * @returns the sanitized resource name
+ */
+export function sanitizeResourceName(name: string) {
+  return (
+    name
+      // The name must be lowercase
+      .toLowerCase()
+      // Replace sequences of non-alphanumeric characters with a single '-'
+      .replace(/[^a-z0-9]+/g, "-")
+      // Truncate the name to 250 characters
+      .slice(0, 250)
+      // Remove leading and trailing non-letter characters
+      .replace(/^[^a-z]+|[^a-z]+$/g, "")
+  );
+}

package/src/templates/.eslintrc.template.json

@@ -0,0 +1,18 @@
+{
+  "env": {
+    "browser": false,
+    "es2021": true
+  },
+  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "project": ["./tsconfig.json"],
+    "ecmaVersion": 2022
+  },
+  "plugins": ["@typescript-eslint"],
+  "ignorePatterns": ["node_modules", "dist"],
+  "root": true,
+  "rules": {
+    "@typescript-eslint/no-floating-promises": ["error"]
+  }
+}

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"
+      }
+    }
+  }
+]