Pepr Kubernetes Application Engine

The Pepr Store is a lightweight, asynchronous key-value store designed for use within Pepr Capabilities. It is specifically built to solve two problems in Kubernetes admission controllers:

1. Complex/Long-running operations: It provides a way to manage state that is difficult to handle within the standard Mutate, Validate, and Watch action lifecycles.
2. Data Sharing: It allows sharing data between different actions and different replicas of the admission controller and watch controller automatically.

How it works internally: Behind the scenes, all store instances within a single Pepr Module are stored within a single Custom Resource Definition (CRD) that is automatically created when the module is deployed. To maintain performance at scale, the store uses Kubernetes watches, batch processing, and patch operations for efficient reads and writes.

Pepr provides two primary mechanisms for handling Kubernetes events, differing in how they manage event order and processing:

• .Watch(): Processes events immediately as they arrive. It does not guarantee event ordering. Use this when immediate reaction is acceptable and the sequence of events (e.g., an update followed by a delete) does not impact the correctness of your logic.
• .Reconcile(): Processes events sequentially through a queue. This ensures that events are handled in the order they were received, which is critical for preventing race conditions during resource updates or deletions.

Recommendation: For most real-world workloads where consistency and event order are critical, use .Reconcile() with the kindNsName configuration.

/* Use .Reconcile() when consistency and event order are critical */

Pepr uses a hybrid build strategy to support both CommonJS (CJS) and ECMA Script Modules (ESM). While the project was originally focused on CJS, it now supports both module types. For the most up-to-date information on how Pepr handles module resolution, refer to ADR-0021 (TypeScript Module Resolution).

This strategy ensures:

• Efficient Debugging: Maintains the pepr dev experience with zero-config breakpoint inspection in VSCode without offset issues between TS source and transpiled code.
• Reliable Bundling: Produces a single-file, small-footprint output for the runtime controller that avoids ESM import breakage.
• Unified Workflow: Uses the same code and configurations for both pepr dev and pepr build, reducing the risk of environment-specific bugs.

Pepr handles compliance through reporting rather than enforcement. Compliance enforcement is handled by the bindings themselves, while Pepr uses the external compliance-reporter library to aggregate and report on the status of those controls.

To implement compliance reporting, you use a pattern of registering controls and then mapping implementations to them. This allows Pepr to identify 'compliance gaps' where controls exist but lack sufficient implementation coverage.

Pepr uses husky to manage git hooks:

• pre-commit: Automatically runs linters to ensure code adheres to style guides.
• pre-push: Warns you if a branch has a large number of changed lines to encourage smaller, more reviewable PRs.

The pre-push hook is optional. You can opt-in by setting the PEPR_HOOK_OPT_IN=1 environment variable.

The PeprStore is backed by ETCD in a PeprStore resource.

Key Characteristics:

• Update Interval: Updates occur at 5-second intervals when an array of patches is sent to the Kubernetes API Server.
• Consistency Model: The store is eventually consistent, not transactional. The last operation within an interval will be persisted, potentially overwriting other operations.
• Caution: Because changes are not guaranteed to occur simultaneously, you must manage errors and ensure consistency carefully in your logic.

Pepr's backward compatibility guarantees apply to four primary areas of the project. When upgrading, you should verify compatibility across these surfaces:

1. Public API: Function signatures, parameters, and return types for core abstractions like Actions, Capabilities, Store, and OnSchedule.
2. Configuration: YAML or JSON structures used for Pepr Modules, including Environment Variables and customization settings (e.g., log formats, reconcile configuration, Helm/package.json customizations).
3. Pepr SDK: Helper functions provided in the SDK for common tasks.
4. CLI Commands: All commands, flags, and output formats provided by the Pepr CLI.

Mutating admission webhooks in Pepr are invoked first to modify objects sent to the API server, allowing you to enforce custom defaults.

When a mutation is successful, Pepr annotates the object to indicate its status. The annotation format follows the pattern: <module-uuid>.<pepr-domain>/<capability-name>: succeeded.

For example, if a module has UUID static-test and a capability named hello-pepr, a successful mutation will result in the annotation: static-test.pepr.dev/hello-pepr: succeeded.

Filters are functions that evaluate an AdmissionReview or Watch event and return a boolean. They allow you to restrict Pepr actions (like Mutate or Validate) to only specific resources that meet defined criteria. You chain filter methods onto a resource type selector (e.g., When(a.ConfigMap)) to build a predicate. If the filter returns true, the subsequent action is executed; otherwise, it is skipped.

When(a.ConfigMap)
  .IsCreated()
  .InNamespace("webapp")
  .WithName("example-1")
  .WithLabel("app", "webapp")
  .Mutate(request => {
    // This only runs if the ConfigMap is new, in 'webapp' namespace, 
    // named 'example-1', and has label 'app=webapp'
    request.SetLabel("pepr", "was-here");
  });