Merge branch 'main' into hotfix-return-types-in-funcs

.github/workflows/codeql.yml

@@ -44,17 +44,17 @@ jobs:
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@f09c1c0a94de965c15400f5634aa42fac8fb8f88 # v3.27.5
+        uses: github/codeql-action/init@aa578102511db1f4524ed59b8cc2bae4f6e88195 # v3.27.6
         with:
           languages: ${{ matrix.language }}
 
       # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@f09c1c0a94de965c15400f5634aa42fac8fb8f88 # v3.27.5
+        uses: github/codeql-action/autobuild@aa578102511db1f4524ed59b8cc2bae4f6e88195 # v3.27.6
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@f09c1c0a94de965c15400f5634aa42fac8fb8f88 # v3.27.5
+        uses: github/codeql-action/analyze@aa578102511db1f4524ed59b8cc2bae4f6e88195 # v3.27.6
         with:
           category: "/language:${{matrix.language}}"
 

.github/workflows/scorecard.yml

@@ -60,6 +60,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@f09c1c0a94de965c15400f5634aa42fac8fb8f88 # v2.2.4
+        uses: github/codeql-action/upload-sarif@aa578102511db1f4524ed59b8cc2bae4f6e88195 # v2.2.4
         with:
           sarif_file: results.sarif

.github/workflows/secret-scan.yml

@@ -23,6 +23,6 @@ jobs:
       with:
         fetch-depth: 0
     - name: Default Secret Scanning
-      uses: trufflesecurity/trufflehog@735bac03911974e37641f570a5582a9b72f49a44 # main
+      uses: trufflesecurity/trufflehog@35943b41905eb1195f021955da17c233ed555e24 # main
       with:
         extra_args: --debug --no-verification # Warn on potential violations

README.md

@@ -33,7 +33,7 @@ Pepr is on a mission to save Kubernetes from the tyranny of YAML, intimidating g
 
 ## 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](./docs/030_user-guide/030_actions.md) section.
+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](./docs/030_user-guide/030_actions/) section.
 
 ```ts
 When(a.ConfigMap)
@@ -95,17 +95,23 @@ When(a.ConfigMap)
 # Create a new Pepr Module
 npx pepr init
 
-# If you already have a Kind or K3d cluster you want to use, skip this step
+# If you already have a 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`
+# Start playing with Pepr now!
+# If using Kind, or another local k8s distro instead,
+# run `npx pepr dev --host <your_hostname>`
 npx pepr dev
 kubectl apply -f capabilities/hello-pepr.samples.yaml
 
