pepr 0.12.1 → 0.13.0

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;
 
@@ -163,6 +153,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,56 +1,99 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
-import promClient from "prom-client";
+import promClient, { Counter, Summary, Registry } from "prom-client";
 import { performance } from "perf_hooks";
+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>;
+  private _registry: Registry;
+  private _counters: Map<string, Counter<string>> = new Map();
+  private _summaries: Map<string, Summary<string>> = new Map();
+  private _prefix: string;
+
+  private _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.
    */
   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");
+  }
+  private getMetricName(name: string) {
+    return `${this._prefix}_${name}`;
+  }
 
-    this._errors = new promClient.Counter({
-      name: `${prefix}_errors`,
-      help: "error counter",
+  private 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;
+    }
+    const metric = new MetricType({
+      name: this.getMetricName(name),
+      help,
       registers: [this._registry],
     });
+    collection.set(this.getMetricName(name), metric);
+  }
 
-    this._alerts = new promClient.Counter({
-      name: `${prefix}_alerts`,
-      help: "alerts counter",
-      registers: [this._registry],
-    });
+  addCounter(name: string, help: string) {
+    this.addMetric(this._counters, promClient.Counter, name, help);
+  }
 
-    this._summary = new promClient.Summary({
-      name: `${prefix}_summary`,
-      help: "summary",
-      registers: [this._registry],
-    });
+  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);
   }
 
   /**
@@ -64,9 +107,10 @@ export class MetricsCollector {
   /**
    * Observes the duration since the provided start time and updates the summary.
    * @param {number} startTime - The start time.
+   * @param {string} 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);
   }
 
   /**

package/src/lib/module.ts

@@ -1,18 +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 { MutateResponse, Request, ValidateResponse } from "./k8s/types";
 import { ModuleConfig } from "./types";
 
-const alwaysIgnore = {
-  namespaces: ["kube-system", "pepr-system"],
-  labels: [{ "pepr.dev": "ignore" }],
-};
-
 export type PackageJSON = {
   description: string;
   pepr: ModuleConfig;
@@ -25,7 +20,7 @@ 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 {
@@ -39,12 +34,19 @@ export class PeprModule {
    * @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()`.
    */
   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
+    const validOnErrors = ["ignore", "warn", "fail"];
+    if (!validOnErrors.includes(config.onError || "")) {
+      throw new Error(`Invalid onErrors value: ${config.onError}`);
+    }
+
     // Handle build mode
-    if (process.env.PEPR_MODE === "build") {
-      process.send?.({ capabilities });
+    if (process.env.PEPR_MODE === "build" && process.send) {
+      // Send capability map to parent process
+      process.send(capabilities);
       return;
     }
 

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

@@ -5,28 +5,28 @@ import jsonPatch from "fast-json-patch";
 
 import { Capability } from "./capability";
 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 +37,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 +76,29 @@ 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 "reject":
+            Log.error(actionMetadata, `Action failed: ${e}`);
+            response.result = "Pepr module configured to reject on error";
+            return response;
+
+          case "audit":
+            // @todo: implement audit logging
+            break;
         }
       }
     }
@@ -99,8 +108,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 +133,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 +141,7 @@ export async function processor(
     delete response.warnings;
   }
 
-  Log.debug(patches, parentPrefix);
+  Log.debug({ ...reqMetadata, patches }, `Patches generated`);
 
   return response;
 }

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

@@ -10,7 +10,7 @@ import { DeepPartial } from "./types";
  * The RequestWrapper class provides methods to modify Kubernetes objects in the context
  * of a mutating webhook request.
  */
-export class PeprRequest<T extends KubernetesObject> {
+export class PeprMutateRequest<T extends KubernetesObject> {
   public Raw: T;
 
   get PermitSideEffects() {
@@ -42,7 +42,7 @@ export class PeprRequest<T extends KubernetesObject> {
   }
 
   /**
-   * Creates a new instance of the Action class.
+   * Creates a new instance of the action class.
    * @param input - The request object containing the Kubernetes resource to modify.
    */
   constructor(private _input: Request<T>) {
@@ -72,7 +72,7 @@ export class PeprRequest<T extends KubernetesObject> {
    * Updates a label on the Kubernetes resource.
    * @param key - The key of the label to update.
    * @param value - The value of the label.
-   * @returns The current Action instance for method chaining.
+   * @returns The current action instance for method chaining.
    */
   SetLabel(key: string, value: string) {
     const ref = this.Raw;
@@ -88,7 +88,7 @@ export class PeprRequest<T extends KubernetesObject> {
    * Updates an annotation on the Kubernetes resource.
    * @param key - The key of the annotation to update.
    * @param value - The value of the annotation.
-   * @returns The current Action instance for method chaining.
+   * @returns The current action instance for method chaining.
    */
   SetAnnotation(key: string, value: string) {
     const ref = this.Raw;