docs.yml

site/content/en/v0.22.0/_index.md

@@ -2,7 +2,7 @@
 title: v0.22.0
 cascade:
   type: docs
-aliases: ["/current/"]
+aliases: []
 ---
 # Pepr
 

site/content/en/v0.22.1/OnSchedule.md

@@ -0,0 +1,84 @@
+---
+title: OnSchedule
+---
+
+
+The `OnSchedule` feature allows you to schedule and automate the execution of specific code at predefined intervals or schedules. This feature is designed to simplify recurring tasks and can serve as an alternative to traditional CronJobs. This code is designed to be run at the top level on a Capability, not within a function like `When`. 
+
+> **Note -** To use this feature in dev mode you MUST set `PEPR_WATCH_MODE="true"`. This is because the scheduler only runs on the watch controller and the watch controller is not started by default in dev mode.
+
+For example: `PEPR_WATCH_MODE="true" npx pepr dev`
+
+## Best Practices
+
+`OnSchedule` is designed for targeting intervals equal to or larger than 30 seconds due to the storage mechanism used to archive schedule info.
+
+## Usage
+
+Create a recurring task execution by calling the OnSchedule function with the following parameters:
+
+**name** - The unique name of the schedule.
+
+**every** - An integer that represents the frequency of the schedule in number of _units_.
+
+**unit** - A string specifying the time unit for the schedule (e.g., `seconds`, `minute`, `minutes`, `hour`, `hours`). 
+
+**startTime** - (Optional) A UTC timestamp indicating when the schedule should start. All date times must be provided in GMT. If not specified the schedule will start when the schedule store reports ready.
+
+**run** - A function that contains the code you want to execute on the defined schedule.  
+
+**completions** - (Optional) An integer indicating the maximum number of times the schedule should run to completion. If not specified the schedule will run indefinitely.
+
+
+## Examples
+
+Update a ConfigMap every 30 seconds:
+
+```typescript
+OnSchedule({
+    name: "hello-interval",
+    every: 30,
+    unit: "seconds",
+    run: async () => {
+      Log.info("Wait 30 seconds and create/update a ConfigMap");
+
+      try {
+        await K8s(kind.ConfigMap).Apply({
+          metadata: {
+            name: "last-updated",
+            namespace: "default",
+          },
+          data: {
+            count: `${new Date()}`,
+          },
+        });
+
+      } catch (error) {
+        Log.error(error, "Failed to apply ConfigMap using server-side apply.");
+      }
+    },
+  });
+```
+
+Refresh an AWSToken every 24 hours, with a delayed start of 30 seconds, running a total of 3 times:
+
+```typescript
+
+OnSchedule({
+  name: "refresh-aws-token",
+  every: 24,
+  unit: "hours",
+  startTime: new Date(new Date().getTime() + 1000 * 30),
+  run: async () => {
+    await RefreshAWSToken();
+  },
+  completions: 3,
+});
+```
+
+## Advantages 
+
+- Simplifies scheduling recurring tasks without the need for complex CronJob configurations.
+- Provides flexibility to define schedules in a human-readable format.
+- Allows you to execute code with precision at specified intervals.
+- Supports limiting the number of schedule completions for finite tasks.

site/content/en/v0.22.1/_index.md

