pepr 0.0.0-development

package/src/lib/assets/yaml.ts

@@ -0,0 +1,234 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { dumpYaml } from "@kubernetes/client-node";
+import crypto from "crypto";
+import { promises as fs } from "fs";
+
+import { Assets } from ".";
+import { apiTokenSecret, service, tlsSecret, watcherService } from "./networking";
+import { deployment, moduleSecret, namespace, watcher } from "./pods";
+import { clusterRole, clusterRoleBinding, serviceAccount, storeRole, storeRoleBinding } from "./rbac";
+import { webhookConfig } from "./webhooks";
+
+// Helm Chart overrides file (values.yaml) generated from assets
+export async function overridesFile({ hash, name, image, config, apiToken }: Assets, path: string) {
+  const overrides = {
+    secrets: {
+      apiToken: Buffer.from(apiToken).toString("base64"),
+    },
+    hash,
+    namespace: {
+      annotations: {},
+      labels: {
+        "pepr.dev": "",
+      },
+    },
+    uuid: name,
+    admission: {
+      terminationGracePeriodSeconds: 5,
+      failurePolicy: config.onError === "reject" ? "Fail" : "Ignore",
+      webhookTimeout: config.webhookTimeout,
+      env: [
+        { name: "PEPR_WATCH_MODE", value: "false" },
+        { name: "PEPR_PRETTY_LOG", value: "false" },
+        { name: "LOG_LEVEL", value: "info" },
+      ],
+      image,
+      annotations: {
+        "pepr.dev/description": `${config.description}` || "",
+      },
+      labels: {
+        app: name,
+        "pepr.dev/controller": "admission",
+        "pepr.dev/uuid": config.uuid,
+      },
+      securityContext: {
+        runAsUser: 65532,
+        runAsGroup: 65532,
+        runAsNonRoot: true,
+        fsGroup: 65532,
+      },
+      resources: {
+        requests: {
+          memory: "64Mi",
+          cpu: "100m",
+        },
+        limits: {
+          memory: "256Mi",
+          cpu: "500m",
+        },
+      },
+      containerSecurityContext: {
+        runAsUser: 65532,
+        runAsGroup: 65532,
+        runAsNonRoot: true,
+        allowPrivilegeEscalation: false,
+        capabilities: {
+          drop: ["ALL"],
+        },
+      },
+      podAnnotations: {},
+      nodeSelector: {},
+      tolerations: [],
+      extraVolumeMounts: [],
+      extraVolumes: [],
+      affinity: {},
+    },
+    watcher: {
+      terminationGracePeriodSeconds: 5,
+      env: [
+        { name: "PEPR_WATCH_MODE", value: "true" },
+        { name: "PEPR_PRETTY_LOG", value: "false" },
+        { name: "LOG_LEVEL", value: "info" },
+      ],
+      image,
+      annotations: {
+        "pepr.dev/description": `${config.description}` || "",
+      },
+      labels: {
+        app: `${name}-watcher`,
+        "pepr.dev/controller": "watcher",
+        "pepr.dev/uuid": config.uuid,
+      },
+      securityContext: {
+        runAsUser: 65532,
+        runAsGroup: 65532,
+        runAsNonRoot: true,
+        fsGroup: 65532,
+      },
+      resources: {
+        requests: {
+          memory: "64Mi",
+          cpu: "100m",
+        },
+        limits: {
+          memory: "256Mi",
+          cpu: "500m",
+        },
+      },
+      containerSecurityContext: {
+        runAsUser: 65532,
+        runAsGroup: 65532,
+        runAsNonRoot: true,
+        allowPrivilegeEscalation: false,
+        capabilities: {
+          drop: ["ALL"],
+        },
+      },
+      nodeSelector: {},
+      tolerations: [],
+      extraVolumeMounts: [],
+      extraVolumes: [],
+      affinity: {},
+      podAnnotations: {},
+    },
+  };
+  if (process.env.PEPR_MODE === "dev") {
+    overrides.admission.env.push({ name: "ZARF_VAR", value: "###ZARF_VAR_THING###" });
+    overrides.watcher.env.push({ name: "ZARF_VAR", value: "###ZARF_VAR_THING###" });
+    overrides.admission.env.push({ name: "MY_CUSTOM_VAR", value: "example-value" });
+    overrides.watcher.env.push({ name: "MY_CUSTOM_VAR", value: "example-value" });
+  }
+
+  await fs.writeFile(path, dumpYaml(overrides, { noRefs: true, forceQuotes: true }));
+}
+export function zarfYaml({ name, image, config }: Assets, path: string) {
+  const zarfCfg = {
+    kind: "ZarfPackageConfig",
+    metadata: {
+      name,
+      description: `Pepr Module: ${config.description}`,
+      url: "https://github.com/defenseunicorns/pepr",
+      version: `${config.appVersion || "0.0.1"}`,
+    },
+    components: [
+      {
+        name: "module",
+        required: true,
+        manifests: [
+          {
+            name: "module",
+            namespace: "pepr-system",
+            files: [path],
+          },
+        ],
+        images: [image],
+      },
+    ],
+  };
+
+  return dumpYaml(zarfCfg, { noRefs: true });
+}
+
+export function zarfYamlChart({ name, image, config }: Assets, path: string) {
+  const zarfCfg = {
+    kind: "ZarfPackageConfig",
+    metadata: {
+      name,
+      description: `Pepr Module: ${config.description}`,
+      url: "https://github.com/defenseunicorns/pepr",
+      version: `${config.appVersion || "0.0.1"}`,
+    },
+    components: [
+      {
+        name: "module",
+        required: true,
+        charts: [
+          {
+            name: "module",
+            namespace: "pepr-system",
+            version: `${config.appVersion || "0.0.1"}`,
+            localPath: path,
+          },
+        ],
+        images: [image],
+      },
+    ],
+  };
+
+  return dumpYaml(zarfCfg, { noRefs: true });
+}
+
+export async function allYaml(assets: Assets, rbacMode: string) {
+  const { name, tls, apiToken, path } = assets;
+
+  const code = await fs.readFile(path);
+
+  // Generate a hash of the code
+  assets.hash = crypto.createHash("sha256").update(code).digest("hex");
+
+  const mutateWebhook = await webhookConfig(assets, "mutate", assets.config.webhookTimeout);
+  const validateWebhook = await webhookConfig(assets, "validate", assets.config.webhookTimeout);
+  const watchDeployment = watcher(assets, assets.hash, assets.buildTimestamp);
+
+  const resources = [
+    namespace(assets.config.customLabels?.namespace),
+    clusterRole(name, assets.capabilities, rbacMode),
+    clusterRoleBinding(name),
+    serviceAccount(name),
+    apiTokenSecret(name, apiToken),
+    tlsSecret(name, tls),
+    deployment(assets, assets.hash, assets.buildTimestamp),
+    service(name),
+    watcherService(name),
+    moduleSecret(name, code, assets.hash),
+    storeRole(name),
+    storeRoleBinding(name),
+  ];
+
+  if (mutateWebhook) {
+    resources.push(mutateWebhook);
+  }
+
+  if (validateWebhook) {
+    resources.push(validateWebhook);
+  }
+
+  if (watchDeployment) {
+    resources.push(watchDeployment);
+  }
+
+  // Convert the resources to a single YAML string
+  return resources.map(r => dumpYaml(r, { noRefs: true })).join("---\n");
+}

