github.com/Racer159/jackal@v0.32.7-0.20240401174413-0bd2339e4f2e/examples/component-webhooks/README.md (about)

     1  import ExampleYAML from '@site/src/components/ExampleYAML';
     2  
     3  # Component Webhooks
     4  
     5  :::caution
     6  
     7  Component Webhooks is currently an [Alpha Feature](../../docs/9-roadmap.md#alpha). This feature is not extensively tested and may be affected by breaking changes in the future. We encourage you to experiment with this feature and provide feedback to the Jackal team as we begin to stabilize this feature.
     8  
     9  :::
    10  
    11  This example demonstrates how to use webhooks to perform actions during the lifecycle of package deployments. Webhooks are similar to [Component Actions](../../docs/3-create-a-jackal-package/7-component-actions.md) 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 `jackal.yaml` while webhooks are defined within the cluster that you are deploying your package onto.
    12  
    13  This example uses `Pepr` as a mutating webhook that watches for any updates to a jackal package secret. As `Jackal` deploys components, it updates a secret in the `jackal` 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 `Jackal` 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 `Jackal` 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. `Jackal` will poll the secret every second to check if the webhook is complete allowing it to continue deploying the rest of the package.
    14  
    15  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.
    16  
    17  :::info
    18  
    19  If you want to update the capability yourself, you will need to rebuild the `Pepr` module before creating the package.
    20  
    21  This can be completed by running the following commands:
    22  `npm ci`
    23  `npx pepr build`
    24  `jackal package create ./dist`
    25  
    26  :::
    27  
    28  ## `jackal.yaml` {#jackal.yaml}
    29  
    30  :::info
    31  
    32  To view the example in its entirety, select the `Edit this page` link below the article and select the parent folder.
    33  
    34  :::
    35  
    36  <ExampleYAML src={require('./jackal.yaml')} showLink={false} />