pepr 0.0.0-development

package/src/lib/controller/index.ts

@@ -0,0 +1,326 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import express, { NextFunction } from "express";
+import fs from "fs";
+import https from "https";
+
+import { Capability } from "../capability";
+import { MutateResponse, AdmissionRequest, ValidateResponse } from "../k8s";
+import Log from "../logger";
+import { MetricsCollector } from "../metrics";
+import { ModuleConfig, isWatchMode } from "../module";
+import { mutateProcessor } from "../mutate-processor";
+import { validateProcessor } from "../validate-processor";
+import { PeprControllerStore } from "./store";
+import { ResponseItem } from "../types";
+
+export class Controller {
+  // Track whether the server is running
+  #running = false;
+
+  // Metrics collector
+  #metricsCollector = new MetricsCollector("pepr");
+
+  // The token used to authenticate requests
+  #token = "";
+
+  // The express app instance
+  readonly #app = express();
+
+  // Initialized with the constructor
+  readonly #config: ModuleConfig;
+  readonly #capabilities: Capability[];
+  readonly #beforeHook?: (req: AdmissionRequest) => void;
+  readonly #afterHook?: (res: MutateResponse | ValidateResponse) => void;
+
+  constructor(
+    config: ModuleConfig,
+    capabilities: Capability[],
+    beforeHook?: (req: AdmissionRequest) => void,
+    afterHook?: (res: MutateResponse | ValidateResponse) => void,
+    onReady?: () => void,
+  ) {
+    this.#config = config;
+    this.#capabilities = capabilities;
+
+    // Initialize the Pepr store for each capability
+    new PeprControllerStore(capabilities, `pepr-${config.uuid}-store`, () => {
+      this.#bindEndpoints();
+      onReady && onReady();
+      Log.info("✅ Controller startup complete");
+      // Initialize the schedule store for each capability
+      new PeprControllerStore(capabilities, `pepr-${config.uuid}-schedule`, () => {
+        Log.info("✅ Scheduling processed");
+      });
+    });
+
+    // Middleware for logging requests
+    this.#app.use(Controller.#logger);
+
+    // Middleware for parsing JSON, limit to 2mb vs 100K for K8s compatibility
+    this.#app.use(express.json({ limit: "2mb" }));
+
+    if (beforeHook) {
+      Log.info(`Using beforeHook: ${beforeHook}`);
+      this.#beforeHook = beforeHook;
+    }
+
+    if (afterHook) {
+      Log.info(`Using afterHook: ${afterHook}`);
+      this.#afterHook = afterHook;
+    }
+  }
+
+  /** Start the webhook server */
+  startServer = (port: number) => {
+    if (this.#running) {
+      throw new Error("Cannot start Pepr module: Pepr module was not instantiated with deferStart=true");
+    }
+
+    // Load SSL certificate and key
+    const options = {
+      key: fs.readFileSync(process.env.SSL_KEY_PATH || "/etc/certs/tls.key"),
+      cert: fs.readFileSync(process.env.SSL_CERT_PATH || "/etc/certs/tls.crt"),
+    };
+
+    // Get the API token if not in watch mode
+    if (!isWatchMode()) {
+      // Get the API token from the environment variable or the mounted secret
+      this.#token = process.env.PEPR_API_TOKEN || fs.readFileSync("/app/api-token/value").toString().trim();
+      Log.info(`Using API token: ${this.#token}`);
+
+      if (!this.#token) {
+        throw new Error("API token not found");
+      }
+    }
+
+    // Create HTTPS server
+    const server = https.createServer(options, this.#app).listen(port);
+
+    // Handle server listening event
+    server.on("listening", () => {
+      Log.info(`Server listening on port ${port}`);
+      // Track that the server is running
+      this.#running = true;
+    });
+
+    // Handle EADDRINUSE errors
+    server.on("error", (e: { code: string }) => {
+      if (e.code === "EADDRINUSE") {
+        Log.warn(
+          `Address in use, retrying in 2 seconds. If this persists, ensure ${port} is not in use, e.g. "lsof -i :${port}"`,
+        );
+        setTimeout(() => {
+          server.close();
+          server.listen(port);
+        }, 2000);
+      }
+    });
+
+    // Listen for the SIGTERM signal and gracefully close the server
+    process.on("SIGTERM", () => {
+      Log.info("Received SIGTERM, closing server");
+      server.close(() => {
+        Log.info("Server closed");
+        process.exit(0);
+      });
+    });
+  };
+
+  #bindEndpoints = () => {
+    // Health check endpoint
+    this.#app.get("/healthz", Controller.#healthz);
+
+    // Metrics endpoint
+    this.#app.get("/metrics", this.#metrics);
+
+    if (isWatchMode()) {
+      return;
+    }
+
+    // Require auth for webhook endpoints
+    this.#app.use(["/mutate/:token", "/validate/:token"], this.#validateToken);
+
+    // Mutate endpoint
+    this.#app.post("/mutate/:token", this.#admissionReq("Mutate"));
+
+    // Validate endpoint
+    this.#app.post("/validate/:token", this.#admissionReq("Validate"));
+  };
+
+  /**
+   * Validate the token in the request path
+   *
+   * @param req The incoming request
+   * @param res The outgoing response
+   * @param next The next middleware function
+   * @returns
+   */
+  #validateToken = (req: express.Request, res: express.Response, next: NextFunction) => {
+    // Validate the token
+    const { token } = req.params;
+    if (token !== this.#token) {
+      const err = `Unauthorized: invalid token '${token.replace(/[^\w]/g, "_")}'`;
+      Log.warn(err);
+      res.status(401).send(err);
+      this.#metricsCollector.alert();
+      return;
+    }
+
+    // Token is valid, continue
+    next();
+  };
+
+  /**
+   * Metrics endpoint handler
+   *
+   * @param req the incoming request
+   * @param res the outgoing response
+   */
+  #metrics = async (req: express.Request, res: express.Response) => {
+    try {
+      res.send(await this.#metricsCollector.getMetrics());
+    } catch (err) {
+      Log.error(err, `Error getting metrics`);
+      res.status(500).send("Internal Server Error");
+    }
+  };
+
+  /**
+   * Admission request handler for both mutate and validate requests
+   *
+   * @param admissionKind the type of admission request
+   * @returns the request handler
+   */
+  #admissionReq = (admissionKind: "Mutate" | "Validate") => {
+    // Create the admission request handler
+    return async (req: express.Request, res: express.Response) => {
+      // Start the metrics timer
+      const startTime = MetricsCollector.observeStart();
+
+      try {
+        // Get the request from the body or create an empty request
+        const request: AdmissionRequest = req.body?.request || ({} as AdmissionRequest);
+
+        // Run the before hook if it exists
+        this.#beforeHook && this.#beforeHook(request || {});
+
+        // Setup identifiers for logging
+        const name = request?.name ? `/${request.name}` : "";
+        const namespace = request?.namespace || "";
+        const gvk = request?.kind || { group: "", version: "", kind: "" };
+
+        const reqMetadata = {
+          uid: request.uid,
+          namespace,
+          name,
+        };
+
+        Log.info({ ...reqMetadata, gvk, operation: request.operation, admissionKind }, "Incoming request");
+        Log.debug({ ...reqMetadata, request }, "Incoming request body");
+
+        // Process the request
+        let response: MutateResponse | ValidateResponse[];
+
+        // Call mutate or validate based on the admission kind
+        if (admissionKind === "Mutate") {
+          response = await mutateProcessor(this.#config, this.#capabilities, request, reqMetadata);
+        } else {
+          response = await validateProcessor(this.#capabilities, request, reqMetadata);
+        }
+
+        // Run the after hook if it exists
+        const responseList: ValidateResponse[] | MutateResponse[] = Array.isArray(response) ? response : [response];
+        responseList.map(res => {
+          this.#afterHook && this.#afterHook(res);
+          // Log the response
+          Log.info({ ...reqMetadata, res }, "Check response");
+        });
+
+        let kubeAdmissionResponse: ValidateResponse[] | MutateResponse | ResponseItem;
+
+        if (admissionKind === "Mutate") {
+          kubeAdmissionResponse = response;
+          Log.debug({ ...reqMetadata, response }, "Outgoing response");
+          res.send({
+            apiVersion: "admission.k8s.io/v1",
+            kind: "AdmissionReview",
+            response: kubeAdmissionResponse,
+          });
+        } else {
+          kubeAdmissionResponse =
+            responseList.length === 0
+              ? {
+                  uid: request.uid,
+                  allowed: true,
+                  status: { message: "no in-scope validations -- allowed!" },
+                }
+              : {
+                  uid: responseList[0].uid,
+                  allowed: responseList.filter(r => !r.allowed).length === 0,
+                  status: {
+                    message: (responseList as ValidateResponse[])
+                      .filter(rl => !rl.allowed)
+                      .map(curr => curr.status?.message)
+                      .join("; "),
+                  },
+                };
+          res.send({
+            apiVersion: "admission.k8s.io/v1",
+            kind: "AdmissionReview",
+            response: kubeAdmissionResponse,
+          });
+        }
+
+        Log.debug({ ...reqMetadata, kubeAdmissionResponse }, "Outgoing response");
+
+        this.#metricsCollector.observeEnd(startTime, admissionKind);
+      } catch (err) {
+        Log.error(err, `Error processing ${admissionKind} request`);
+        res.status(500).send("Internal Server Error");
+        this.#metricsCollector.error();
+      }
+    };
+  };
+
+  /**
+   * Middleware for logging requests
+   *
+   * @param req the incoming request
+   * @param res the outgoing response
+   * @param next the next middleware function
+   */
+  static #logger(req: express.Request, res: express.Response, next: express.NextFunction) {
+    const startTime = Date.now();
+
+    res.on("finish", () => {
+      const elapsedTime = Date.now() - startTime;
+      const message = {
+        uid: req.body?.request?.uid,
+        method: req.method,
+        url: req.originalUrl,
+        status: res.statusCode,
+        duration: `${elapsedTime} ms`,
+      };
+
+      res.statusCode >= 300 ? Log.warn(message) : Log.info(message);
+    });
+
+    next();
+  }
+  /**
+   * Health check endpoint handler
+   *
+   * @param req the incoming request
+   * @param res the outgoing response
+   */
+  static #healthz(req: express.Request, res: express.Response) {
+    try {
+      res.send("OK");
+    } catch (err) {
+      Log.error(err, `Error processing health check`);
+      res.status(500).send("Internal Server Error");
+    }
+  }
+}