package/src/lib/capability.ts

@@ -0,0 +1,314 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { GenericClass, GroupVersionKind, modelToGroupVersionKind } from "kubernetes-fluent-client";
+import { WatchAction } from "kubernetes-fluent-client/dist/fluent/types";
+import { pickBy } from "ramda";
+
+import Log from "./logger";
+import { isBuildMode, isDevMode, isWatchMode } from "./module";
+import { PeprStore, Storage } from "./storage";
+import { OnSchedule, Schedule } from "./schedule";
+import {
+  Binding,
+  BindingFilter,
+  BindingWithName,
+  CapabilityCfg,
+  CapabilityExport,
+  Event,
+  MutateAction,
+  MutateActionChain,
+  ValidateAction,
+  ValidateActionChain,
+  WhenSelector,
+} from "./types";
+
+const registerAdmission = isBuildMode() || !isWatchMode();
+const registerWatch = isBuildMode() || isWatchMode() || isDevMode();
+
+/**
+ * A capability is a unit of functionality that can be registered with the Pepr runtime.
+ */
+export class Capability implements CapabilityExport {
+  #name: string;
+  #description: string;
+  #namespaces?: string[] | undefined;
+  #bindings: Binding[] = [];
+  #store = new Storage();
+  #scheduleStore = new Storage();
+  #registered = false;
+  #scheduleRegistered = false;
+  hasSchedule: boolean;
+
+  /**
+   * Run code on a schedule with the capability.
+   *
+   * @param schedule The schedule to run the code on
+   * @returns
+   */
+  OnSchedule: (schedule: Schedule) => void = (schedule: Schedule) => {
+    const { name, every, unit, run, startTime, completions } = schedule;
+    this.hasSchedule = true;
+
+    if (process.env.PEPR_WATCH_MODE === "true" || process.env.PEPR_MODE === "dev") {
+      // Only create/watch schedule store if necessary
+
+      // Create a new schedule
+      const newSchedule: Schedule = {
+        name,
+        every,
+        unit,
+        run,
+        startTime,
+        completions,
+      };
+
+      this.#scheduleStore.onReady(() => {
+        new OnSchedule(newSchedule).setStore(this.#scheduleStore);
+      });
+    }
+  };
+
+  /**
+   * Store is a key-value data store that can be used to persist data that should be shared
+   * between requests. Each capability has its own store, and the data is persisted in Kubernetes
+   * in the `pepr-system` namespace.
+   *
+   * Note: You should only access the store from within an action.
+   */
+  Store: PeprStore = {
+    clear: this.#store.clear,
+    getItem: this.#store.getItem,
+    removeItem: this.#store.removeItem,
+    removeItemAndWait: this.#store.removeItemAndWait,
+    setItem: this.#store.setItem,
+    subscribe: this.#store.subscribe,
+    onReady: this.#store.onReady,
+    setItemAndWait: this.#store.setItemAndWait,
+  };
+
+  /**
+   * ScheduleStore is a key-value data store used to persist schedule data that should be shared
+   * between intervals. Each Schedule shares store, and the data is persisted in Kubernetes
+   * in the `pepr-system` namespace.
+   *
+   * Note: There is no direct access to schedule store
+   */
+  ScheduleStore: PeprStore = {
+    clear: this.#scheduleStore.clear,
+    getItem: this.#scheduleStore.getItem,
+    removeItemAndWait: this.#scheduleStore.removeItemAndWait,
+    removeItem: this.#scheduleStore.removeItem,
+    setItemAndWait: this.#scheduleStore.setItemAndWait,
+    setItem: this.#scheduleStore.setItem,
+    subscribe: this.#scheduleStore.subscribe,
+    onReady: this.#scheduleStore.onReady,
+  };
+
+  get bindings() {
+    return this.#bindings;
+  }
+
+  get name() {
+    return this.#name;
+  }
+
+  get description() {
+    return this.#description;
+  }
+
+  get namespaces() {
+    return this.#namespaces || [];
+  }
+
+  constructor(cfg: CapabilityCfg) {
+    this.#name = cfg.name;
+    this.#description = cfg.description;
+    this.#namespaces = cfg.namespaces;
+    this.hasSchedule = false;
+
+    Log.info(`Capability ${this.#name} registered`);
+    Log.debug(cfg);
+  }
+
+  /**
+   * Register the store with the capability. This is called automatically by the Pepr controller.
+   *
+   * @param store
+   */
+  registerScheduleStore = () => {
+    Log.info(`Registering schedule store for ${this.#name}`);
+
+    if (this.#scheduleRegistered) {
+      throw new Error(`Schedule store already registered for ${this.#name}`);
+    }
+
+    this.#scheduleRegistered = true;
+
+    // Pass back any ready callback to the controller
+    return {
+      scheduleStore: this.#scheduleStore,
+    };
+  };
+
+  /**
+   * Register the store with the capability. This is called automatically by the Pepr controller.
+   *
+   * @param store
+   */
+  registerStore = () => {
+    Log.info(`Registering store for ${this.#name}`);
+
+    if (this.#registered) {
+      throw new Error(`Store already registered for ${this.#name}`);
+    }
+
+    this.#registered = true;
+
+    // Pass back any ready callback to the controller
+    return {
+      store: this.#store,
+    };
+  };
+
+  /**
+   * The When method is used to register a action to be executed when a Kubernetes resource is
+   * processed by Pepr. The action will be executed if the resource matches the specified kind and any
+   * filters that are applied.
+   *
+   * @param model the KubernetesObject model to match
+   * @param kind if using a custom KubernetesObject not available in `a.*`, specify the GroupVersionKind
+   * @returns
+   */
+  When = <T extends GenericClass>(model: T, kind?: GroupVersionKind): WhenSelector<T> => {
+    const matchedKind = modelToGroupVersionKind(model.name);
+
+    // If the kind is not specified and the model is not a KubernetesObject, throw an error
+    if (!matchedKind && !kind) {
+      throw new Error(`Kind not specified for ${model.name}`);
+    }
+
+    const binding: Binding = {
+      model,
+      // If the kind is not specified, use the matched kind from the model
+      kind: kind || matchedKind,
+      event: Event.Any,
+      filters: {
+        name: "",
+        namespaces: [],
+        labels: {},
+        annotations: {},
+      },
+    };
+
+    const bindings = this.#bindings;
+    const prefix = `${this.#name}: ${model.name}`;
+    const commonChain = { WithLabel, WithAnnotation, Mutate, Validate, Watch, Reconcile };
+    const isNotEmpty = (value: object) => Object.keys(value).length > 0;
+    const log = (message: string, cbString: string) => {
+      const filteredObj = pickBy(isNotEmpty, binding.filters);
+
+      Log.info(`${message} configured for ${binding.event}`, prefix);
+      Log.info(filteredObj, prefix);
+      Log.debug(cbString, prefix);
+    };
+
+    function Validate(validateCallback: ValidateAction<T>): ValidateActionChain<T> {
+      if (registerAdmission) {
+        log("Validate Action", validateCallback.toString());
+
+        // Push the binding to the list of bindings for this capability as a new BindingAction
+        // with the callback function to preserve
+        bindings.push({
+          ...binding,
+          isValidate: true,
+          validateCallback,
+        });
+      }
+
+      return { Watch, Reconcile };
+    }
+
+    function Mutate(mutateCallback: MutateAction<T>): MutateActionChain<T> {
+      if (registerAdmission) {
+        log("Mutate Action", mutateCallback.toString());
+
+        // Push the binding to the list of bindings for this capability as a new BindingAction
+        // with the callback function to preserve
+        bindings.push({
+          ...binding,
+          isMutate: true,
+          mutateCallback,
+        });
+      }
+
+      // Now only allow adding actions to the same binding
+      return { Watch, Validate, Reconcile };
+    }
+
+    function Watch(watchCallback: WatchAction<T>) {
+      if (registerWatch) {
+        log("Watch Action", watchCallback.toString());
+
+        bindings.push({
+          ...binding,
+          isWatch: true,
+          watchCallback,
+        });
+      }
+    }
+
+    function Reconcile(watchCallback: WatchAction<T>) {
+      if (registerWatch) {
+        log("Reconcile Action", watchCallback.toString());
+
+        bindings.push({
+          ...binding,
+          isWatch: true,
+          isQueue: true,
+          watchCallback,
+        });
+      }
+    }
+
+    function InNamespace(...namespaces: string[]): BindingWithName<T> {
+      Log.debug(`Add namespaces filter ${namespaces}`, prefix);
+      binding.filters.namespaces.push(...namespaces);
+      return { ...commonChain, WithName };
+    }
+
+    function WithName(name: string): BindingFilter<T> {
+      Log.debug(`Add name filter ${name}`, prefix);
+      binding.filters.name = name;
+      return commonChain;
+    }
+
+    function WithLabel(key: string, value = ""): BindingFilter<T> {
+      Log.debug(`Add label filter ${key}=${value}`, prefix);
+      binding.filters.labels[key] = value;
+      return commonChain;
+    }
+
+    function WithAnnotation(key: string, value = ""): BindingFilter<T> {
+      Log.debug(`Add annotation filter ${key}=${value}`, prefix);
+      binding.filters.annotations[key] = value;
+      return commonChain;
+    }
+
+    function bindEvent(event: Event) {
+      binding.event = event;
+      return {
+        ...commonChain,
+        InNamespace,
+        WithName,
+      };
+    }
+
+    return {
+      IsCreatedOrUpdated: () => bindEvent(Event.CreateOrUpdate),
+      IsCreated: () => bindEvent(Event.Create),
+      IsUpdated: () => bindEvent(Event.Update),
+      IsDeleted: () => bindEvent(Event.Delete),
+    };
+  };
+}