{"id":14975854,"url":"https://github.com/defenseunicorns/pepr","last_synced_at":"2026-02-20T22:01:13.469Z","repository":{"id":151999723,"uuid":"611174067","full_name":"defenseunicorns/pepr","owner":"defenseunicorns","description":":unicorn: Type safe K8s middleware for humans ","archived":false,"fork":false,"pushed_at":"2025-05-13T16:39:21.000Z","size":8303,"stargazers_count":157,"open_issues_count":53,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-13T16:44:26.420Z","etag":null,"topics":["controller","fluent-api","gitops","k8s","kubernetes","kubernetes-controller","mutating-admission-webhook","npm","operator-framework","policy","typescript","validating-admission-webhook","webhook"],"latest_commit_sha":null,"homepage":"https://pepr.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/defenseunicorns.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-03-08T09:20:10.000Z","updated_at":"2025-05-13T16:21:30.000Z","dependencies_parsed_at":"2023-12-21T08:23:42.237Z","dependency_job_id":"28a1cadc-b713-4da5-9325-344810020b9d","html_url":"https://github.com/defenseunicorns/pepr","commit_stats":{"total_commits":990,"total_committers":33,"mean_commits":30.0,"dds":0.5545454545454546,"last_synced_commit":"900eb012351f8c7d77f5f644ea5ec158cd495e76"},"previous_names":[],"tags_count":162,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/defenseunicorns%2Fpepr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/defenseunicorns%2Fpepr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/defenseunicorns%2Fpepr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/defenseunicorns%2Fpepr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/defenseunicorns","download_url":"https://codeload.github.com/defenseunicorns/pepr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254374475,"owners_count":22060611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["controller","fluent-api","gitops","k8s","kubernetes","kubernetes-controller","mutating-admission-webhook","npm","operator-framework","policy","typescript","validating-admission-webhook","webhook"],"created_at":"2024-09-24T13:52:46.222Z","updated_at":"2026-02-20T22:01:13.461Z","avatar_url":"https://github.com/defenseunicorns.png","language":"TypeScript","readme":"# Pepr\n\n| | | |\n| :--- | :--- | :--- |\n| [![Pepr Documentation](https://img.shields.io/badge/docs--d25ba1)](https://docs.pepr.dev) | [![Npm package license](https://img.shields.io/npm/l/pepr)](https://npmjs.com/package/pepr) | [![Known Vulnerabilities](https://snyk.io/test/npm/pepr/badge.svg)](https://snyk.io/advisor/npm-package/pepr) |\n| [![Npm package version](https://img.shields.io/npm/v/pepr)](https://npmjs.com/package/pepr) | [![Npm package total downloads](https://img.shields.io/npm/dy/pepr)](https://npmjs.com/package/pepr) | [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/defenseunicorns/pepr/badge)](https://securityscorecards.dev/viewer/?uri=github.com/defenseunicorns/pepr) |\n| [![codecov](https://codecov.io/github/defenseunicorns/pepr/graph/badge.svg?token=7679Y9K1HB)](https://codecov.io/github/defenseunicorns/pepr) | [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](/docs/contribute/code-of-conduct) | |\n\n## **_Type safe Kubernetes middleware for humans_**\n\n\u003c!-- markdownlint-disable MD033 --\u003e\n\n\u003ctable border=\"0\" cellspacing=\"0\" cellpadding=\"0\"\u003e\n\u003ctr\u003e\n\u003ctd width=\"65%\" style=\"vertical-align: middle; border: none;\"\u003e\n\u003cdiv\u003e\nPepr simplifies Kubernetes management by providing an alternative to complex YAML configurations, custom scripts, and ad-hoc solutions.\nAs a Kubernetes controller, Pepr enables you to define Kubernetes transformations using TypeScript, accessible through straightforward configurations even without extensive development expertise.\nPepr transforms disparate implementation approaches into a cohesive, well-structured, and maintainable system.\nWith Pepr, you can efficiently convert organizational knowledge into code, improving documentation, testing, validation, and change management for more predictable outcomes.\n\u003c/div\u003e\n\u003c/td\u003e\n\u003ctd width=\"35%\" align=\"center\" style=\"vertical-align: middle; border: none;\"\u003e\n\u003cimg alt=\"The Pepr Logo\" width=\"100%\" src=\"_images/pepr.png\" /\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-enable MD033 --\u003e\n\n## Features\n\n- Zero-config K8s Mutating and Validating Webhooks plus Controller generation\n- Automatic leader-elected K8s resource watching\n- Lightweight async key-value store backed by K8s for stateful operations with the [Pepr Store](docs/user-guide/store.md)\n- Human-readable fluent API for generating [Pepr Capabilities](#capability)\n- A fluent API for creating/modifying/watching and server-side applying K8s resources via [Kubernetes Fluent Client](https://github.com/defenseunicorns/kubernetes-fluent-client)\n- Generate new K8s resources based off of cluster resource changes\n- Perform other exec/API calls based off of cluster resources changes or any other arbitrary schedule\n- Out of the box airgap support with [Zarf](https://zarf.dev)\n- Entire NPM ecosystem available for advanced operations\n- Realtime K8s debugging system for testing/reacting to cluster changes\n- Controller network isolation and tamper-resistant module execution\n- Least-privilege [RBAC](docs/user-guide/rbac.md) generation\n- AMD64 and ARM64 support\n\n## Example Pepr Action\n\nThis quick sample shows how to react to a ConfigMap being created or updated in the cluster.\nIt adds a label and annotation to the ConfigMap and adds some data to the ConfigMap.\nIt also creates a Validating Webhook to make sure the \"pepr\" label still exists.\nFinally, after the ConfigMap is created, it logs a message to the Pepr controller and creates or updates a separate ConfigMap with the [kubernetes-fluent-client](https://github.com/defenseunicorns/kubernetes-fluent-client) using server-side apply.\nFor more details see [actions](docs/actions/README.md) section.\n\n```ts\nWhen(a.ConfigMap)\n  .IsCreatedOrUpdated()\n  .InNamespace(\"pepr-demo\")\n  .WithLabel(\"example\", \"value\")\n  // Create a Mutate Action for the ConfigMap\n  .Mutate(request =\u003e {\n    // Add a label and annotation to the ConfigMap\n    request.SetLabel(\"pepr\", \"was-here\").SetAnnotation(\"pepr.dev\", \"annotations-work-too\");\n\n    // Add some data to the ConfigMap\n    request.Raw.data[\"doug-says\"] = \"Pepr is awesome!\";\n\n    // Log a message to the Pepr controller logs\n    Log.info(\"A ConfigMap was created or updated:\");\n  })\n  // Create a Validate Action for the ConfigMap\n  .Validate(request =\u003e {\n    // Validate the ConfigMap has a specific label\n    if (request.HasLabel(\"pepr\")) {\n      return request.Approve();\n    }\n\n    // Reject the ConfigMap if it doesn't have the label\n    return request.Deny(\"ConfigMap must have the required pepr label\");\n  })\n  // Watch behaves like controller-runtime's Manager.Watch()\n  .Watch(async (cm, phase) =\u003e {\n    Log.info(cm, `ConfigMap was ${phase}.`);\n\n    // Apply a ConfigMap using K8s server-side apply (will create or update)\n    await K8s(kind.ConfigMap).Apply({\n      metadata: {\n        name: \"pepr-ssa-demo\",\n        namespace: \"pepr-demo-2\",\n      },\n      data: {\n        uid: cm.metadata.uid,\n      },\n    });\n  });\n```\n\n## Prerequisites\n\n- [Node.js](https://nodejs.org/en/) v20.0.0+ (even-numbered releases only)\n  - To ensure compatibility and optimal performance, it is recommended to use even-numbered releases of Node.js as they are stable releases and receive long-term support for three years.\n    Odd-numbered releases are experimental and may not be supported by certain libraries utilized in Pepr.\n\n- [npm](https://www.npmjs.com/) v10.1.0+\n\n- Recommended (optional) tools:\n  - [Visual Studio Code](https://code.visualstudio.com/) for inline debugging and [Pepr Capabilities](#capability) creation.\n  - A Kubernetes cluster for `npx pepr dev`. Pepr modules include `npm run k3d-setup` if you want to test locally with [K3d](https://k3d.io/) and [Docker](https://www.docker.com/).\n\n## Quick Start Guide\n\n```bash\n# Create a new Pepr Module\nnpx pepr init\n\n# If you already have a K3d cluster you want to use, skip this step\nnpm run k3d-setup\n\n# Start playing with Pepr now!\n# If using Kind, or another local k8s distro instead,\n# run `npx pepr dev --host \u003cyour_hostname\u003e`\nnpx pepr dev\nkubectl apply -f capabilities/hello-pepr.samples.yaml\n```\n\n\u003e [!TIP]\n\u003e Don't use IP as your `--host`, it's not supported. Make sure to check your\n\u003e local k8s distro documentation how to reach your localhost, which is where\n\u003e `pepr dev` is serving the code from.\n\n  \u003cvideo controls width=\"100%\"\u003e\n    \u003csource src=\"https://user-images.githubusercontent.com/882485/230895880-c5623077-f811-4870-bb9f-9bb8e5edc118.mp4\" type=\"video/mp4\"\u003e\n    \u003cp\u003eYour browser doesn't support HTML video. \u003ca href=\"https://user-images.githubusercontent.com/882485/230895880-c5623077-f811-4870-bb9f-9bb8e5edc118.mp4\"\u003eDownload the video\u003c/a\u003e instead.\u003c/p\u003e\n  \u003c/video\u003e\n\n## Concepts\n\n### Module\n\nA module is the top-level collection of capabilities.\nIt is a single, complete TypeScript project that includes an entry point to load all the configuration and capabilities, along with their actions.\nDuring the Pepr build process, each module produces a unique Kubernetes MutatingWebhookConfiguration and ValidatingWebhookConfiguration, along with a secret containing the transpiled and compressed TypeScript code.\nThe webhooks and secret are deployed into the Kubernetes cluster with their own isolated controller.\n\nSee [Module](docs/user-guide/pepr-modules.md) for more details.\n\n### Capability\n\nA capability is set of related actions that work together to achieve a specific transformation or operation on Kubernetes resources.\nCapabilities are user-defined and can include one or more actions.\nThey are defined within a Pepr module and can be used in both MutatingWebhookConfigurations and ValidatingWebhookConfigurations.\nA Capability can have a specific scope, such as mutating or validating, and can be reused in multiple Pepr modules.\n\nSee [Capabilities](docs/user-guide/capabilities.md) for more details.\n\n### Action\n\nAction is a discrete set of behaviors defined in a single function that acts on a given Kubernetes GroupVersionKind (GVK) passed in from Kubernetes.\nActions are the atomic operations that are performed on Kubernetes resources by Pepr.\n\nFor example, an action could be responsible for adding a specific label to a Kubernetes resource, or for modifying a specific field in a resource's metadata.\nActions can be grouped together within a Capability to provide a more comprehensive set of operations that can be performed on Kubernetes resources.\n\nThere are both `Mutate()` and `Validate()` Actions that can be used to modify or validate Kubernetes resources within the admission controller lifecycle.\nThere are also `Watch()` and `Reconcile()` actions that can be used to watch for changes to Kubernetes resources that already exist.\nFinally, the `Finalize()` can be used after `Watch()` or `Reconcile()` to perform cleanup operations when the resource is deleted.\n\nSee [actions](docs/actions/README.md) for more details.\n\n## Logical Pepr Flow\n\n![Arch Diagram](_images/pepr-arch.png)\n\n## TypeScript\n\n[TypeScript](https://www.typescriptlang.org/) is a strongly typed, object-oriented programming language built on top of JavaScript.\nIt provides optional static typing and a rich type system, allowing developers to write more robust code.\nTypeScript is transpiled to JavaScript, enabling it to run in any environment that supports JavaScript.\nPepr allows you to use JavaScript or TypeScript to write capabilities, but TypeScript is recommended for its type safety and rich type system.\nSee the [TypeScript docs](https://www.typescriptlang.org/docs/handbook/typescript-from-scratch.html) to learn more.\n\n## Community\n\nTo join our channel go to [Kubernetes Slack](https://communityinviter.com/apps/kubernetes/community) and join the `#pepr` channel.\n\n[contributors]: https://contrib.rocks/image?repo=defenseunicorns/pepr\n[![Contributor Chart][contributors]](https://github.com/defenseunicorns/pepr/graphs/contributors)\n\nMade with [contrib.rocks](https://contrib.rocks).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefenseunicorns%2Fpepr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdefenseunicorns%2Fpepr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefenseunicorns%2Fpepr/lists"}