pepr 0.12.2 → 0.13.1

package/src/lib/k8s/kinds.ts

@@ -5,6 +5,46 @@ import { GenericClass } from "../types";
 import { GroupVersionKind } from "./types";
 
 export const gvkMap: Record<string, GroupVersionKind> = {
+  /**
+   * Represents a K8s ClusterRole resource.
+   * ClusterRole is a set of permissions that can be bound to a user or group in a cluster-wide scope.
+   * @see {@link https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole}
+   */
+  V1ClusterRole: {
+    kind: "ClusterRole",
+    version: "v1",
+    group: "rbac.authorization.k8s.io",
+  },
+  /**
+   * Represents a K8s ClusterRoleBinding resource.
+   * ClusterRoleBinding binds a ClusterRole to a user or group in a cluster-wide scope.
+   * @see {@link https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding}
+   */
+  V1ClusterRoleBinding: {
+    kind: "ClusterRoleBinding",
+    version: "v1",
+    group: "rbac.authorization.k8s.io",
+  },
+  /**
+   * Represents a K8s Role resource.
+   * Role is a set of permissions that can be bound to a user or group in a namespace scope.
+   * @see {@link https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole}
+   */
+  V1Role: {
+    kind: "Role",
+    version: "v1",
+    group: "rbac.authorization.k8s.io",
+  },
+  /**
+   * Represents a K8s RoleBinding resource.
+   * RoleBinding binds a Role to a user or group in a namespace scope.
+   * @see {@link https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding}
+   */
+  V1RoleBinding: {
+    kind: "RoleBinding",
+    version: "v1",
+    group: "rbac.authorization.k8s.io",
+  },
   /**
    * Represents a K8s ConfigMap resource.
    * ConfigMap holds configuration data for pods to consume.

package/src/lib/k8s/types.ts

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
-import { V1ListMeta, V1ObjectMeta } from "@kubernetes/client-node";
+import { KubernetesListObject, KubernetesObject, V1ObjectMeta } from "@kubernetes/client-node";
+
+export { KubernetesListObject, KubernetesObject };
 
 export enum Operation {
   CREATE = "CREATE",
@@ -10,18 +12,6 @@ export enum Operation {
   CONNECT = "CONNECT",
 }
 
-export interface KubernetesObject {
-  apiVersion?: string;
-  kind?: string;
-  metadata?: V1ObjectMeta;
-}
-export interface KubernetesListObject<T extends KubernetesObject> {
-  apiVersion?: string;
-  kind?: string;
-  metadata?: V1ListMeta;
-  items: T[];
-}
-
 /**
  * GenericKind is a generic Kubernetes object that can be used to represent any Kubernetes object
  * that is not explicitly supported by Pepr. This can be used on its own or as a base class for
@@ -138,7 +128,7 @@ export interface Request<T = KubernetesObject> {
   readonly options?: any;
 }
 
-export interface Response {
+export interface MutateResponse {
   /** UID is an identifier for the individual request/response. This must be copied over from the corresponding AdmissionRequest. */
   uid: string;
 
@@ -154,7 +144,11 @@ export interface Response {
   /** The type of Patch. Currently we only allow "JSONPatch". */
   patchType?: "JSONPatch";
 
-  /** AuditAnnotations is an unstructured key value map set by remote admission controller (e.g. error=image-blacklisted). */
+  /**
+   * AuditAnnotations is an unstructured key value map set by remote admission controller (e.g. error=image-blacklisted).
+   *
+   * See https://kubernetes.io/docs/reference/labels-annotations-taints/audit-annotations/ for more information
+   */
   auditAnnotations?: {
     [key: string]: string;
   };
@@ -163,6 +157,18 @@ export interface Response {
   warnings?: string[];
 }
 
+export interface ValidateResponse extends MutateResponse {
+  /** Status contains extra details into why an admission request was denied. This field IS NOT consulted in any way if "Allowed" is "true". */
+  status?: {
+    /** A machine-readable description of why this operation is in the
+       "Failure" status. If this value is empty there is no information available. */
+    code: number;
+
+    /** A human-readable description of the status of this operation. */
+    message: string;
+  };
+}
+
 export type WebhookIgnore = {
   /**
    * List of Kubernetes namespaces to always ignore.

package/src/lib/k8s/upstream.ts

@@ -1,10 +1,12 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
-/** a is a collection of K8s types to be used within a CapabilityAction: `When(a.Configmap)` */
+/** a is a collection of K8s types to be used within an action: `When(a.Configmap)` */
 export {
   V1APIService as APIService,
   V1CertificateSigningRequest as CertificateSigningRequest,
+  V1ClusterRole as ClusterRole,
+  V1ClusterRoleBinding as ClusterRoleBinding,
   V1ConfigMap as ConfigMap,
   V1ControllerRevision as ControllerRevision,
   V1CronJob as CronJob,
@@ -32,6 +34,8 @@ export {
   V1ReplicaSet as ReplicaSet,
   V1ReplicationController as ReplicationController,
   V1ResourceQuota as ResourceQuota,
+  V1Role as Role,
+  V1RoleBinding as RoleBinding,
   V1RuntimeClass as RuntimeClass,
   V1Secret as Secret,
   V1SelfSubjectAccessReview as SelfSubjectAccessReview,

package/src/lib/logger.ts

@@ -1,136 +1,25 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
-/**
- * Enumeration representing different logging levels.
- */
-export enum LogLevel {
-  debug = 0,
-  info = 1,
-  warn = 2,
-  error = 3,
-}
-
-enum ConsoleColors {
-  Reset = "\x1b[0m",
-  Bright = "\x1b[1m",
-  Dim = "\x1b[2m",
-  Underscore = "\x1b[4m",
-  Blink = "\x1b[5m",
-  Reverse = "\x1b[7m",
-  Hidden = "\x1b[8m",
-
-  FgBlack = "\x1b[30m",
-  FgRed = "\x1b[31m",
-  FgGreen = "\x1b[32m",
-  FgYellow = "\x1b[33m",
-  FgBlue = "\x1b[34m",
-  FgMagenta = "\x1b[35m",
-  FgCyan = "\x1b[36m",
-  FgWhite = "\x1b[37m",
-
-  BgBlack = "\x1b[40m",
-  BgRed = "\x1b[41m",
-  BgGreen = "\x1b[42m",
-  BgYellow = "\x1b[43m",
-  BgBlue = "\x1b[44m",
-  BgMagenta = "\x1b[45m",
-  BgCyan = "\x1b[46m",
-  BgWhite = "\x1b[47m",
-}
-
-/**
- * Simple logger class that logs messages at different log levels.
- */
-export class Logger {
-  private _logLevel: LogLevel;
-
-  /**
-   * Create a new logger instance.
-   * @param logLevel - The minimum log level to log messages for.
-   */
-  constructor(logLevel: LogLevel) {
-    this._logLevel = logLevel;
-  }
-
-  /**
-   * Change the log level of the logger.
-   * @param logLevel - The log level to log the message at.
-   */
-  public SetLogLevel(logLevel: string): void {
-    this._logLevel = LogLevel[logLevel as keyof typeof LogLevel];
-    this.debug(`Log level set to ${logLevel}`);
-  }
+import { pino } from "pino";
 
-  /**
-   * Log a debug message.
-   * @param message - The message to log.
-   */
-  public debug<T>(message: T, prefix?: string): void {
-    this.log(LogLevel.debug, message, prefix);
-  }
+const isPrettyLog = process.env.PEPR_PRETTY_LOGS === "true";
 
-  /**
-   * Log an info message.
-   * @param message - The message to log.
-   */
-  public info<T>(message: T, prefix?: string): void {
-    this.log(LogLevel.info, message, prefix);
-  }
+const pretty = {
+  target: "pino-pretty",
+  options: {
+    colorize: true,
+  },
+};
 
-  /**
-   * Log a warning message.
-   * @param message - The message to log.
-   */
-  public warn<T>(message: T, prefix?: string): void {
-    this.log(LogLevel.warn, message, prefix);
-  }
+const transport = isPrettyLog ? pretty : undefined;
 
-  /**
-   * Log an error message.
-   * @param message - The message to log.
-   */
-  public error<T>(message: T, prefix?: string): void {
-    this.log(LogLevel.error, message, prefix);
-  }
+const Log = pino({
+  transport,
+});
 
-  /**
-   * Log a message at the specified log level.
-   * @param logLevel - The log level of the message.
-   * @param message - The message to log.
-   */
-  private log<T>(logLevel: LogLevel, message: T, callerPrefix = ""): void {
-    const color = {
-      [LogLevel.debug]: ConsoleColors.FgBlack,
-      [LogLevel.info]: ConsoleColors.FgCyan,
-      [LogLevel.warn]: ConsoleColors.FgYellow,
-      [LogLevel.error]: ConsoleColors.FgRed,
-    };
-
-    if (logLevel >= this._logLevel) {
-      // Prefix the message with the colored log level.
-      let prefix = "[" + LogLevel[logLevel] + "]\t" + callerPrefix;
-
-      prefix = this.colorize(prefix, color[logLevel]);
-
-      // If the message is not a string, use the debug method to log the object.
-      if (typeof message !== "string") {
-        console.log(prefix);
-        console.debug("%o", message);
-      } else {
-        console.log(prefix + "\t" + message);
-      }
-    }
-  }
-
-  private colorize(text: string, color: ConsoleColors): string {
-    return color + text + ConsoleColors.Reset;
-  }
-}
-
-/** Log is an instance of Logger used to generate log entries. */
-const Log = new Logger(LogLevel.info);
 if (process.env.LOG_LEVEL) {
-  Log.SetLogLevel(process.env.LOG_LEVEL);
+  Log.level = process.env.LOG_LEVEL;
 }
+
 export default Log;

package/src/lib/metrics.ts

@@ -1,61 +1,117 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
-import promClient from "prom-client";
+/* eslint-disable class-methods-use-this */
+
 import { performance } from "perf_hooks";
+import promClient, { Counter, Registry, Summary } from "prom-client";
+import Log from "./logger";
+
+const loggingPrefix = "MetricsCollector";
+
+interface MetricNames {
+  errors: string;
+  alerts: string;
+  mutate: string;
+  validate: string;
+}
+
+interface MetricArgs {
+  name: string;
+  help: string;
+  registers: Registry[];
+}
 
 /**
  * MetricsCollector class handles metrics collection using prom-client and performance hooks.
  */
 export class MetricsCollector {
-  private _registry: promClient.Registry;
-  private _errors: promClient.Counter<string>;
-  private _alerts: promClient.Counter<string>;
-  private _summary: promClient.Summary<string>;
+  #registry: Registry;
+  #counters: Map<string, Counter<string>> = new Map();
+  #summaries: Map<string, Summary<string>> = new Map();
+  #prefix: string;
+
+  #metricNames: MetricNames = {
+    errors: "errors",
+    alerts: "alerts",
+    mutate: "Mutate",
+    validate: "Validate",
+  };
 
   /**
    * Creates a MetricsCollector instance with prefixed metrics.
-   * @param {string} [prefix='pepr'] - The prefix for the metric names.
+   * @param [prefix='pepr'] - The prefix for the metric names.
    */
   constructor(prefix = "pepr") {
-    this._registry = new promClient.Registry();
+    this.#registry = new Registry();
+    this.#prefix = prefix;
+    this.addCounter(this.#metricNames.errors, "Mutation/Validate errors encountered");
+    this.addCounter(this.#metricNames.alerts, "Mutation/Validate bad api token received");
+    this.addSummary(this.#metricNames.mutate, "Mutation operation summary");
+    this.addSummary(this.#metricNames.validate, "Validation operation summary");
+  }
 
-    this._errors = new promClient.Counter({
-      name: `${prefix}_errors`,
-      help: "error counter",
-      registers: [this._registry],
-    });
+  #getMetricName(name: string) {
+    return `${this.#prefix}_${name}`;
+  }
 
-    this._alerts = new promClient.Counter({
-      name: `${prefix}_alerts`,
-      help: "alerts counter",
-      registers: [this._registry],
-    });
+  #addMetric<T extends Counter<string> | Summary<string>>(
+    collection: Map<string, T>,
+    MetricType: new (args: MetricArgs) => T,
+    name: string,
+    help: string,
+  ) {
+    if (collection.has(this.#getMetricName(name))) {
+      Log.debug(`Metric for ${name} already exists`, loggingPrefix);
+      return;
+    }
+
+    // Bind public methods
+    this.incCounter = this.incCounter.bind(this);
+    this.error = this.error.bind(this);
+    this.alert = this.alert.bind(this);
+    this.observeStart = this.observeStart.bind(this);
+    this.observeEnd = this.observeEnd.bind(this);
+    this.getMetrics = this.getMetrics.bind(this);
 
-    this._summary = new promClient.Summary({
-      name: `${prefix}_summary`,
-      help: "summary",
-      registers: [this._registry],
+    const metric = new MetricType({
+      name: this.#getMetricName(name),
+      help,
+      registers: [this.#registry],
     });
+
+    collection.set(this.#getMetricName(name), metric);
+  }
+
+  addCounter(name: string, help: string) {
+    this.#addMetric(this.#counters, promClient.Counter, name, help);
+  }
+
+  addSummary(name: string, help: string) {
+    this.#addMetric(this.#summaries, promClient.Summary, name, help);
+  }
+
+  incCounter(name: string) {
+    this.#counters.get(this.#getMetricName(name))?.inc();
   }
 
   /**
    * Increments the error counter.
    */
   error() {
-    this._errors.inc();
+    this.incCounter(this.#metricNames.errors);
   }
 
   /**
    * Increments the alerts counter.
    */
   alert() {
-    this._alerts.inc();
+    this.incCounter(this.#metricNames.alerts);
   }
 
   /**
    * Returns the current timestamp from performance.now() method. Useful for start timing an operation.
-   * @returns {number} The timestamp.
+   * @returns The timestamp.
    */
   observeStart() {
     return performance.now();
@@ -63,17 +119,18 @@ export class MetricsCollector {
 
   /**
    * Observes the duration since the provided start time and updates the summary.
-   * @param {number} startTime - The start time.
+   * @param startTime - The start time.
+   * @param name - The metrics summary to increment.
    */
-  observeEnd(startTime: number) {
-    this._summary.observe(performance.now() - startTime);
+  observeEnd(startTime: number, name: string = this.#metricNames.mutate) {
+    this.#summaries.get(this.#getMetricName(name))?.observe(performance.now() - startTime);
   }
 
   /**
    * Fetches the current metrics from the registry.
-   * @returns {Promise<string>} The metrics.
+   * @returns The metrics.
    */
   async getMetrics() {
-    return this._registry.metrics();
+    return this.#registry.metrics();
   }
 }

package/src/lib/module.ts

@@ -1,17 +1,13 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
-import { concat, mergeDeepWith } from "ramda";
+import { clone } from "ramda";
 
 import { Capability } from "./capability";
 import { Controller } from "./controller";
-import { Request, Response } from "./k8s/types";
-import { ModuleConfig } from "./types";
-
-const alwaysIgnore = {
-  namespaces: ["kube-system", "pepr-system"],
-  labels: [{ "pepr.dev": "ignore" }],
-};
+import { ValidateError } from "./errors";
+import { MutateResponse, Request, ValidateResponse } from "./k8s/types";
+import { CapabilityExport, ModuleConfig } from "./types";
 
 export type PackageJSON = {
   description: string;
@@ -25,30 +21,50 @@ export type PeprModuleOptions = {
   beforeHook?: (req: Request) => void;
 
   /** A user-defined callback to post-process or intercept a Pepr response just before it is returned to K8s */
-  afterHook?: (res: Response) => void;
+  afterHook?: (res: MutateResponse | ValidateResponse) => void;
 };
 
 export class PeprModule {
-  private _controller!: Controller;
+  #controller!: Controller;
 
   /**
    * Create a new Pepr runtime
    *
    * @param config The configuration for the Pepr runtime
    * @param capabilities The capabilities to be loaded into the Pepr runtime
-   * @param _deferStart (optional) If set to `true`, the Pepr runtime will not be started automatically. This can be used to start the Pepr runtime manually with `start()`.
+   * @param opts Options for the Pepr runtime
    */
   constructor({ description, pepr }: PackageJSON, capabilities: Capability[] = [], opts: PeprModuleOptions = {}) {
-    const config: ModuleConfig = mergeDeepWith(concat, pepr, alwaysIgnore);
+    const config: ModuleConfig = clone(pepr);
     config.description = description;
 
+    // Need to validate at runtime since TS gets sad about parsing the package.json
+    ValidateError(config.onError);
+
+    // Bind public methods
+    this.start = this.start.bind(this);
+
     // Handle build mode
-    if (process.env.PEPR_MODE === "build") {
-      process.send?.({ capabilities });
+    if (process.env.PEPR_MODE === "build" && process.send) {
+      const exportedCapabilities: CapabilityExport[] = [];
+
+      // Send capability map to parent process
+      for (const capability of capabilities) {
+        // Convert the capability to a capability config
+        exportedCapabilities.push({
+          name: capability.name,
+          description: capability.description,
+          namespaces: capability.namespaces,
+          bindings: capability.bindings,
+        });
+      }
+
+      process.send(exportedCapabilities);
+
       return;
     }
 
-    this._controller = new Controller(config, capabilities, opts.beforeHook, opts.afterHook);
+    this.#controller = new Controller(config, capabilities, opts.beforeHook, opts.afterHook);
 
     // Stop processing if deferStart is set to true
     if (opts.deferStart) {
@@ -65,6 +81,6 @@ export class PeprModule {
    * @param port
    */
   start(port = 3000) {
-    this._controller.startServer(port);
+    this.#controller.startServer(port);
   }
 }

package/src/lib/{processor.ts → mutate-processor.ts}

@@ -4,29 +4,30 @@
 import jsonPatch from "fast-json-patch";
 
 import { Capability } from "./capability";
+import { Errors } from "./errors";
 import { shouldSkipRequest } from "./filter";
-import { Request, Response } from "./k8s/types";
+import { MutateResponse, Request } from "./k8s/types";
 import { Secret } from "./k8s/upstream";
 import Log from "./logger";
-import { PeprRequest } from "./request";
+import { PeprMutateRequest } from "./mutate-request";
 import { ModuleConfig } from "./types";
-import { convertFromBase64Map, convertToBase64Map } from "./utils";
+import { base64Encode, convertFromBase64Map, convertToBase64Map } from "./utils";
 
-export async function processor(
+export async function mutateProcessor(
   config: ModuleConfig,
   capabilities: Capability[],
   req: Request,
-  parentPrefix: string
-): Promise<Response> {
-  const wrapped = new PeprRequest(req);
-  const response: Response = {
+  reqMetadata: Record<string, string>,
+): Promise<MutateResponse> {
+  const wrapped = new PeprMutateRequest(req);
+  const response: MutateResponse = {
     uid: req.uid,
     warnings: [],
     allowed: false,
   };
 
   // Track whether any capability matched the request
-  let matchedCapabilityAction = false;
+  let matchedAction = false;
 
   // Track data fields that should be skipped during decoding
   let skipDecode: string[] = [];
@@ -37,21 +38,26 @@ export async function processor(
     skipDecode = convertFromBase64Map(wrapped.Raw as unknown as Secret);
   }
 
-  Log.info(`Processing request`, parentPrefix);
+  Log.info(reqMetadata, `Processing request`);
 
   for (const { name, bindings } of capabilities) {
-    const prefix = `${parentPrefix} ${name}:`;
+    const actionMetadata = { ...reqMetadata, name };
 
     for (const action of bindings) {
+      // Skip this action if it's not a mutate action
+      if (!action.mutateCallback) {
+        continue;
+      }
+
       // Continue to the next action without doing anything if this one should be skipped
       if (shouldSkipRequest(action, req)) {
         continue;
       }
 
-      const label = action.callback.name;
-      Log.info(`Processing matched action ${label}`, prefix);
+      const label = action.mutateCallback.name;
+      Log.info(actionMetadata, `Processing matched action ${label}`);
 
-      matchedCapabilityAction = true;
+      matchedAction = true;
 
       // Add annotations to the request to indicate that the capability started processing
       // this will allow tracking of failed mutations that were permitted to continue
@@ -71,25 +77,30 @@ export async function processor(
 
       try {
         // Run the action
-        await action.callback(wrapped);
+        await action.mutateCallback(wrapped);
 
-        Log.info(`Action succeeded`, prefix);
+        Log.info(actionMetadata, `Action succeeded`);
 
         // Add annotations to the request to indicate that the capability succeeded
         updateStatus("succeeded");
       } catch (e) {
+        Log.warn(actionMetadata, `Action failed: ${e}`);
+        updateStatus("warning");
+
         // Annoying ts false positive
         response.warnings = response.warnings || [];
         response.warnings.push(`Action failed: ${e}`);
 
-        // If errors are not allowed, note the failure in the Response
-        if (config.onError) {
-          Log.error(`Action failed: ${e}`, prefix);
-          response.result = "Pepr module configured to reject on error";
-          return response;
-        } else {
-          Log.warn(`Action failed: ${e}`, prefix);
-          updateStatus("warning");
+        switch (config.onError) {
+          case Errors.reject:
+            Log.error(actionMetadata, `Action failed: ${e}`);
+            response.result = "Pepr module configured to reject on error";
+            return response;
+
+          case Errors.audit:
+            response.auditAnnotations = response.auditAnnotations || {};
+            response.auditAnnotations[Date.now()] = e;
+            break;
         }
       }
     }
@@ -99,8 +110,8 @@ export async function processor(
   response.allowed = true;
 
   // If no capability matched the request, exit early
-  if (!matchedCapabilityAction) {
-    Log.info(`No matching capability action found`, parentPrefix);
+  if (!matchedAction) {
+    Log.info(reqMetadata, `No matching actions found`);
     return response;
   }
 
@@ -124,7 +135,7 @@ export async function processor(
     response.patchType = "JSONPatch";
     // Webhook must be base64-encoded
     // https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#response
-    response.patch = Buffer.from(JSON.stringify(patches)).toString("base64");
+    response.patch = base64Encode(JSON.stringify(patches));
   }
 
   // Remove the warnings array if it's empty
@@ -132,7 +143,7 @@ export async function processor(
     delete response.warnings;
   }
 
-  Log.debug(patches, parentPrefix);
+  Log.debug({ ...reqMetadata, patches }, `Patches generated`);
 
   return response;
 }