package/src/lib/controller/store.ts

@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { Operation } from "fast-json-patch";
+import { K8s } from "kubernetes-fluent-client";
+import { startsWith } from "ramda";
+
+import { Capability } from "../capability";
+import { PeprStore } from "../k8s";
+import Log from "../logger";
+import { DataOp, DataSender, DataStore, Storage } from "../storage";
+
+const namespace = "pepr-system";
+export const debounceBackoff = 5000;
+
+export class PeprControllerStore {
+  #name: string;
+  #stores: Record<string, Storage> = {};
+  #sendDebounce: NodeJS.Timeout | undefined;
+  #onReady?: () => void;
+
+  constructor(capabilities: Capability[], name: string, onReady?: () => void) {
+    this.#onReady = onReady;
+
+    // Setup Pepr State bindings
+    this.#name = name;
+
+    if (name.includes("schedule")) {
+      // Establish the store for each capability
+      for (const { name, registerScheduleStore, hasSchedule } of capabilities) {
+        // Guard Clause to exit  early
+        if (hasSchedule !== true) {
+          continue;
+        }
+        // Register the scheduleStore with the capability
+        const { scheduleStore } = registerScheduleStore();
+
+        // Bind the store sender to the capability
+        scheduleStore.registerSender(this.#send(name));
+
+        // Store the storage instance
+        this.#stores[name] = scheduleStore;
+      }
+    } else {
+      // Establish the store for each capability
+      for (const { name, registerStore } of capabilities) {
+        // Register the store with the capability
+        const { store } = registerStore();
+
+        // Bind the store sender to the capability
+        store.registerSender(this.#send(name));
+
+        // Store the storage instance
+        this.#stores[name] = store;
+      }
+    }
+
+    // Add a jitter to the Store creation to avoid collisions
+    setTimeout(
+      () =>
+        K8s(PeprStore)
+          .InNamespace(namespace)
+          .Get(this.#name)
+          // If the get succeeds, setup the watch
+          .then(this.#setupWatch)
+          // Otherwise, create the resource
+          .catch(this.#createStoreResource),
+      Math.random() * 3000,
+    );
+  }
+
+  #setupWatch = () => {
+    const watcher = K8s(PeprStore, { name: this.#name, namespace }).Watch(this.#receive);
+    watcher.start().catch(e => Log.error(e, "Error starting Pepr store watch"));
+  };
+
+  #receive = (store: PeprStore) => {
+    Log.debug(store, "Pepr Store update");
+
+    // Wrap the update in a debounced function
+    const debounced = () => {
+      // Base64 decode the data
+      const data: DataStore = store.data || {};
+
+      // Loop over each stored capability
+      for (const name of Object.keys(this.#stores)) {
+        // Get the prefix offset for the keys
+        const offset = `${name}-`.length;
+
+        // Get any keys that match the capability name prefix
+        const filtered: DataStore = {};
+
+        // Loop over each key in the secret
+        for (const key of Object.keys(data)) {
+          // Match on the capability name as a prefix
+          if (startsWith(name, key)) {
+            // Strip the prefix and store the value
+            filtered[key.slice(offset)] = data[key];
+          }
+        }
+
+        // Send the data to the receiver callback
+        this.#stores[name].receive(filtered);
+      }
+
+      // Call the onReady callback if this is the first time the secret has been read
+      if (this.#onReady) {
+        this.#onReady();
+        this.#onReady = undefined;
+      }
+    };
+
+    // Debounce the update to 1 second to avoid multiple rapid calls
+    clearTimeout(this.#sendDebounce);
+    this.#sendDebounce = setTimeout(debounced, this.#onReady ? 0 : debounceBackoff);
+  };
+
+  #send = (capabilityName: string) => {
+    const sendCache: Record<string, Operation> = {};
+
+    // Load the sendCache with patch operations
+    const fillCache = (op: DataOp, key: string[], val?: string) => {
+      if (op === "add") {
+        const path = `/data/${capabilityName}-${key}`;
+        const value = val || "";
+        const cacheIdx = [op, path, value].join(":");
+
+        // Add the operation to the cache
+        sendCache[cacheIdx] = { op, path, value };
+
+        return;
+      }
+
+      if (op === "remove") {
+        if (key.length < 1) {
+          throw new Error(`Key is required for REMOVE operation`);
+        }
+
+        for (const k of key) {
+          const path = `/data/${capabilityName}-${k}`;
+          const cacheIdx = [op, path].join(":");
+
+          // Add the operation to the cache
+          sendCache[cacheIdx] = { op, path };
+        }
+
+        return;
+      }
+
+      // If we get here, the operation is not supported
+      throw new Error(`Unsupported operation: ${op}`);
+    };
+
+    // Send the cached updates to the cluster
+    const flushCache = async () => {
+      const indexes = Object.keys(sendCache);
+      const payload = Object.values(sendCache);
+
+      // Loop over each key in the cache and delete it to avoid collisions with other sender calls
+      for (const idx of indexes) {
+        delete sendCache[idx];
+      }
+
+      try {
+        // Send the patch to the cluster
+        await K8s(PeprStore, { namespace, name: this.#name }).Patch(payload);
+      } catch (err) {
+        Log.error(err, "Pepr store update failure");
+
+        if (err.status === 422) {
+          Object.keys(sendCache).forEach(key => delete sendCache[key]);
+        } else {
+          // On failure to update, re-add the operations to the cache to be retried
+          for (const idx of indexes) {
+            sendCache[idx] = payload[Number(idx)];
+          }
+        }
+      }
+    };
+
+    // Create a sender function for the capability to add/remove data from the store
+    const sender: DataSender = async (op: DataOp, key: string[], val?: string) => {
+      fillCache(op, key, val);
+    };
+
+    // Send any cached updates every debounceBackoff milliseconds
+    setInterval(() => {
+      if (Object.keys(sendCache).length > 0) {
+        Log.debug(sendCache, "Sending updates to Pepr store");
+        void flushCache();
+      }
+    }, debounceBackoff);
+
+    return sender;
+  };
+
+  #createStoreResource = async (e: unknown) => {
+    Log.info(`Pepr store not found, creating...`);
+    Log.debug(e);
+
+    try {
+      await K8s(PeprStore).Apply({
+        metadata: {
+          name: this.#name,
+          namespace,
+        },
+        data: {
+          // JSON Patch will die if the data is empty, so we need to add a placeholder
+          __pepr_do_not_delete__: "k-thx-bye",
+        },
+      });
+
+      // Now that the resource exists, setup the watch
+      this.#setupWatch();
+    } catch (err) {
+      Log.error(err, "Failed to create Pepr store");
+    }
+  };
+}

package/src/lib/errors.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+export const Errors = {
+  audit: "audit",
+  ignore: "ignore",
+  reject: "reject",
+};
+
+export const ErrorList = Object.values(Errors);
+
+/**
+ * Validate the error or throw an error
+ * @param error
+ */
+export function ValidateError(error = "") {
+  if (!ErrorList.includes(error)) {
+    throw new Error(`Invalid error: ${error}. Must be one of: ${ErrorList.join(", ")}`);
+  }
+}

package/src/lib/filter.ts

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { AdmissionRequest, Operation } from "./k8s";
+import logger from "./logger";
+import { Binding, Event } from "./types";
+
+/**
+ * shouldSkipRequest determines if a request should be skipped based on the binding filters.
+ *
+ * @param binding the action binding
+ * @param req the incoming request
+ * @returns
+ */
+export function shouldSkipRequest(binding: Binding, req: AdmissionRequest, capabilityNamespaces: string[]) {
+  const { group, kind, version } = binding.kind || {};
+  const { namespaces, labels, annotations, name } = binding.filters || {};
+  const operation = req.operation.toUpperCase();
+  const uid = req.uid;
+  // 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)) {
+    return true;
+  }
+
+  // Test name first, since it's the most specific
+  if (name && name !== req.name) {
+    return true;
+  }
+
+  // Test for matching kinds
+  if (kind !== req.kind.kind) {
+    return true;
+  }
+
+  // Test for matching groups
+  if (group && group !== req.kind.group) {
+    return true;
+  }
+
+  // Test for matching versions
+  if (version && version !== req.kind.version) {
+    return true;
+  }
+
+  // Test for matching namespaces
+  if (
+    (combinedNamespaces.length && !combinedNamespaces.includes(req.namespace || "")) ||
+    (!namespaces.includes(req.namespace || "") && capabilityNamespaces.length !== 0 && namespaces.length !== 0)
+  ) {
+    let type = "";
+    let label = "";
+
+    if (binding.isMutate) {
+      type = "Mutate";
+      label = binding.mutateCallback!.name;
+    } else if (binding.isValidate) {
+      type = "Validate";
+      label = binding.validateCallback!.name;
+    } else if (binding.isWatch) {
+      type = "Watch";
+      label = binding.watchCallback!.name;
+    }
+
+    logger.debug({ uid }, `${type} binding (${label}) does not match request namespace "${req.namespace}"`);
+
+    return true;
+  }
+
+  // Test for matching labels
+  for (const [key, value] of Object.entries(labels)) {
+    const testKey = metadata?.labels?.[key];
+
+    // First check if the label exists
+    if (!testKey) {
+      logger.debug({ uid }, `Label ${key} does not exist`);
+      return true;
+    }
+
+    // Then check if the value matches, if specified
+    if (value && testKey !== value) {
+      logger.debug({ uid }, `${testKey} does not match ${value}`);
+      return true;
+    }
+  }
+
+  // Test for matching annotations
+  for (const [key, value] of Object.entries(annotations)) {
+    const testKey = metadata?.annotations?.[key];
+
+    // First check if the annotation exists
+    if (!testKey) {
+      logger.debug({ uid }, `Annotation ${key} does not exist`);
+      return true;
+    }
+
+    // Then check if the value matches, if specified
+    if (value && testKey !== value) {
+      logger.debug({ uid }, `${testKey} does not match ${value}`);
+      return true;
+    }
+  }
+
+  // No failed filters, so we should not skip this request
+  return false;
+}