docs.yml

site/content/en/v0.35.0/_index.md → site/content/en/v0.38.0-rc/_index.md

@@ -1,6 +1,6 @@
 ---
 title: Pepr
-linkTitle: v0.35.0
+linkTitle: v0.38.0-rc
 cascade:
   type: docs
 aliases: []

site/content/en/v0.35.0/contribute/_index.md → site/content/en/v0.38.0-rc/contribute/_index.md

@@ -64,6 +64,11 @@ Please follow the coding conventions and style used in the project. Use ESLint a
 
 ### Run Tests Locally
 
+> ⚠️ **Warning: Be cautious when creating test cases in `journey/`!**
+>
+> - Test cases that capture end-to-end/journey behavior are usually stored in [pepr-excellent-examples](https://github.com/defenseunicorns/pepr-excellent-examples) or run as a Github workflow (`.github/workflows`).
+> - Journey tests established in `journey/` are from an earlier time in project history.
+
 - Run all tests: `npm test`
 
 ### Test a Local Development Version

site/content/en/v0.35.0/faq/_index.md → site/content/en/v0.38.0-rc/faq/_index.md

@@ -7,6 +7,14 @@ weight: 80
 
 ## How do I remove the punycode warning?
 
+By default, warnings are removed. You can allow warnings by setting the `PEPR_NODE_WARNINGS` environment variable.
+
+```bash
+PEPR_NODE_WARNINGS="true"
+```
+
+If you allow warnings, you can disable the specific punycode warning by:
+
 ```bash
 export NODE_OPTIONS="--disable-warning=DEP0040"
 ```
@@ -17,6 +25,7 @@ or
 npx --node-options="--disable-warning=DEP0040" pepr [command]
 ```
 
+
 ## How does Pepr compare to Operator SDK?
 
 Pepr and Operator SDK are both frameworks used for building Kubernetes operators and admission controllers. While they share a common goal of simplifying the creation of Kubernetes operators and enhancing Kubernetes functionality, they have different approaches and features.

site/content/en/v0.35.0/user-guide/actions/_index.md → site/content/en/v0.38.0-rc/user-guide/actions/_index.md

@@ -10,7 +10,7 @@ An action is a discrete set of behaviors defined in a single function that acts
 
 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()`, `Watch()`, or `Reconcile()`. Both Mutate and Validate actions run during the admission controller lifecycle, while Watch and Reconcile actions run in a separate controller that tracks changes to resources, including existing resources.
+Actions are `Mutate()`, `Validate()`, `Watch()`, `Reconcile()`, and `Finalize()`. Both Mutate and Validate actions run during the admission controller lifecycle, while Watch and Reconcile actions run in a separate controller that tracks changes to resources, including existing resource; the Finalize action spans both the admission & afterward.
 
 Let's look at some example actions that are included in the `HelloPepr` capability that is created for you when you [`npx pepr init`](./pepr-cli#pepr-init):
 

site/content/en/v0.38.0-rc/user-guide/actions/finalize.md

@@ -0,0 +1,15 @@
+---
+title: Finalize
+weight: 50
+---
+
+
+A specialized combination of Pepr's [Mutate](../mutate/) & [Watch](../watch/) functionalities that allow a module author to run logic while Kubernetes is [Finalizing](https://kubernetes.io/docs/concepts/overview/working-with-objects/finalizers/) a resource (i.e. cleaning up related resources _after_ a deleteion request has been accepted).
+
+This method will:
+
+1. Inject a finalizer into the `metadata.finalizers` field of the requested resource during the mutation phase of the admission.
+
+1. Watch appropriate resource lifecycle events & invoke the given callback.
+
+1. Remove the injected finalizer from the `metadata.finalizers` field of the requested resource.

site/content/en/v0.38.0-rc/user-guide/actions/using-alias-child-logger.md

@@ -0,0 +1,91 @@
+---
+title: Using Alias Child Logger in Actions
+weight: 50
+---
+
+
+You can use the Alias function to include a user-defined alias in the logs for Mutate, Validate, and Watch actions. This can make for easier debugging since your user-defined alias will be included in the action's logs. This is especially useful when you have multiple actions of the same type in a single module.
+
+The below example uses Mutate, Validate, and Watch actions with the Alias function:
+
+```ts
+When(a.Pod)
+  .IsCreatedOrUpdated()
+  .Alias("mutate")
+  .Mutate((po, logger) => {
+    logger.info(`alias: mutate ${po.Raw.metadata.name}`);
+  });
+When(a.Pod)
+  .IsCreatedOrUpdated()
+  .Alias("validate")
+  .Validate((po, logger) => {
+    logger.info(`alias: validate ${po.Raw.metadata.name}`);
+    return po.Approve();
+  });
+When(a.Pod)
+  .IsCreatedOrUpdated()
+  .Alias("watch")
+  .Watch((po, _, logger) => {
+    logger.info(`alias: watch ${po.metadata.name}`);
+  });
+When(a.Pod)
+  .IsCreatedOrUpdated()
+  .Alias("reconcile")
+  .Reconcile((po, _, logger) => {
+    logger.info(`alias: reconcile ${po.metadata.name}`);
+  });
+```
+
+This will result in log entries when creating a Pod with the that include the alias:
+
+**Logs for Mutate When Pod `red` is Created:**
+
+```bash
+{"level":30,"time":1726632368808,"pid":16,"hostname":"pepr-static-test-6786948977-6hbnt","uid":"b2221631-e87c-41a2-94c8-cdaef15e7b5f","namespace":"pepr-demo","name":"/red","gvk":{"group":"","version":"v1","kind":"Pod"},"operation":"CREATE","admissionKind":"Mutate","msg":"Incoming request"}
+{"level":30,"time":1726632368808,"pid":16,"hostname":"pepr-static-test-6786948977-6hbnt","uid":"b2221631-e87c-41a2-94c8-cdaef15e7b5f","namespace":"pepr-demo","name":"/red","msg":"Processing request"}
+{"level":30,"time":1726632368808,"pid":16,"hostname":"pepr-static-test-6786948977-6hbnt","msg":"Executing mutation action with alias: mutate"}
+{"level":30,"time":1726632368808,"pid":16,"hostname":"pepr-static-test-6786948977-6hbnt","alias":"mutate","msg":"alias: mutate red"}
+{"level":30,"time":1726632368808,"pid":16,"hostname":"pepr-static-test-6786948977-6hbnt","uid":"b2221631-e87c-41a2-94c8-cdaef15e7b5f","namespace":"pepr-demo","name":"hello-pepr","msg":"Mutation action succeeded (mutateCallback)"}
+{"level":30,"time":1726632368808,"pid":16,"hostname":"pepr-static-test-6786948977-6hbnt","uid":"b2221631-e87c-41a2-94c8-cdaef15e7b5f","namespace":"pepr-demo","name":"/red","res":{"uid":"b2221631-e87c-41a2-94c8-cdaef15e7b5f","allowed":true,"patchType":"JSONPatch","patch":"W3sib3AiOiJhZGQiLCJwYXRoIjoiL21ldGFkYXRhL2Fubm90YXRpb25zL3N0YXRpYy10ZXN0LnBlcHIuZGV2fjFoZWxsby1wZXByIiwidmFsdWUiOiJzdWNjZWVkZWQifV0="},"msg":"Check response"}
+{"level":30,"time":1726632368809,"pid":16,"hostname":"pepr-static-test-6786948977-6hbnt","uid":"b2221631-e87c-41a2-94c8-cdaef15e7b5f","method":"POST","url":"/mutate/c1a7fb6e3f2ab9dc08909d2de4166987520f317d53b759ab882dfd0b1c198479?timeout=10s","status":200,"duration":"1 ms"}
+```
+
+**Logs for Validate When Pod `red` is Created:**
+
+```bash
+{"level":30,"time":1726631437605,"pid":16,"hostname":"pepr-static-test-6786948977-j7f9h","uid":"731eff93-d457-4ffc-a98c-0bcbe4c1727a","namespace":"pepr-demo","name":"/red","gvk":{"group":"","version":"v1","kind":"Pod"},"operation":"CREATE","admissionKind":"Validate","msg":"Incoming request"}
+{"level":30,"time":1726631437606,"pid":16,"hostname":"pepr-static-test-6786948977-j7f9h","uid":"731eff93-d457-4ffc-a98c-0bcbe4c1727a","namespace":"pepr-demo","name":"/red","msg":"Processing validation request"}
+{"level":30,"time":1726631437606,"pid":16,"hostname":"pepr-static-test-6786948977-j7f9h","uid":"731eff93-d457-4ffc-a98c-0bcbe4c1727a","namespace":"pepr-demo","name":"hello-pepr","msg":"Processing validation action (validateCallback)"}
+{"level":30,"time":1726631437606,"pid":16,"hostname":"pepr-static-test-6786948977-j7f9h","msg":"Executing validate action with alias: validate"}
+{"level":30,"time":1726631437606,"pid":16,"hostname":"pepr-static-test-6786948977-j7f9h","alias":"validate","msg":"alias: validate red"}
+{"level":30,"time":1726631437606,"pid":16,"hostname":"pepr-static-test-6786948977-j7f9h","uid":"731eff93-d457-4ffc-a98c-0bcbe4c1727a","namespace":"pepr-demo","name":"hello-pepr","msg":"Validation action complete (validateCallback): allowed"}
+{"level":30,"time":1726631437606,"pid":16,"hostname":"pepr-static-test-6786948977-j7f9h","uid":"731eff93-d457-4ffc-a98c-0bcbe4c1727a","namespace":"pepr-demo","name":"/red","res":{"uid":"731eff93-d457-4ffc-a98c-0bcbe4c1727a","allowed":true},"msg":"Check response"}
+{"level":30,"time":1726631437606,"pid":16,"hostname":"pepr-static-test-6786948977-j7f9h","uid":"731eff93-d457-4ffc-a98c-0bcbe4c1727a","method":"POST","url":"/validate/c1a7fb6e3f2ab9dc08909d2de4166987520f317d53b759ab882dfd0b1c198479?timeout=10s","status":200,"duration":"5 ms"}
+```
+
+**Logs for Watch and Reconcile When Pod `red` is Created:**
+
+```bash
+{"level":30,"time":1726798504518,"pid":16,"hostname":"pepr-static-test-watcher-6dc69654c9-5ql6b","msg":"Executing reconcile action with alias: reconcile"}
+{"level":30,"time":1726798504518,"pid":16,"hostname":"pepr-static-test-watcher-6dc69654c9-5ql6b","alias":"reconcile","msg":"alias: reconcile red"}
+{"level":30,"time":1726798504518,"pid":16,"hostname":"pepr-static-test-watcher-6dc69654c9-5ql6b","msg":"Executing watch action with alias: watch"}
+{"level":30,"time":1726798504518,"pid":16,"hostname":"pepr-static-test-watcher-6dc69654c9-5ql6b","alias":"watch","msg":"alias: watch red"}
+{"level":30,"time":1726798504521,"pid":16,"hostname":"pepr-static-test-watcher-6dc69654c9-5ql6b","msg":"Executing reconcile action with alias: reconcile"}
+{"level":30,"time":1726798504521,"pid":16,"hostname":"pepr-static-test-watcher-6dc69654c9-5ql6b","alias":"reconcile","msg":"alias: reconcile red"}
+{"level":30,"time":1726798504521,"pid":16,"hostname":"pepr-static-test-watcher-6dc69654c9-5ql6b","msg":"Executing watch action with alias: watch"}
+{"level":30,"time":1726798504521,"pid":16,"hostname":"pepr-static-test-watcher-6dc69654c9-5ql6b","alias":"watch","msg":"alias: watch red"}
+{"level":30,"time":1726798504528,"pid":16,"hostname":"pepr-static-test-watcher-6dc69654c9-5ql6b","msg":"Executing reconcile action with alias: reconcile"}
+{"level":30,"time":1726798504528,"pid":16,"hostname":"pepr-static-test-watcher-6dc69654c9-5ql6b","alias":"reconcile","msg":"alias: reconcile red"}
+{"level":30,"time":1726798504528,"pid":16,"hostname":"pepr-static-test-watcher-6dc69654c9-5ql6b","msg":"Executing watch action with alias: watch"}
+{"level":30,"time":1726798504528,"pid":16,"hostname":"pepr-static-test-watcher-6dc69654c9-5ql6b","alias":"watch","msg":"alias: watch red"}
+{"level":30,"time":1726798510464,"pid":16,"hostname":"pepr-static-test-watcher-6dc69654c9-5ql6b","msg":"Executing watch action with alias: watch"}
+{"level":30,"time":1726798510464,"pid":16,"hostname":"pepr-static-test-watcher-6dc69654c9-5ql6b","alias":"watch","msg":"alias: watch red"}
+{"level":30,"time":1726798510466,"pid":16,"hostname":"pepr-static-test-watcher-6dc69654c9-5ql6b","msg":"Executing reconcile action with alias: reconcile"}
+{"level":30,"time":1726798510466,"pid":16,"hostname":"pepr-static-test-watcher-6dc69654c9-5ql6b","alias":"reconcile","msg":"alias: reconcile red"}
+```
+
+**Note:** The Alias function is optional and can be used to provide additional context in the logs. You must pass the logger object as shown above to the action to use the Alias function.
+
+## See Also
+
+Looking for some more generic helpers? Check out the [Module Author SDK](../../sdk/) for information on other things that Pepr can help with.

site/content/en/v0.35.0/user-guide/customization.md → site/content/en/v0.38.0-rc/user-guide/customization.md

@@ -6,6 +6,30 @@ weight: 120
 
 This document outlines how to customize the build output through Helm overrides and `package.json` configurations.
 
+## Redact Store Values from Logs
+
+By default, the store values are displayed in logs, to redact them you can set the `PEPR_STORE_REDACT_VALUES` environment variable to `true` in the `package.json` file or directly on the Watcher or Admission `Deployment`. The default value is `undefined`.
+
+```json
+{
+  "env": {
+    "PEPR_STORE_REDACT_VALUES": "true"
+  }
+}
+```
+
+## Display Node Warnings
+
+You can display warnings in the logs by setting the `PEPR_NODE_WARNINGS` environment variable to `true` in the `package.json` file or directly on the Watcher or Admission `Deployment`. The default value is `undefined`.
+
+```json
+{
+  "env": {
+    "PEPR_NODE_WARNINGS": "true"
+  }
+}
+```
+
 ## Customizing Log Format
 
 The log format can be customized by setting the `PINO_TIME_STAMP` environment variable in the `package.json` file or directly on the Watcher or Admission `Deployment`. The default value is a partial JSON timestamp string representation of the time. If set to `iso`, the timestamp is displayed in an ISO format. 
@@ -45,18 +69,18 @@ The Watch configuration is a part of the Pepr module that allows you to watch fo
 
 ## Configuring Reconcile
 
-The [Reconcile Action](../actions/reconcile/) allows you to maintain ordering of resource updates processed by a Pepr controller. The Reconcile configuration can be customized by specific enviroment variables of the Watcher Deployment and can be set in the `package.json` or in the helm `values.yaml` file.
+The [Reconcile Action](../actions/reconcile/) allows you to maintain ordering of resource updates processed by a Pepr controller. The Reconcile configuration can be customized via enviroment variable on the Watcher Deployment, which can be set in the `package.json` or in the helm `values.yaml` file.
 
 | Field | Description | Example Values |
 |-|-|-|
-| `PEPR_RECONCILE_STRATEGY` | How Pepr should order resource updates being Reconcile()'d. | default: `"singular"` |
+| `PEPR_RECONCILE_STRATEGY` | How Pepr should order resource updates being Reconcile()'d. | default: `"kind"` |
 
 | Available Options ||
 |-|-|
-| `singular`  | Pepr will keep a single queue of events across _all_ Reconcile()'d resources of a kind.
-| `sharded`   | Pepr will keep multiple queues of events, one for each resource _instance_ of a kind.
-
-
+| `kind`  | separate queues of events for Reconcile()'d resources of a kind |
+| `kindNs` | separate queues of events for Reconcile()'d resources of a kind, within a namespace |
+| `kindNsName` | separate queues of events for Reconcile()'d resources of a kind, within a namespace, per name |
+| `global` | a single queue of events for all Reconcile()'d resources |
 
 ## Customizing with Helm
 

site/content/en/v0.38.0-rc/user-guide/filters.md

@@ -0,0 +1,39 @@
+---
+title: Pepr Filters
+weight: 130
+---
+
+
+Filters are functions that take a `AdmissionReview` or Watch event and return a boolean. They are used to filter out resources that do not meet certain criteria. Filters are used in the package to filter out resources that are not relevant to the user-defined admission or watch process.
+
+```ts
+When(a.ConfigMap)
+  // This limits the action to only act on new resources.
+  .IsCreated()
+  // Namespace filter
+  .InNamespace("webapp")
+  // Name filter
+  .WithName("example-1")
+  // Label filter
+  .WithLabel("app", "webapp")
+  .WithLabel("env", "prod")
+  .Mutate(request => {
+    request
+      .SetLabel("pepr", "was-here")
+      .SetAnnotation("pepr.dev", "annotations-work-too");
+  });
+```
+
+
+## `Filters`
+
+- `.WithName("name")`: Filters resources by name.
+- `.WithNameRegex(/^pepr/)`: Filters resources by name using a regex.
+- `.InNamespace("namespace")`: Filters resources by namespace.
+- `.InNamespaceRegex(/(.*)-system/)`: Filters resources by namespace using a regex.
+- `.WithLabel("key", "value")`: Filters resources by label. (Can be multiple)
+- `.WithDeletionTimestamp()`: Filters resources that have a deletion timestamp. 
+
+Notes: 
+- `WithDeletionTimestamp()` is does not work on Delete through the `Mutate` or `Validate` methods because the Kubernetes Admission Process does not fire the DELETE event with a deletion timestamp on the resource. 
+- `WithDeletionTimestamp()` _will_ match on an Update event during Admission (`Mutate` or `Validate`) when pending-deletion permitted changes (like removing a finalizer) occur.

site/content/en/v0.35.0/user-guide/pepr-cli.md → site/content/en/v0.38.0-rc/user-guide/pepr-cli.md

@@ -10,7 +10,12 @@ Initialize a new Pepr Module.
 
 **Options:**
 
-- `--skip-post-init` - Skip npm install, git init and VSCode launch
+- `--skip-post-init` - Skip npm install, git init and VSCode launch.
+- `--confirm` - Skip verification prompt when creating a new module.
+- `--description <string>` - Explain the purpose of the new module.
+- `--name <string>` - Set the name of the new module.
+- `--skip-post-init` - Skip npm install, git init, and VSCode launch.
+- `--errorBehavior <audit|ignore|reject>` - Set an errorBehavior.
 
 ---
 

site/content/en/v0.35.0/user-guide/sdk.md → site/content/en/v0.38.0-rc/user-guide/sdk.md

@@ -51,9 +51,11 @@ let result = containers(peprValidationRequest, "ephemeralContainers")
 
 ## `getOwnerRefFrom`
 
-Returns the owner reference for a Kubernetes resource. Accepts the following parameters:
+Returns the owner reference for a Kubernetes resource as an array. Accepts the following parameters:
 
 - **@param kubernetesResource: GenericKind** The Kubernetes resource to get the owner reference for
+- **@param blockOwnerDeletion: boolean** If true, AND if the owner has the "foregroundDeletion" finalizer, then the owner cannot be deleted from the key-value store until this reference is removed. 
+- **@param controller: boolean** If true, this reference points to the managing controller.
 
 **Usage:**
 

site/hugo.yaml

@@ -38,8 +38,6 @@ params:
       url: /v0.37.2/
     - version: v0.36
       url: /v0.36.0/
-    - version: v0.35
-      url: /v0.35.0/
     - version: main
       url: /main/
 markup: