Skip to content

Commit

Permalink
docs.yml
Browse files Browse the repository at this point in the history
  • Loading branch information
docs.yml committed Jun 28, 2024
1 parent ad3528c commit a3022d4
Show file tree
Hide file tree
Showing 41 changed files with 4,105 additions and 2 deletions.
2 changes: 1 addition & 1 deletion site/content/en/v0.32.4/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Pepr
linkTitle: v0.32.4
cascade:
type: docs
aliases: ["/current/"]
aliases: []
---


Expand Down
158 changes: 158 additions & 0 deletions site/content/en/v0.32.5/_index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,158 @@
---
title: Pepr
linkTitle: v0.32.5
cascade:
type: docs
aliases: ["/current/"]
---


[![Pepr Documentation](https://img.shields.io/badge/docs--d25ba1)](https://docs.pepr.dev)
[![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)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/defenseunicorns/pepr/badge)](https://securityscorecards.dev/viewer/?uri=github.com/defenseunicorns/pepr)
[![Contributor Covenant](https://img.shields.io/badge/contributor%20covenant-2.1-4baaaa.svg)](code_of_conduct/)

#### **_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 organizational knowledge into code, simplifying documentation, testing, validation, and coordination of changes for a more predictable outcome.

## 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](./user-guide/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-resistant module execution
- Least-privilege [RBAC](./user-guide/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](./user-guide/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](./user-guide/pepr-modules/) 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](./user-guide/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](./user-guide/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).
127 changes: 127 additions & 0 deletions site/content/en/v0.32.5/best-practices/_index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
---
title: Pepr Best Practices
weight: 60
---


## Table of Contents

- [Pepr Best Practices](#pepr-best-practices)
- [Table of Contents](#table-of-contents)
- [Core Development](#core-development)
- [Debugging](#debugging)
- [Deployment](#deployment)
- [Keep Modules Small](#keep-modules-small)
- [Monitoring](#monitoring)
- [Multiple Modules or Multiple Capabilities](#multiple-modules-or-multiple-capabilities)
- [OnSchedule](#onschedule)
- [Reconcile](#reconcile)
- [Security](#security)
- [Pepr Store](#pepr-store)
- [Watch](#watch)


## Core Development

When developing new features in Pepr Core, it is recommended to use `npx pepr deploy -i pepr:dev`, which will deploy Pepr's Kubernetes manifests to the cluster with the development image. This will allow you to test your changes without having to build a new image and push it to a registry.

The workflow for developing features in Pepr is:

1. Run `npm test` which will create a k3d cluster and build a development image called `pepr:dev`
2. Deploy development image into the cluster with `npx pepr deploy -i pepr:dev`

## Debugging

Pepr can be broken down into two parts: Admission and Watches. If the focus of the debug is on a Mutation or Validation, then only pay attention to pods with labels `pepr.dev/controller: admission`, else, you can focus on `pepr.dev/controller: watch`.

## Deployment

Production environment deployments should be `declarative` in order to avoid mistakes. The Pepr modules should be generated with `npx pepr build` and moved into the appropriate location.

Development environment deployments can use `npx pepr deploy` to deploy Pepr's Kubernetes manifests into the cluster or `npx pepr dev` to active debug the Pepr module with breakpoints in the code editor.

## Keep Modules Small

Modules are minified and built JavaScript files that are stored in a Kubernetes Secret in the cluster. The Secret is mounted in the Pepr Pod and is processed by Pepr Core. Due to the nature of the module being packaged in a Secret, it is recommended to keep the modules as small as possible to avoid hitting the [1MB limit](https://kubernetes.io/docs/concepts/configuration/secret/#restriction-data-size) of secrets.

Recommendations for keeping modules small are:

- Don't repeat yourself
- Only import the part of the library modules that you need

It is suggested to lint and format your modules using `npx pepr format`.

## Monitoring

Pepr can monitor Mutations and Validations from Admission Controller the through the `npx pepr monitor [module-uuid]` command. This command will display neatly formatted log showing approved and rejected Validations as well as the Mutations. If `[module-uuid]` is not supplied, then it uses all Pepr admission controller logs as the data source. If you are unsure of what modules are currently deployed, issue `npx pepr uuid` to display the modules and their descriptions.

```plaintext
✅ MUTATE pepr-demo/pepr-demo (50c5d836-335e-4aa5-8b56-adecb72d4b17)
✅ VALIDATE pepr-demo/example-2 (01c1d044-3a33-4160-beb9-01349e5d7fea)
❌ VALIDATE pepr-demo/example-evil-cm (8ee44ca8-845c-4845-aa05-642a696b51ce)
[ 'No evil CM annotations allowed.' ]
```

## Multiple Modules or Multiple Capabilities

Each module has it's own Mutating, Validating webhook configurations, Admission and Watch Controllers and Stores. This allows for each module to be deployed independently of each other. However, creating multiple modules creates overhead on the kube-apiserver, and the cluster.

Due to the overhead costs, it is recommended to deploy multiple capabilities that share the same resources (when possible). This will simplify analysis of which capabilities are responsible for changes on resources.

However, there are some cases where multiple modules makes sense. For instance different teams owning separate modules, or one module for Validations and another for Mutations. If you have a use-case where you need to deploy multiple modules it is recommended to separate concerns by operating in different namespaces.

## OnSchedule

`OnSchedule` is supported by a `PeprStore` to safeguard against schedule loss following a pod restart. It is utilized at the top level, distinct from being within a `Validate`, `Mutate`, `Reconcile` or `Watch`. Recommended intervals are 30 seconds or longer, and jobs are advised to be idempotent, meaning that if the code is applied or executed multiple times, the outcome should be the same as if it had been executed only once. A major use-case for `OnSchedule` is day 2 operations.

## Security

To enhance the security of your Pepr Controller, we recommend following these best practices:

- Regularly update Pepr to the latest stable release.
- Secure Pepr through RBAC using [scoped mode](https://docs.pepr.dev/main/user-guide/rbac/#scoped) taking into account access to the Kubernetes API server needed in the callbacks.
- Practice the principle of least privilege when assigning roles and permissions and avoid giving the service account more permissions than necessary.
- Use NetworkPolicy to restrict traffic from Pepr Controllers to the minimum required.
- Limit calls from Pepr to the Kubernetes API server to the minimum required.
- Set webhook failure policies to `Fail` to ensure that the request is rejected if the webhook fails. More Below..

When using Pepr as a `Validating` Webhook, it is recommended to set the Webhook's `failurePolicy` to `Fail`. This can be done in your Pepr module in the`values.yaml` file of the helm chart by setting `admission.failurePolicy` to `Fail` or in the `package.json` under `pepr` by setting the `onError` flag to `reject`, then running `npx pepr build` again.

By following these best practices, you can help protect your Pepr Controller from potential security threats.

## Reconcile

Fills a similar niche to .Watch() -- and runs in the Watch Controller -- but it employs a Queue to force sequential processing of resource states once they are returned by the Kubernetes API. This allows things like operators to handle bursts of events without overwhelming the system or the Kubernetes API. It provides a mechanism to back off when the system is under heavy load, enhancing overall stability and maintaining the state consistency of Kubernetes resources, as the order of operations can impact the final state of a resource. For example, creating and then deleting a resource should be processed in that exact order to avoid state inconsistencies.

```typescript
When(WebApp)
.IsCreatedOrUpdated()
.Validate(validator)
.Reconcile(async instance => {
// Do WORK HERE
```
## Pepr Store
The store is backed by ETCD in a `PeprStore` resource, and updates happen at 5-second intervals when an array of patches is sent to the Kubernetes API Server. The store is intentionally not designed to be `transactional`; instead, it is built to be eventually consistent, meaning that the last operation within the interval will be persisted, potentially overwriting other operations. In simpler terms, changes to the data are made without a guarantee that they will occur simultaneously, so caution is needed in managing errors and ensuring consistency.
## Watch
Pepr streamlines the process of receiving timely change notifications on resources by employing the `Watch` mechanism. It is advisable to opt for `Watch` over `Mutate` or `Validate` when dealing with more extended operations, as `Watch` does not face any [timeout limitations](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#timeouts). Additionally, `Watch` proves particularly advantageous for monitoring previously existing resources within a cluster. One compelling scenario for leveraging `Watch` is when there is a need to chain API calls together, allowing `Watch` operations to be sequentially executed following `Mutate` and `Validate` actions.
```typescript
When(a.Pod)
.IsCreated()
.InNamespace("my-app")
.WithName("database")
.Mutate(pod => // .... )
.Validate(pod => // .... )
.Watch(async (pod, phase) => {
Log.info(pod, `Pod was ${phase}.`);

// do consecutive api calls
```
[TOP](#pepr-best-practices)
Loading

0 comments on commit a3022d4

Please sign in to comment.