docs.yml

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

@@ -3,7 +3,7 @@ title: Pepr
 linkTitle: v0.38.3
 cascade:
   type: docs
-aliases: ["/current/"]
+aliases: []
 ---
 
 

site/content/en/v0.36.0/_index.md → site/content/en/v0.39.0/_index.md

@@ -1,9 +1,9 @@
 ---
 title: Pepr
-linkTitle: v0.36.0
+linkTitle: v0.39.0
 cascade:
   type: docs
-aliases: []
+aliases: ["/current/"]
 ---
 
 

site/content/en/v0.36.0/contribute/_index.md → site/content/en/v0.39.0/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.36.0/faq/_index.md → site/content/en/v0.39.0/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.36.0/user-guide/actions/_index.md → site/content/en/v0.39.0/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.39.0/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.39.0/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.36.0/user-guide/customization.md → site/content/en/v0.39.0/user-guide/customization.md

@@ -6,11 +6,35 @@ 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. 
+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.
 
-**Caution**: attempting to format time in-process will significantly impact logging performance.  
+**Caution**: attempting to format time in-process will significantly impact logging performance.
 
 ```json
 {
@@ -26,13 +50,13 @@ With ISO:
 {"level":30,"time":"2024-05-14T14:26:03.788Z","pid":16,"hostname":"pepr-static-test-7f4d54b6cc-9lxm6","method":"GET","url":"/healthz","status":200,"duration":"1 ms"}
 ```
 
-Default (without): 
+Default (without):
 
 ```json
 {"level":30,"time":"1715696764106","pid":16,"hostname":"pepr-static-test-watcher-559d94447f-xkq2h","method":"GET","url":"/healthz","status":200,"duration":"1 ms"}
 ```
 
-## Customizing Watch Configuration 
+## Customizing Watch Configuration
 
 The Watch configuration is a part of the Pepr module that allows you to watch for specific resources in the Kubernetes cluster. The Watch configuration can be customized by specific enviroment variables of the Watcher Deployment and can be set in the field in the `package.json` or in the helm `values.yaml` file.
 
@@ -42,6 +66,7 @@ The Watch configuration is a part of the Pepr module that allows you to watch fo
 | `PEPR_RETRY_DELAY_SECONDS`     | The delay between retries in seconds.                                                                            | default: `"10"`                 |
 | `PEPR_LAST_SEEN_LIMIT_SECONDS` | Max seconds to go without receiving a watch event before re-establishing the watch | default: `"300"` (5 mins)       |
 | `PEPR_RELIST_INTERVAL_SECONDS` | Amount of seconds to wait before a relist of the watched resources  | default: `"600"` (10 mins)       |
+| `PEPR_USE_LEGACY_WATCH` | Configure the Kubernetes Fluent Client to use legacy node-fetch watcher  | default: `"undefined"` |
 
 ## Configuring Reconcile
 
@@ -108,8 +133,33 @@ Below are the available configurations through `package.json`.
 | `onError`        | Behavior of the webhook failure policy | `reject`, `ignore`              |
 | `webhookTimeout` | Webhook timeout in seconds             | `1` - `30`                      |
 | `customLabels`   | Custom labels for namespaces           | `{namespace: {}}`               |
-| `alwaysIgnore`   | Conditions to always ignore            | `{namespaces: []}`  |
+| `alwaysIgnore`   | Conditions to always ignore            | `{namespaces: []}`              |
 | `includedFiles`  | For working with WebAssembly           | ["main.wasm", "wasm_exec.js"]   |
 | `env`            | Environment variables for the container| `{LOG_LEVEL: "warn"}`           |
+| `rbac`           | Custom RBAC rules (requires building with `rbacMode: scoped`)            | `{"rbac": [{"apiGroups": ["<apiGroups>"], "resources": ["<resources>"], "verbs": ["<verbs>"]}]}` |
+| `rbacMode`       | Configures module to build binding RBAC with principal of least privilege | `scoped`, `admin` |
 
 These tables provide a comprehensive overview of the fields available for customization within the Helm overrides and the `package.json` file. Modify these according to your deployment requirements.
+
+### Example Custom RBAC Rules
+
+The following example demonstrates how to add custom RBAC rules to the Pepr module.
+
+```json
+{
+  "pepr": {
+    "rbac": [
+      {
+        "apiGroups": ["pepr.dev"],
+        "resources": ["customresources"],
+        "verbs": ["get", "list"]
+      },
+      {
+        "apiGroups": ["apps"],
+        "resources": ["deployments"],
+        "verbs": ["create", "delete"]
+      }
+    ]
+  }
+}
+```

site/content/en/v0.36.0/user-guide/filters.md → site/content/en/v0.39.0/user-guide/filters.md

@@ -28,7 +28,9 @@ When(a.ConfigMap)
 ## `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. 
 

site/content/en/v0.36.0/user-guide/pepr-cli.md → site/content/en/v0.39.0/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/hugo.yaml

@@ -34,12 +34,12 @@ params:
       url: https://github.com/defenseunicorns/pepr-docs
   version_menu: Releases
   versions:
+    - version: v0.39
+      url: /v0.39.0/
     - version: v0.38
       url: /v0.38.3/
     - version: v0.37
       url: /0.37.3/
-    - version: v0.36
-      url: /v0.36.0/
     - version: main
       url: /main/
 markup: