The Controller Lifecycle Notifications plugin sends webhooks from the operations center to a configured endpoint based on the managed controller state changes, such as provisioned and deprovisioned.
Configuration
The plugin is configured under Manage Jenkins > Controller Lifecycle Notifications. Custom webhook data can be configured for a specific controller under the configuration page for that controller item in the operations center.
Figures 1-4 show examples of how to configure the Controller Lifecycle Notifications plugin, enable the Controller Lifecycle Notifications, add the custom webhook data, and complete the configuration.
Solution
When the managed controller’s lifecycle is updated, an event is sent to an external webhook. This webhook and the service behind it are not part of CloudBees CI and are not provided by CloudBees.
To secure the communication to the webhook, you must use a mutual TLS authentication (mTLS) by using a certificate that is known to CloudBees CI.
The content of the event is JSON-formatted and uniquely identifies the managed controller that is the source of the event. To provide the identity of the managed controller, its name, domain, and the operations center it belongs to will be part of the event.
The event also contains an additional customizable data field, statically provided for each managed controller item in the Controller Lifecycle Notifications Managed Controller property available on the custom data page shown in Figure 3. This data does not need any computation from the CloudBees CI products and will be sent to the event as is.
Additional data is provided for each managed controller item in the the Controller Lifecycle Notifications Managed Controller property.
The webhook endpoint is provided at the operations center level, in a dedicated administration page.
If you use a CloudBees CasC bundle for the operations center, the version of the bundle is included in the webhook payload. Refer to the following example:
{ "status": "PROVISIONING", "id": "b905b61a-0286-4479-ad81-3aad2c732641", "timestamp": "2024-07-08T17:16:35.990023Z", "controller": { "name": "mc", "displayName": "mc", "domain": "mc", "image": "cloudbees/cloudbees-core-mm:2.452.2.4" }, "operationsCenter": { "url": "http://localhost:52215/jenkins/", "cascBundleVersion": "1.2.3" } }
Use Cases
With the introduction of the Controller Lifecycle Notifications plugin, you can easily automate actions when a lifecycle event occurs. The following use cases are supported:
-
Provision/deprovision
-
When a CasC bundle is updated and reloaded by the operations center and when a managed controller is provisioned or deprovisioned, a notification is sent to an external webhook.
-
If an error occurs during provisioning or deprovisioning, a notification is sent to an external webhook.
-
The status names that are supported by the Controller Lifecycle Notifications plugin are listed in the following table.
Status names and descriptions
The following table shows the status names and descriptions.
| Status name | Definition | Example payload |
|---|---|---|
|
Sent when a controller connects to the operations center after its health check endpoint is reachable from the operations center. |
|
|
Sent when the operations center completes a request to deprovision a controller. |
|
|
Sent when the operations center initiates a request to deprovision a controller. |
|
|
Sent if the operations center encounters an error when it tries to deprovision a controller. It only includes fatal errors, such as the Kubernetes API being unreachable. |
|
|
Sent when a controller disconnects from the operations center. |
|
|
Sent when the operations center completes a request to provision a controller. The underlying Kubernetes resource provisioning may still be incomplete. |
|
|
Sent when the operations center initiates a request to provision a controller. |
|
|
Sent if the operations center encounters an error when it tries to provision a controller. It only includes fatal errors, such as the Kubernetes API being unreachable. |
|
|
Sent when the operations center initiates a request to restart a controller. |
|
|
Sent if the operations center encounters an error when it tries to restart a controller. It only includes fatal errors, such as the Kubernetes API being unreachable. |
|
|
Sent when the operations center completes a request to start a controller. The controller may not have started yet. This status can be sent when the controller does not start; for example, if it requests too much memory for the pod to be scheduled. |
|
|
Sent if a |
|
|
Sent when the operations center initiates a request to start a controller. |
|
|
Sent if the operations center encounters an error when it tries to start a controller. It only includes fatal errors, such as the Kubernetes API being unreachable. |
|
|
Sent when the operations center completes a request to stop a controller. |
|
|
Sent when the operations center initiates a request to stop a controller. |
|
|
Sent if the operations center encounters an error when it tries to stop a controller. It only includes fatal errors, such as the Kubernetes API being unreachable. |
|
For information about the Controller Lifecycle Notifications plugin release notes, refer to Operations Center Plugins.