@@ -0,0 +1,157 @@
+---
+title: v0.22.1
+cascade:
+  type: docs
+aliases: []
+---
+# Pepr
+
+[![Pepr Documentation](https://img.shields.io/badge/docs--d25ba1)](./README/)
+[![Npm package license](https://badgen.net/npm/license/pepr)](https://npmjs.com/package/pepr)
+[![Known Vulnerabilities](https://snyk.io/test/npm/pepr/badge.svg)](https://snyk.io/advisor/npm-package/pepr)
+[![Npm package version](https://badgen.net/npm/v/pepr)](https://npmjs.com/package/pepr)
+[![Npm package total downloads](https://badgen.net/npm/dt/pepr)](https://npmjs.com/package/pepr)
+
+#### **_Type safe Kubernetes middleware for humans_**
+
+<img align="right" width="40%" src="_images/pepr.png" />
+
+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.
+
+#### _Note: Pepr is still in active development so breaking changes may occur, but will be documented in release notes._
+
+## Features
+
+- Zero-config K8s webhook mutations and validations
+- Automatic leader-elected K8s resource watching
+- Lightweight async key-value store backed by K8s for stateful operations with the [Pepr Store](./store/)
+- Human-readable fluent API for generating [Pepr Capabilities](#capability)
+- A fluent API for creating/modifying/watching and server-side applying K8s resources via [Kubernetes Fluent Client](https://github.com/defenseunicorns/kubernetes-fluent-client)
+- Generate new K8s resources based off of cluster resource changes
+- Perform other exec/API calls based off of cluster resources changes or any other arbitrary schedule
+- Out of the box airgap support with [Zarf](https://zarf.dev)
+- 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
+- Least-privilege [RBAC](https://github.com/defenseunicorns/pepr/blob/main/docs/rbac/) generation
+- AMD64 and ARM64 support
+
+## Example Pepr Action
+
+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. It also creates a Validating Webhook to make sure the "pepr" label still exists. Finally, 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. For more details see [actions](./actions/) section.
+
+```ts
+When(a.ConfigMap)
+  .IsCreatedOrUpdated()
+  .InNamespace("pepr-demo")
+  .WithLabel("unicorn", "rainbow")
+  // Create a Mutate Action for the ConfigMap
+  .Mutate(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:");
+  })
+  // Create a Validate Action for the ConfigMap
+  .Validate(request => {
+    // Validate the ConfigMap has a specific label
+    if (request.HasLabel("pepr")) {
+      return request.Approve();
+    }
+
+    // Reject the ConfigMap if it doesn't have the label
+    return request.Deny("ConfigMap must have a unicorn label");
+  })
+  // Watch behaves like controller-runtime's Manager.Watch()
+  .Watch(async (cm, phase) => {
+    Log.info(cm, `ConfigMap was ${phase}.`);
+
+    // Apply a ConfigMap using K8s server-side apply (will create or update)
+    await K8s(kind.ConfigMap).Apply({
+      metadata: {
+        name: "pepr-ssa-demo",
+        namespace: "pepr-demo-2",
+      },
+      data: {
+        uid: cm.metadata.uid,
+      },
+    });
+  });
+```
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en/) v18.0.0+ (even-numbered releases only)
+  - To ensure compatability 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. Odd-numbered releases are experimental and may not be supported by certain libraries utilized in Pepr.  
+
+- [npm](https://www.npmjs.com/) v10.1.0+  
+
+- Recommended (optional) tools:
+  - [Visual Studio Code](https://code.visualstudio.com/) for inline debugging and [Pepr Capabilities](#capability) creation.
+  - 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/).
+
+## Wow too many words! tl;dr;
+
+```bash
+# Create a new Pepr Module
+npx pepr init
+
+# 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 `npx pepr dev --host host.docker.internal`
+npx pepr dev
+kubectl apply -f capabilities/hello-pepr.samples.yaml
+
+# Be amazed and ⭐️ this repo
+```
+
+<video class="td-content" controls src="https://user-images.githubusercontent.com/882485/230895880-c5623077-f811-4870-bb9f-9bb8e5edc118.mp4"></video>
+
+## Concepts
+
+### Module
+
+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 actions. 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 with their own isolated controller.
+
+See [Module](./module/) for more details.
+
+### Capability
+
+A capability is set of related actions that work together to achieve a specific transformation or operation on Kubernetes resources. Capabilities are user-defined and can include one or more actions. 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](./capabilities/) for more details.
+
+### Action
+
+Action is a discrete set of behaviors defined in a single function that acts on a given Kubernetes GroupVersionKind (GVK) passed in from Kubernetes. Actions are the atomic operations that are performed on Kubernetes resources by Pepr.
+
+For 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. Actions can be grouped together within a Capability to provide a more comprehensive set of operations that can be performed on Kubernetes resources.
+
+There are both `Mutate()` and `Validate()` Actions that can be used to modify or validate Kubernetes resources within the admission controller lifecycle. There is also a `Watch()` Action that can be used to watch for changes to Kubernetes resources that already exist.
+
+See [actions](./actions/) for more details.
+
+## Logical Pepr Flow
+
+![Arch Diagram](./_images/pepr-arch.svg)
+[Source Diagram](_images/pepr-arch.svg)
+
+## TypeScript
+
+[TypeScript](https://www.typescriptlang.org/) 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](https://www.typescriptlang.org/docs/handbook/typescript-from-scratch.html).
+
+## Community
+
+To join our channel go to [Kubernetes Slack](https://communityinviter.com/apps/kubernetes/community) and join the `#pepr` channel.
+
+<a href="https://github.com/defenseunicorns/pepr/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=defenseunicorns/pepr" />
+</a>
+
+Made with [contrib.rocks](https://contrib.rocks).

site/content/en/v0.22.1/actions.md

@@ -0,0 +1,73 @@
+---
+title: Actions
+---
+
+
+An action is a discrete set of behaviors defined in a single function that acts on a given Kubernetes GroupVersionKind (GVK) passed in during the admission controller lifecycle. Actions are the atomic operations that are performed on Kubernetes resources by Pepr.
+
+For 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. Actions can be grouped together within a Capability to provide a more comprehensive set of operations that can be performed on Kubernetes resources.
+
+Actions are `Mutate()`, `Validate()`, or `Watch()`. Both Mutate and Validate actions run during the admission controller lifecycle, while Watch actions run in a separate controller that tracks changes to resources, including existing resources.
+
+Let's look at some example actions that are included in the `HelloPepr` capability that is created for you when you [`pepr init`](../cli#pepr-init):
+
+---
+
+In this first example, Pepr is adding a label and annotation to a ConfigMap with tne name `example-1` when it is created. Comments are added to each line to explain in more detail what is happening.
+
+```ts
+// When(a.<Kind>) filters which GroupVersionKind (GVK) this action should act on.
+When(a.ConfigMap)
+  // This limits the action to only act on new resources.
+  .IsCreated()
+  // This limits the action to only act on resources with the name "example-1".
+  .WithName("example-1")
+  // Mutate() is where we define the actual behavior of this action.
+  .Mutate(request => {
+    // The request object is a wrapper around the K8s resource that Pepr is acting on.
+    request
+      // Here we are adding a label to the ConfigMap.
+      .SetLabel("pepr", "was-here")
+      // And here we are adding an annotation.
+      .SetAnnotation("pepr.dev", "annotations-work-too");
+
+    // Note that we are not returning anything here. This is because Pepr is tracking the changes in each action automatically.
+  });
+```
+
+---
+
+In this example, a Validate action rejects any ConfigMap in the `pepr-demo` namespace that has no data.
+
+```ts
+When(a.ConfigMap)
+  .IsCreated()
+  .InNamespace("pepr-demo")
+  // Validate() is where we define the actual behavior of this action.
+  .Validate(request => {
+    // If data exists, approve the request.
+    if (request.Raw.data) {
+      return request.Approve();
+    }
+
+    // Otherwise, reject the request with a message and optional code.
+    return request.Deny("ConfigMap must have data");
+  });
+```
+
+---
+
+In this example, a Watch action on the name and phase of any ConfigMap.Watch actions run in a separate controller that tracks changes to resources, including existing resources so that you can react to changes in real-time. It is important to note that Watch actions are not run during the admission controller lifecycle, so they cannot be used to modify or validate resources. They also may run multiple times for the same resource, so it is important to make sure that your Watch actions are idempotent. In a future release, Pepr will provide a better way to control when a Watch action is run to avoid this issue.
+
+```ts
+When(a.ConfigMap)
+  // Watch() is where we define the actual behavior of this action.
+  .Watch((cm, phase) => {
+    Log.info(cm, `ConfigMap ${cm.metadata.name} was ${phase}`);
+  });
+```
+
+```
+There are many more examples in the `HelloPepr` capability that you can use as a reference when creating your own actions. Note that each time you run [`pepr update`](../cli#pepr-update), Pepr will automatically update the `HelloPepr` capability with the latest examples and best practices for you to reference and test directly in your Pepr Module.
+```
+

site/content/en/v0.22.1/capabilities.md

@@ -0,0 +1,33 @@
+---
+title: Capabilities
+---
+
+
+A capability is set of related [actions](../actions/) that work together to achieve a specific transformation or operation on Kubernetes resources. Capabilities are user-defined and can include one or more actions. 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.
+
+When you [`pepr init`](../cli#pepr-init), a `capabilities` directory is created for you. This directory is where you will define your capabilities. You can create as many capabilities as you need, and each capability can contain one or more actions. Pepr also automatically creates a `HelloPepr` capability with a number of example actions to help you get started.
+
+## Creating a Capability
+
+Defining a new capability can be done via a [VSCode Snippet](https://code.visualstudio.com/docs/editor/userdefinedsnippets) generated during [`pepr init`](../cli#pepr-init).
+
+1. Create a new file in the `capabilities` directory with the name of your capability. For example, `capabilities/my-capability.ts`.
+
+1. Open the new file in VSCode and type `create` in the file. A suggestion should prompt you to generate the content from there.
+
+<video class="td-content" controls src="https://user-images.githubusercontent.com/882485/230897379-0bb57dff-9832-479f-8733-79e103703135.mp4"></video>
+
+_If you prefer not to use VSCode, you can also modify or copy the `HelloPepr` capability to meet your needs instead._
+
+
+## Reusable Capabilities
+
+Pepr has an NPM org managed by Defense Unicorns, `@pepr`, where capabilities are published for reuse in other Pepr Modules. You can find a list of published capabilities [here](https://www.npmjs.com/search?q=@pepr).
+
+You also can publish your own Pepr capabilities to NPM and import them.  A couple of things you'll want to be aware of when publishing your own capabilities:
+
+- Reuseable capability versions should use the format `0.x.x` or `0.12.x` as examples to determine compatibility with other reusable capabilities. Before `1.x.x`, we recommend binding to `0.x.x` if you can for maximum compatibility.
+
+- `pepr.ts` will still be used for local development, but you'll also need to publish an `index.ts` that exports your capabilities. When you build & publish the capability to NPM, you can use `npx pepr build -e index.ts` to generate the code needed for reuse by other Pepr modules.
+
+- See [Pepr Istio](https://github.com/defenseunicorns/pepr-istio) for an example of a reusable capability.