pepr 0.14.2 → 0.15.0

package/website/content/en/docs/customresources.md

@@ -0,0 +1,167 @@
+---
+title: Custom Resources
+linkTitle: Custom Resources
+---
+
+
+# Importing Custom Resources
+
+
+The [Kubernetes Fluent Client](https://github.com/defenseunicorns/kubernetes-fluent-client) supports the creation of TypeScript typings directly from Kubernetes Custom Resource Definitions (CRDs).  The files it generates can be directly incorporated into Pepr capabilities and provide a way to work with strongly-typed CRDs.
+
+For example (below), Istio CRDs can be imported and used as though they were intrinsic Kubernetes resources.
+
+
+## Generating TypeScript Types from CRDs
+
+Using the kubernetes-fluent-client to produce a new type looks like this:
+
+```bash
+npx kubernetes-fluent-client crd [source] [directory]
+```
+
+The `crd` command expects a `[source]`, which can be a URL or local file containing the `CustomResourceDefinition(s)`, and a `[directory]` where the generated code will live.
+
+The following example creates types for the Istio CRDs:
+
+```bash
+user@workstation$  npx kubernetes-fluent-client crd https://raw.githubusercontent.com/istio/istio/master/manifests/charts/base/crds/crd-all.gen.yaml crds
+
+Attempting to load https://raw.githubusercontent.com/istio/istio/master/manifests/charts/base/crds/crd-all.gen.yaml as a URL
+
+- Generating extensions.istio.io/v1alpha1 types for WasmPlugin
+- Generating networking.istio.io/v1alpha3 types for DestinationRule
+- Generating networking.istio.io/v1beta1 types for DestinationRule
+- Generating networking.istio.io/v1alpha3 types for EnvoyFilter
+- Generating networking.istio.io/v1alpha3 types for Gateway
+- Generating networking.istio.io/v1beta1 types for Gateway
+- Generating networking.istio.io/v1beta1 types for ProxyConfig
+- Generating networking.istio.io/v1alpha3 types for ServiceEntry
+- Generating networking.istio.io/v1beta1 types for ServiceEntry
+- Generating networking.istio.io/v1alpha3 types for Sidecar
+- Generating networking.istio.io/v1beta1 types for Sidecar
+- Generating networking.istio.io/v1alpha3 types for VirtualService
+- Generating networking.istio.io/v1beta1 types for VirtualService
+- Generating networking.istio.io/v1alpha3 types for WorkloadEntry
+- Generating networking.istio.io/v1beta1 types for WorkloadEntry
+- Generating networking.istio.io/v1alpha3 types for WorkloadGroup
+- Generating networking.istio.io/v1beta1 types for WorkloadGroup
+- Generating security.istio.io/v1 types for AuthorizationPolicy
+- Generating security.istio.io/v1beta1 types for AuthorizationPolicy
+- Generating security.istio.io/v1beta1 types for PeerAuthentication
+- Generating security.istio.io/v1 types for RequestAuthentication
+- Generating security.istio.io/v1beta1 types for RequestAuthentication
+- Generating telemetry.istio.io/v1alpha1 types for Telemetry
+
+✅ Generated 23 files in the istio directory
+```
+
+Observe that the `kubernetes-fluent-client` has produced the TypeScript types within the `crds` directory. These types can now be utilized in the Pepr module.
+
+```typescript
+user@workstation$  cat crds/proxyconfig-v1beta1.ts
+// This file is auto-generated by kubernetes-fluent-client, do not edit manually
+
+import { GenericKind, RegisterKind } from "kubernetes-fluent-client";
+
+export class ProxyConfig extends GenericKind {
+    /**
+     * Provides configuration for individual workloads. See more details at:
+     * https://istio.io/docs/reference/config/networking/proxy-config.html
+     */
+    spec?:   Spec;
+    status?: { [key: string]: any };
+}
+
+/**
+ * Provides configuration for individual workloads. See more details at:
+ * https://istio.io/docs/reference/config/networking/proxy-config.html
+ */
+export interface Spec {
+    /**
+     * The number of worker threads to run.
+     */
+    concurrency?: number;
+    /**
+     * Additional environment variables for the proxy.
+     */
+    environmentVariables?: { [key: string]: string };
+    /**
+     * Specifies the details of the proxy image.
+     */
+    image?: Image;
+    /**
+     * Optional.
+     */
+    selector?: Selector;
+}
+
+/**
+ * Specifies the details of the proxy image.
+ */
+export interface Image {
+    /**
+     * The image type of the image.
+     */
+    imageType?: string;
+}
+
+/**
+ * Optional.
+ */
+export interface Selector {
+    /**
+     * One or more labels that indicate a specific set of pods/VMs on which a policy should be
+     * applied.
+     */
+    matchLabels?: { [key: string]: string };
+}
+
+RegisterKind(ProxyConfig, {
+  group: "networking.istio.io",
+  version: "v1beta1",
+  kind: "ProxyConfig",
+});
+```
+
+## Using new types
+
+The generated types can be imported into Pepr directly, _there is no additional logic needed to make them to work_. 
+
+```typescript
+import { Capability, K8s, Log, a, kind } from "pepr";
+
+import { Gateway } from "../crds/gateway-v1beta1";
+import {
+  PurpleDestination,
+  VirtualService,
+} from "../crds/virtualservice-v1beta1";
+
+export const IstioVirtualService = new Capability({
+  name: "istio-virtual-service",
+  description: "Generate Istio VirtualService resources",
+});
+
+// Use the 'When' function to create a new action
+const { When, Store } = IstioVirtualService;
+
+// Define the configuration keys
+enum config {
+  Gateway = "uds/istio-gateway",
+  Host = "uds/istio-host",
+  Port = "uds/istio-port",
+  Domain = "uds/istio-domain",
+}
+
+// Define the valid gateway names
+const validGateway = ["admin", "tenant", "passthrough"];
+
+// Watch Gateways to get the HTTPS domain for each gateway
+When(Gateway)
+  .IsCreatedOrUpdated()
+  .WithLabel(config.Domain)
+  .Watch(vs => {
+    // Store the domain for the gateway
+    Store.setItem(vs.metadata.name, vs.metadata.labels[config.Domain]);
+  });
+```

package/website/content/en/docs/diagrams.txt

@@ -0,0 +1,18 @@
+---
+title: Mermaid Diagram Samples
+description: Mermaid
+---
+<!-- 
+In certain instances a markdown viewer may not display due to
+the '---' frontmatter block above. If you're one of those edge
+cases enclose the frontmatter at the top of this file entirely
+within a comment block just like this comment.
+-->
+
+```mermaid
+graph TD
+  Start --> Need{"Hugo version >= 0.93.0"}
+  Need -- No --> Off["Set params.mermaid.enable = true"]
+  Off --> Author
+  Need -- Yes --> Author[Insert mermaid codeblock]
+```

package/website/content/en/docs/metrics.md

@@ -0,0 +1,74 @@
+---
+title: Metrics
+linkTitle: Metrics
+---
+
+# `/metrics` Endpoint Documentation
+
+The `/metrics` endpoint provides metrics for the application that are collected via the `MetricsCollector` class. It uses the `prom-client` library and performance hooks from Node.js to gather and expose the metrics data in a format that can be scraped by Prometheus.
+
+## Metrics Exposed
+
+The `MetricsCollector` exposes the following metrics:
+
+- `pepr_errors`: A counter that increments when an error event occurs in the application.
+- `pepr_alerts`: A counter that increments when an alert event is triggered in the application.
+- `pepr_Mutate`: A summary that provides the observed durations of mutation events in the application.
+- `pepr_Validate`: A summary that provides the observed durations of validation events in the application.
+
+## API Details
+
+**Method:** GET
+
+**URL:** `/metrics`
+
+**Response Type:** text/plain
+
+**Status Codes:**
+- 200 OK: On success, returns the current metrics from the application.
+
+**Response Body:**
+The response body is a plain text representation of the metrics data, according to the Prometheus exposition formats. It includes the metrics mentioned above.
+
+## Examples
+
+### Request
+
+```plaintext
+GET /metrics
+```
+
+### Response
+```plaintext
+  `# HELP pepr_errors Mutation/Validate errors encountered
+  # TYPE pepr_errors counter
+  pepr_errors 5
+  
+  # HELP pepr_alerts Mutation/Validate bad api token received
+  # TYPE pepr_alerts counter
+  pepr_alerts 10
+  
+  # HELP pepr_Mutate Mutation operation summary
+  # TYPE pepr_Mutate summary
+  pepr_Mutate{quantile="0.01"} 100.60707900021225
+  pepr_Mutate{quantile="0.05"} 100.60707900021225
+  pepr_Mutate{quantile="0.5"} 100.60707900021225
+  pepr_Mutate{quantile="0.9"} 100.60707900021225
+  pepr_Mutate{quantile="0.95"} 100.60707900021225
+  pepr_Mutate{quantile="0.99"} 100.60707900021225
+  pepr_Mutate{quantile="0.999"} 100.60707900021225
+  pepr_Mutate_sum 100.60707900021225
+  pepr_Mutate_count 1
+  
+  # HELP pepr_Validate Validation operation summary
+  # TYPE pepr_Validate summary
+  pepr_Validate{quantile="0.01"} 201.19413900002837
+  pepr_Validate{quantile="0.05"} 201.19413900002837
+  pepr_Validate{quantile="0.5"} 201.2137690000236
+  pepr_Validate{quantile="0.9"} 201.23339900001884
+  pepr_Validate{quantile="0.95"} 201.23339900001884
+  pepr_Validate{quantile="0.99"} 201.23339900001884
+  pepr_Validate{quantile="0.999"} 201.23339900001884
+  pepr_Validate_sum 402.4275380000472
+  pepr_Validate_count 2
+```

package/website/content/en/docs/rbac.md

@@ -0,0 +1,153 @@
+---
+title: RBAC
+linkTitle: RBAC
+---
+
+# RBAC Modes
+
+During the build phase of Pepr (`npx pepr build --rbac-mode [admin|scoped]`), you have the option to specify the desired RBAC mode through specific flags. This allows fine-tuning the level of access granted based on requirements and preferences.
+
+## Modes
+
+**admin**   
+
+```bash
+npx pepr build --rbac-mode admin
+```
+
+**Description:** The service account is given cluster-admin permissions, granting it full, unrestricted access across the entire cluster. This can be useful for administrative tasks where broad permissions are necessary. However, use this mode with caution, as it can pose security risks if misused. This is the default mode.
+
+**scoped**
+
+```bash
+npx pepr build --rbac-mode scoped
+```
+
+**Description:** The service account is provided just enough permissions to perform its required tasks, and no more. This mode is recommended for most use cases as it limits potential attack vectors and aligns with best practices in security. _The admission controller's primary mutating or validating action doesn't require a ClusterRole (as the request is not persisted or executed while passing through admission control), if you have a use case where the admission controller's logic involves reading other Kubernetes resources or taking additional actions beyond just validating, mutating, or watching the incoming request, appropriate RBAC settings should be reflected in the ClusterRole. See how in [Updating the ClusterRole](#updating-the-clusterrole)._
+
+## Debugging RBAC Issues
+
+If encountering unexpected behaviors in Pepr while running in scoped mode, check to see if they are related to RBAC.
+
+1. Check Deployment logs for RBAC errors:
+
+```bash
+kubectl logs -n pepr-system  -l app | jq
+
+# example output
+{
+  "level": 50,
+  "time": 1697983053758,
+  "pid": 16,
+  "hostname": "pepr-static-test-watcher-745d65857d-pndg7",
+  "data": {
+    "kind": "Status",
+    "apiVersion": "v1",
+    "metadata": {},
+    "status": "Failure",
+    "message": "configmaps \"pepr-ssa-demo\" is forbidden: User \"system:serviceaccount:pepr-system:pepr-static-test\" cannot patch resource \"configmaps\" in API group \"\" in the namespace \"pepr-demo-2\"",
+    "reason": "Forbidden",
+    "details": {
+      "name": "pepr-ssa-demo",
+      "kind": "configmaps"
+    },
+    "code": 403
+  },
+  "ok": false,
+  "status": 403,
+  "statusText": "Forbidden",
+  "msg": "Dooes the ServiceAccount permissions to CREATE and PATCH this ConfigMap?"
+}
+```
+
+2. Verify ServiceAccount Permissions with `kubectl auth can-i`
+
+```bash
+SA=$(kubectl get deploy -n pepr-system -o=jsonpath='{range .items[0]}{.spec.template.spec.serviceAccountName}{"\n"}{end}')
+
+# Can i create configmaps as the service account in pepr-demo-2?
+kubectl auth can-i create cm --as=system:serviceaccount:pepr-system:$SA -n pepr-demo-2
+
+# example output: no
+```
+
+3. Describe the ClusterRole
+
+```bash
+SA=$(kubectl get deploy -n pepr-system -o=jsonpath='{range .items[0]}{.spec.template.spec.serviceAccountName}{"\n"}{end}')
+
+kubectl describe clusterrole $SA
+
+# example output:
+Name:         pepr-static-test
+Labels:       <none>
+Annotations:  <none>
+PolicyRule:
+  Resources            Non-Resource URLs  Resource Names  Verbs
+  ---------            -----------------  --------------  -----
+  peprstores.pepr.dev  []                 []              [create delete get list patch update watch]
+  configmaps           []                 []              [watch]
+  namespaces           []                 []              [watch]
+```
+
+## Updating the ClusterRole
+
+As discussed in the [Modes](#modes) section, the admission controller's primary mutating or validating action doesn't require a ClusterRole (as the request is not persisted or executed while passing through admission control), if you have a use case where the admission controller's logic involves reading other Kubernetes resources or taking additional actions beyond just validating, mutating, or watching the incoming request, appropriate RBAC settings should be reflected in the ClusterRole.
+
+Step 1: Figure out the desired permissions. (`kubectl create clusterrole --help` is a good place to start figuring out the syntax)
+
+```bash
+ kubectl create clusterrole configMapApplier --verb=create,patch --resource=configmap --dry-run=client -oyaml
+
+ # example output
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  creationTimestamp: null
+  name: configMapApplier
+rules:
+- apiGroups:
+  - ""
+  resources:
+  - configmaps
+  verbs:
+  - create
+  - patch
+```
+
+Step 2: Update the ClusterRole in the `dist` folder.
+
+```yaml
+...
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: pepr-static-test
+rules:
+  - apiGroups:
+      - pepr.dev
+    resources:
+      - peprstores
+    verbs:
+      - create
+      - get
+      - patch
+      - watch
+  - apiGroups:
+      - ''
+    resources:
+      - namespaces
+    verbs:
+      - watch
+  - apiGroups:
+      - ''
+    resources:
+      - configmaps
+    verbs:
+      - watch
+      - create # New
+      - patch  # New
+...
+```
+
+Step 3: Apply the updated configuration

package/website/content/en/docs/webassembly.md

@@ -0,0 +1,189 @@
+---
+title: WebAssembly
+linkTitle: WebAssembly
+---
+
+# WASM Support: Running WebAssembly in Pepr Guide
+
+Pepr fully supports WebAssembly. Depending on the language used to generate the WASM, certain files can be too large to fit into a `Secret` or `ConfigMap`. Due to this limitation, users have the ability to incorporate `*.wasm` and any other essential files during the build phase, which are then embedded into the Pepr Controller container. This is achieved through adding an array of files to the `includedFiles` section under `pepr` in the `package.json`.
+
+> **NOTE -** In order to instantiate the WebAsembly module in TypeScript, you need the WebAssembly type. This is accomplished through add the "DOM" to the `lib` array in the `compilerOptions` section of the `tsconfig.json`. Ex: `"lib": ["ES2022", "DOM"]`. Be aware that adding the DOM will add a lot of extra types to your project and your developer experience will be impacted in terms of the intellisense. 
+
+
+## High-Level Overview
+
+WASM support is achieved through adding files as layers atop the Pepr controller image, these files are then able to be read by the individual capabilities. The key components of WASM support are:
+
+- Add files to the **base** of the Pepr module.
+- Reference the files in the `includedFiles` section of the `pepr` block of the `package.json` 
+- Run `npx pepr build` with the `-r ` option specifying registry info. Ex: `npx pepr build -r docker.io/cmwylie19`
+- Pepr builds and pushes a custom image that is used in the `Deployment`.
+
+## Using WASM Support 
+
+### Creating a WASM Module in Go
+
+Create a simple Go function that you want to call from your Pepr module
+
+```go
+package main
+
+import (
+	"fmt"
+	"syscall/js"
+)
+
+func concats(this js.Value, args []js.Value) interface{} {
+    fmt.Println("PeprWASM!")
+	stringOne := args[0].String()
+	stringTwo := args[1].String()
+	return fmt.Sprintf("%s%s", stringOne, stringTwo)
+}
+
+func main() {
+	done := make(chan struct{}, 0)
+	js.Global().Set("concats", js.FuncOf(concats))
+	<-done
+}
+```
+
+Compile it to a wasm target and move it to your Pepr module
+
+```bash
+GOOS=js GOARCH=wasm go build -o main.wasm
+cp main.wasm $YOUR_PEPR_MODULE/
+```
+
+Copy the `wasm_exec.js` from `GOROOT` to your Pepr Module
+
+```bash
+cp "$(go env GOROOT)/misc/wasm/wasm_exec.js" $YOUR_PEPR_MODULE/
+```
+
+Update the polyfill to add `globalThis.crypto` in the `wasm_exec.js` since we are not running in the browser. This is needed directly under: `(() => {`
+
+
+```javascript
+// Initialize the polyfill
+if (typeof globalThis.crypto === 'undefined') {
+    globalThis.crypto = {
+        getRandomValues: (array) => {
+        for (let i = 0; i < array.length; i++) {
+            array[i] = Math.floor(Math.random() * 256);
+        }
+        },
+    };
+}
+```
+
+
+### Configure Pepr to use WASM
+
+After adding the files to the root of the Pepr module, reference those files in the `package.json`:
+
+```json
+{
+  "name": "pepr-test-module",
+  "version": "0.0.1",
+  "description": "A test module for Pepr",
+  "keywords": [
+    "pepr",
+    "k8s",
+    "policy-engine",
+    "pepr-module",
+    "security"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "pepr": {
+    "name": "pepr-test-module",
+    "uuid": "static-test",
+    "onError": "ignore",
+    "alwaysIgnore": {
+      "namespaces": [],
+      "labels": []
+    },
+    "includedFiles":[
+      "main.wasm",
+      "wasm_exec.js"
+    ]
+  },
+  ...
+}
+```
+
+Update the `tsconfig.json` to add "DOM" to the `compilerOptions` lib:
+
+```json
+{
+  "compilerOptions": {
+    "allowSyntheticDefaultImports": true,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "esModuleInterop": true,
+    "lib": [
+      "ES2022",
+      "DOM" // <- Add this
+    ],
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "outDir": "dist",
+    "resolveJsonModule": true,
+    "rootDir": ".",
+    "strict": false,
+    "target": "ES2022",
+    "useUnknownInCatchVariables": false
+  },
+  "include": [
+    "**/*.ts"
+  ]
+}
+```
+
+### Call WASM functions from TypeScript
+
+Import the `wasm_exec.js` in the `pepr.ts`
+
+```javascript
+import "./wasm_exec.js";
+```
+
+Create a helper function to load the wasm file in a capability and call it during an event of your choice
+
+```typescript
+async function callWASM(a,b) {
+  const go = new globalThis.Go();
+
+  const wasmData = readFileSync("main.wasm");
+  var concated: string;
+
+  await WebAssembly.instantiate(wasmData, go.importObject).then(wasmModule => {
+    go.run(wasmModule.instance);
+  
+    concated = global.concats(a,b);
+  });
+  return concated;
+}
+
+When(a.Pod)
+.IsCreated()
+.Mutate(async pod => {
+  try {
+    let label_value = await callWASM("loves","wasm")
+    pod.SetLabel("pepr",label_value)
+  } 
+  catch(err) {
+    Log.error(err);
+  }
+});
+```
+
+### Run Pepr Build 
+
+Build your Pepr module with the registry specified.
+
+```bash
+npx pepr build -r docker.io/defenseunicorns
+```

package/website/go.mod

@@ -0,0 +1,8 @@
+module main
+
+go 1.20
+
+require (
+	github.com/defenseunicorns/defense-unicorns-hugo-theme v0.3.9 // indirect
+	github.com/defenseunicorns/defense-unicorns-hugo-theme/dependencies v0.3.9 // indirect
+)

package/website/go.sum

@@ -0,0 +1,4 @@
+github.com/defenseunicorns/defense-unicorns-hugo-theme v0.3.9 h1:o2ptq0ozp8x5R61Ik0E08YI3VEBjJGwUvKs8sRleUC8=
+github.com/defenseunicorns/defense-unicorns-hugo-theme v0.3.9/go.mod h1:qOBlMoMnovWO8PwmHAlpR7WfPLOJiiq4+XIrVblRb8g=
+github.com/defenseunicorns/defense-unicorns-hugo-theme/dependencies v0.3.9 h1:nz4Aiu+ISXKESXgTjPyDyR9L708XjszH6lnQAGFAAVI=
+github.com/defenseunicorns/defense-unicorns-hugo-theme/dependencies v0.3.9/go.mod h1:zQT7gnRyPnVCNxREasYkyewPJLhemxlOGZhbu+9mcfQ=