component-webhooks

This example demonstrates how to use webhooks to perform actions during the lifecycle of package deployments. Webhooks are similar to Component Actions such that they both enable complex functionality to be executed during the lifecycle of a package deployment. The key difference between webhooks and actions is that actions are defined within the package’s zarf.yaml while webhooks are defined within the cluster that you are deploying your package onto.

This example uses Pepr as a mutating webhook that watches for any updates to a zarf package secret. As zarf deploys components, it updates a secret in the zarf namespace that ‘declares’ what components are being deployed. Pepr watches for these updates and runs an example operation for each component that gets deployed to the cluster. Since Pepr is a mutating webhook, as zarf updates the package secret for each component that is being deployed, Pepr will modify the secret to denote that a webhook operation is executing for that component. To account for this, every time zarf updates the package secret, it will check to see if a webhook has modified the secret and will wait if there are any webhooks in a Running state. The webhook itself is responsible for updating the secrets when it’s operations complete. zarf will poll the secret every second to check if the webhook is complete allowing it to continue deploying the rest of the package.

Webhooks have the potential to be extremely powerful. Since they are written in Javascript, they have the capability to do almost anything that you can do with JavaScript. This includes interacting with the Kubernetes API, interacting with other APIs, or even interacting with other systems. Caution should be exercised when deploying webhooks to clusters as they have the potential to run any time a new package is deployed to the cluster, and future package deployers might not be aware that the cluster has webhooks configured.

If you want to update the capability yourself, you will need to rebuild the Pepr module before creating the package.

This can be completed by running the following commands:

npm ci
npx pepr build
zarf package create ./dist

kind: ZarfPackageConfig
metadata:
  name: component-webhooks
  description: Example Pepr Module for Component Webhooks
  url: https://github.com/defenseunicorns/pepr
  version: 0.0.1

components:
  - name: module
    required: true
    manifests:
      - name: module
        namespace: pepr-system
        files:
          - pepr-module-cb5693ef-d13c-5fe1-b5ad-c870fd911b3b.yaml
    images:
      - ghcr.io/defenseunicorns/pepr/controller:v0.15.0