-# Be amazed and ⭐️ this repo
+# Be amazed and ⭐️ this repo!
 ```
 
+> [!TIP]
+> Don't use IP as your `--host`, it's not supported. Make sure to check your
+> local k8s distro documentation how to reach your localhost, which is where
+> `pepr dev` is serving the code from.
+
 https://user-images.githubusercontent.com/882485/230895880-c5623077-f811-4870-bb9f-9bb8e5edc118.mp4
 
 ## Concepts

docs/030_user-guide/040_capabilities.md

@@ -1,6 +1,6 @@
 # Pepr Capabilities
 
-A capability is set of related [actions](./030_actions.md) 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.
+A capability is set of related [actions](./030_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 [`npx pepr init`](./010_pepr-cli.md#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.
 

docs/030_user-guide/README.md

@@ -10,7 +10,7 @@ You can find the following information in this section:
 
 ### [Pepr Modules](020_pepr-modules.md)
 
-### [Pepr Actions](030_actions.md)
+### [Pepr Actions](030_actions/)
 
 ### [Pepr Capabilities](040_capabilities.md)
 

docs/090_roadmap/README.md

@@ -1,57 +1,68 @@
 # Roadmap for Pepr 
-
 _2024 Roadmap_  
 ## Phase 1: Preparation - Testing and Docs
 
 - **Q1**:
   - **Establish Medium for Communication with Community**:
-    Establish communication channel for community members and contributors. Easy/discoverable "how to contribute" guide.
+    - Establish communication channel for community members and contributors. Easy/discoverable "how to contribute" guide.
   - **Site/Documentation**:
-    Improve information architecture, nail killer use-cases, and make it obvious how to get started and find your way around.
+    - Improve information architecture, nail killer use-cases, and make it obvious how to get started and find your way around.
   - **Automated Testing**:
-    Focus on stories that increase confidence in protection of features and functionality. Simplify hello-pepr and bring e2e test against external repo with examples. Make sure that contributions are well-tested.
+    - Focus on stories that increase confidence in protection of features and functionality. Simplify hello-pepr and bring e2e test against external repo with examples. Make sure that contributions are well-tested.
 
-## Phase 2: Community Building, Competitive Analysis, and Feature Development
+## Phase 2: Community Building, Competitive Analysis, Instrumentation and Feature Development
 
 - **Q2**:
   - **Community Engagement**:
-    Begin engaging with potential contributors and users through social media, Kubernetes/Cloud Native Computing Foundation (CNCF) meetups, and other channels. Monitor and participate in our Slack channel.
+    - Begin engaging with potential contributors and users through social media, Kubernetes/Cloud Native Computing Foundation (CNCF) meetups, and other channels. Monitor and participate in our Slack channel.
   - **Feature Development**:
-    Based on company feedback, continuously improve and add features. Add feature parity with other tools in the Kubernetes ecosystem where it makes sense. Chip away at the backlog.
+    - Based on company feedback, continuously improve and add features. Add feature parity with other tools in the Kubernetes ecosystem where it makes sense. Chip away at the backlog.
   - **Documentation Improvements**:
-    Continue to improve documentation and add more examples like Doom, find scaling limitations
+    - Continue to improve documentation and add more examples like Doom, find scaling limitations
   - **Competitive Analysis**:
-    Understand the competitive landscape and how/where Pepr can/does differentiate itself. Have it in the docs.
+    - Understand the competitive landscape and how/where Pepr can/does differentiate itself. Have it in the docs.
+  - **Instrumentation**:
+    - Outfit Pepr with the necessary instrumentation to collect metrics and logs. Use this data to make informed about the watch direction.
 
-## Phase 3: Donation, Transition, Move Project, and Stabilization/Improvement of New Features
+## Phase 3: Informer Iterations, Watch Analysis, Metric Collection, Development/Stabilization/Improvement of New Features
 
 - **Q3**:
-  - **Donation**:
-    - Donate the project to the CNCF.
-    - CNCF Code of conduct
-    - CNCF IP policy
-    - CNCF CLA
-    - Discoverable and simple governance model
-    - move project to its own organization
-    - ensure license in Apache 2.0
-    - Transfer trademark, logo, domain name, and other assets to CNCF.
-  - **Community Building**:
-    Grow the contributor base, establish a governance model, and encourage community-led initiatives. Interact with people in our Slack channel.
+  - **Informer Iterations**:
+    - Tune informer based on feedback from UDS Core and delivery so events will be reconciled through eventual consistency.
+    - [Evaluate](https://github.com/defenseunicorns/pepr/blob/main/adr/0015-kfc-watch-undici.md) other underlying technologies for informer.
   - **Feature Development**:
-    Based on community feedback, continuously improve and add features. Rigoursly test and document and review code.
+    - `.WithNameRegex()/.InNamespaceRegex()` for Kubernetes Controller development against resources that could match a variety of names or namespaces.
+    - `.WithDeletionTimestamp()` for Kubernetes Controller Development against resources that are pending deletion
+    - Create a sharded queue that enables the Module Author to define queueing strategies based on `kind`, `kind/namespace`, `kind/namespace/name`, `global`.
+  - **Community Building**:
+    - Grow the contributor base, establish a governance model, and encourage community-led initiatives. Look to drive conversation in our Slack Channel.
+    - Based on community feedback, continuously improve and add features. Rigoursly test and document and review code.
   - **Project Advocation**:
-    Publicly advocate for the project and encourage adoption.
-  - **Submit PR for Sandbox**
-    - Submit sandbox PR when ready
+    - Publicly advocate for the project and encourage adoption.
+  - **Stability**:
+    - Ensure that the project is stable and reliable. Make sure that the project is well-tested and documented.
+    - Identify new areas of project improvement and work on them.
 
-## Phase 4: Post Donation
+## Phase 4: Feature Development, Stablization, Code and Testing Quality Improvements
 
 - **Q4**:
-  - **Road to GA**:
-    Right now, Pepr itself is still in its 'development' phase. We are working on some final things before we release the official 1.0 General Availability (GA) release
-  - **Community Meetings**:
-    - Monthly community meetings/steering committee meetings/contributor meetings
-  - **Review Sandbox PR**
-    - Review PR for sandbox
-  - **Road to Incubation**:
-    - to come
+  - **Features**:
+    - Improve DevEx overrides in Pepr section of package.json for customized builds of Modules
+    - `.Finalize()` for Kubernetes Controller Development to controlling downstream resources through finalizers
+    - Scaffolding to validate images from a registry through cosign/sigstore
+    - Replace node-fetch with Undici in the KFC project for performance improvements
+  - **Removal of Circular Dependencies**:
+    Identify and remove circular dependencies in the codebase.
+  - **Strong Typings**:
+    - Identify where we can make Pepr/KFC stronger by adding typings.
+  - **Work to reduce code complexity**
+    - Monitor code complexity through eslint, work to drive down complexity
+  - **Robust E2E Tests in KFC**:
+    - Create a strong e2e suite in KFC, ensure tests are robust and cover all the features of KFC.
+  - **Documentation**:
+    - Ensure that the documentation is up-to-date and accurate. Add more examples and use-cases.
+    - Onboarding and contribution guides should be clear and easy to follow.
+  - **Load/Stress Testing**:
+    - Load test Pepr/KFC to identify bottlenecks and areas of improvement.
+    - Ensure that Pepr/KFC can handle a large number of resources and events over a sustained period of time (nightly).
+

docs/120_contribute/README.md

@@ -60,7 +60,8 @@ 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/`!**
+> [!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.
@@ -73,6 +74,20 @@ Please follow the coding conventions and style used in the project. Use ESLint a
 2. Change to the test module directory: `cd pepr-test-module`.
 3. You can now run any of the `npx pepr` commands.
 
+### Running Development Version Locally
+
+1. Run `npm run build` to build the package.
+2. For running modified pepr, you have two options:
+  - Using `npx ts-node ./src/cli.ts init` to run the modified code directly, without installing it locally.
+    You'll need to also run `npx link <your_dev_pepr_location>` inside your pepr module, to link to the
+    development version of pepr.
+  - Install the pre-build package with `npm install pepr-0.0.0-development.tgz`.
+    You'll need to re-run the installation after every build, though.
+3. Run `npx pepr dev` inside your module's directory to run the modified version of pepr.
+
+> [!TIP]
+> Make sure to re-run `npm run build` after you modify any of the pepr source files.
+
 ## Contact
 
 For any questions or concerns, please open an issue on GitHub or contact the maintainers.

journey/pepr-deploy.ts

@@ -302,7 +302,7 @@ function testStore() {
     // Should have a key from the joke url and getItem should have worked
     const key3 = await waitForPeprStoreKey(
       "pepr-static-test-store",
-      `hello-pepr-v2-https://icanhazdadjoke.com/`,
+      `hello-pepr-v2-https://icanhazdadjoke.com`,
     );
     expect(key3).toBeTruthy();
 

journey/pepr-dev.ts

@@ -3,17 +3,23 @@
 
 import { afterAll, expect, it } from "@jest/globals";
 import { ChildProcessWithoutNullStreams, spawn } from "child_process";
-import { Agent } from "https";
 import { fetch } from "kubernetes-fluent-client";
-import { RequestInit } from "node-fetch";
+import { RequestInit, Agent } from "undici";
 import { cwd } from "./entrypoint.test";
 import { sleep } from "./k8s";
 
 const fetchBaseUrl = "https://localhost:3000";
 const fetchOpts: RequestInit = {
-  agent: new Agent({
-    // Avoid tls issues for self-signed certs
-    rejectUnauthorized: false,
+  method: "GET",
+  headers: {
+    "Content-Type": "application/json; charset=UTF-8",
+  },
+  dispatcher: new Agent({
+    // disable keep-alive https://github.com/nodejs/undici/issues/2522#issuecomment-1859213319
+    pipelining: 0,
+    connect: {
+      rejectUnauthorized: false,
+    },
   }),
 };
 
@@ -78,7 +84,6 @@ export function peprDev() {
       } else {
         // Abort all further processing
         success = true;
-
         // Finish the test
         done();
       }