Pepr is on a mission to save Kubernetes from the tyranny of YAML, intimidating glue code, bash scripts, and other makeshift solutions. As a Kubernetes controller, Pepr empowers you to define Kubernetes transformations using TypeScript, without software development expertise thanks to plain-english configurations. Pepr transforms a patchwork of forks, scripts, overlays, and other chaos into a cohesive, well-structured, and maintainable system. With Pepr, you can seamlessly transition IT ops tribal knowledge into code, simplifying documentation, testing, validation, and coordination of changes for a more predictable outcome.

• Zero-config K8s webhook mutations and validations soon.
• Human-readable fluent API for generating Pepr Capabilities
• Generate new K8s resources based off of cluster resource changes
• Perform other exec/API calls based off of cluster resources changes or any other abitrary schedule
• Out of the box airgap support with Zarf
• Entire NPM ecosystem available for advanced operations
• Realtime K8s debugging system for testing/reacting to cluster changes
• Controller network isolation and tamper-resistent module execution
• Automatic least-privelege RBAC generation soon
• AMD64 and ARM64 support

This quick sample shows how to react to a ConfigMap being created or updated in the cluster. It adds a label and annotation to the ConfigMap and adds some data to the ConfigMap. Finally, it logs a message to the Pepr controller logs. For more see CapabilityActions.

When(a.ConfigMap)
  .IsCreatedOrUpdated()
  .InNamespace("pepr-demo")
  .WithLabel("unicorn", "rainbow")
  .Then(request => {
    // Add a label and annotation to the ConfigMap
    request
      .SetLabel("pepr", "was-here")
      .SetAnnotation("pepr.dev", "annotations-work-too");

    // Add some data to the ConfigMap
    request.Raw.data["doug-says"] = "Pepr is awesome!";

    // Log a message to the Pepr controller logs
    Log.info("A 🦄 ConfigMap was created or updated:");
  });

# Install Pepr (you can also use npx)
npm i -g pepr

# Initialize a new Pepr Module
pepr init

# Follow the prompts...

# If you already have a Kind or K3d cluster you want to use, skip this step
npm run k3d-setup

# Start playing with Pepr now
# If using another local K8s distro instead of k3d, run `pepr dev --host host.docker.internal`
pepr dev
kubectl apply -f capabilities/hello-pepr.samples.yaml

# Be amazed and ⭐️ this repo

Pepr is an open-source project that helps IT Ops teams of all skill levels manage and modify resources in a Kubernetes (K8s) cluster using TypeScript. Kubernetes simplifies the management of multiple computers working together to run and scale applications. Pepr acts as a smart assistant, automatically changing or validating parts of the system as needed.

TypeScript is used to create Pepr capabilities, benefiting from its error-catching and clean code features, but without requiring specialized software engineering experience or prior Typescript knowledge. Pepr also provides a user-friendly interface for writing commands in plain English in a Fluent Interface style.

Capabilities are logical groupings of actions, which are the atomic units of change within Pepr. Actions modify, create, or interact with resources in response to events. Pepr's capabilities and actions work together in the cluster, offering a versatile and customizable tool that enhances Kubernetes by building glue code or plumbing for system interactions. This makes Pepr useful for various tasks such as creating robust policy engines or seamlessly connecting applications.

Imagine Pepr as a smart home system where different devices communicate with each other. Pepr provides instructions, simplifying the management of the smart home. The project enables both expert and novice capability authors to improve management and interactions within the Kubernetes environment, making its features accessible to everyone.

A module is the top-level collection of capabilities. It is a single, complete TypeScript project that includes an entry point to load all the configuration and capabilities, along with their CapabilityActions. During the Pepr build process, each module produces a unique Kubernetes MutatingWebhookConfiguration and ValidatingWebhookConfiguration, along with a secret containing the transpiled and compressed TypeScript code. The webhooks and secret are deployed into the Kubernetes cluster for processing by a common Pepr controller.

See Module for more details.

A capability is set of related CapabilityActions that work together to achieve a specific transformation or operation on Kubernetes resources. Capabilities are user-defined and can include one or more CapabilityActions. They are defined within a Pepr module and can be used in both MutatingWebhookConfigurations and ValidatingWebhookConfigurations. A Capability can have a specific scope, such as mutating or validating, and can be reused in multiple Pepr modules.

See Capabilities for more details.

CapabilityAction is a discrete set of behaviors defined in a single function that acts on a given Kubernetes GroupVersionKind (GVK) passed in from Kubernetes. CapabilityActions are the atomic operations that are performed on Kubernetes resources by Pepr.

For example, a CapabilityAction could be responsible for adding a specific label to a Kubernetes resource, or for modifying a specific field in a resource's metadata. CapabilityActions can be grouped together within a Capability to provide a more comprehensive set of operations that can be performed on Kubernetes resources.

See CapabilityActions for more details.

graph LR

subgraph "Module 3 (Validate Only)"
    direction LR
    Q[entrypoint 3] --> R[Validate Webhook];
    R --> S[Capability a <br><i>- action 1<br>- action 2</i>];
    S --> T[Capability b <br><i>- action 1<br>- action 2</i>];
end

subgraph "Module 2 (Mutate Only)"
    direction LR
    K[entrypoint 2] --> L[Mutate Webhook];
    L --> M[Capability a <br><i>- action 1<br>- action 2</i>];
    M --> N[Capability b <br><i>- action 1<br>- action 2<br>- action 3</i>];
    N --> O[Capability c <br><i>- action 1</i>];
end

subgraph "Module 1 (Mutate & Validate)"
    direction LR
    A[entrypoint 1] --> B[Mutate Webhook];
    A --> C[Validate Webhook];
    B --> D[Capability a <br><i>- action 1</i>];
    D --> E[Capability b <br><i>- action 1<br>- action 2</i>];
    E --> F[Capability c <br><i>- action 1<br>- action 2</i>];
    C --> G[Capability d <br><i>- action 1<br>- action 2</i>];
    G --> H[Capability e <br><i>- action 1</i>];
    H --> I[Capability f <br><i>- action 1<br>- action 2<br>- action 3</i>];
end



%% Defining node styles
classDef Validate fill:#66ff66,color:#000;
classDef Mutate fill:#5786ea,color:#000;


class L,M,N,O Mutate;
class B,D,E,F Mutate;

class R,S,T Validate;
class C,G,H,I Validate;

TypeScript is a strongly typed, object-oriented programming language built on top of JavaScript. It provides optional static typing and a rich type system, allowing developers to write more robust code. TypeScript is transpiled to JavaScript, enabling it to run in any environment that supports JavaScript. Pepr allows you to use JavaScript or TypeScript to write capabilities, but TypeScript is recommended for its type safety and rich type system. You can learn more about TypeScript here.

Kubernetes mutating webhooksare a powerful feature that allows users to intercept and modify Kubernetes API requests, such as resource creation or updates, before they are persisted to the cluster. They can be used to enforce security policies, default values, or perform custom transformations on resources.

Pepr uses Kubernetes mutating webhooks to react to cluster resource events and apply user-defined capabilities, which are sets of Kubernetes transformations/actions.