Skill lifecycle hooks

Skill lifecycle hooks are scripts embedded directly in a skill definition that the Node Management agent executes at specific points in a skill’s lifecycle. You can use hooks to run custom automation logic, such as stopping a service before an upgrade, running validation checks after an install, or cleaning up state before a delete.

Hooks are OS-specific: you can provide separate scripts for Linux and Windows nodes. When the agent runs on a node, it picks the script that matches its operating system and silently skips the stage if no matching script exists.

Role requirements

To configure lifecycle hooks on a skill, you must use a profile with the node-manager role.

Lifecycle hooks reference

To define a lifecycle hook, add the hooks object to a skill’s JSON definition:

hooks

Optional. Defines the lifecycle hook scripts for the skill. If you omit this field, the skill installs and runs without any lifecycle scripts.

<LIFECYCLE_STAGE>

An object for a lifecycle stage. Accepted values: preInstall, postInstall, preUpdate, postUpdate, preDelete, postDelete.

scripts

An array of scripts to run at this lifecycle stage.

targetPlatform: The operating system that runs this script. Accepted values: linux or windows.
You can include each targetPlatform value (linux or windows) at most once per lifecycle stage. Including the same platform more than once in a stage is a validation error.
script: A base64-encoded shell script. Use Bash on Linux or PowerShell on Windows.
timeoutSeconds: The number of seconds the agent waits before killing the process. Default: 300 (5 minutes). Minimum: 1.

For example:

{
  "name": "<SKILL_NAME>",
  // ...
  "hooks": {
    "<LIFECYCLE_STAGE>": {
      "scripts": [
        {
          "targetPlatform": "<PLATFORM>",
          "script": "<BASE_64_ENCODED_SCRIPT>",
          "timeoutSeconds": <SECONDS>
        }
      ]
    }
  }
}

Note

The skill definition example shows only the hooks field. Your skill definition may include other fields such as canister, dependencies, and configurationTemplates.

Lifecycle stages

You can attach a hook to the following six lifecycle stages:

preInstall: Runs before the agent installs the skill. If the hook fails, the agent reports the failure and aborts the install.
postInstall: Runs after the agent successfully installs the skill. If the hook fails, the agent reports the failure but doesn’t roll back the install.
preUpdate: Runs before the agent updates the skill. A version upgrade or a settings/configuration change triggers this stage. If the hook fails, the agent reports the failure and aborts the update.
postUpdate: Runs after the agent successfully updates the skill. A version upgrade or a settings/configuration change triggers this stage. If the hook fails, the agent reports the failure but doesn’t roll back the update.
preDelete: Runs before the agent deletes the skill. If the hook fails, the agent reports the failure and aborts the delete.
postDelete: Runs after the agent successfully deletes the skill. If the hook fails, the agent reports the failure, but no rollback is possible.

Configure lifecycle hooks

Add hooks when creating a skill

To create a skill with lifecycle hooks, follow these steps:

Create a JSON file with the skill definition, including the hooks field. For example:

{
  "name": "chef-client-interpreter",
  // ...
  "hooks": {
    "preInstall": {
      "scripts": [
        {
          "targetPlatform": "linux",
          "script": "IyEvYmluL2Jhc2gKZWNobyAiUnVubmluZyBwcmVJbnN0YWxsIGhvb2si",
          "timeoutSeconds": 120
        },
        {
          "targetPlatform": "windows",
          "script": "V3JpdGUtT3V0cHV0ICJSdW5uaW5nIHByZUluc3RhbGwgaG9vayI=",
          "timeoutSeconds": 120
        }
      ]
    },
    "postInstall": {
      "scripts": [
        {
          "targetPlatform": "linux",
          "script": "IyEvYmluL2Jhc2gKZWNobyAiUnVubmluZyBwb3N0SW5zdGFsbCBob29rIg==",
          "timeoutSeconds": 300
        }
      ]
    }
  }
}

Note

The skill definition example shows only the hooks field. Your skill definition may include other fields such as canister, dependencies, and configurationTemplates.

Create the skill:
```
chef-node-management-cli management skill create-skill \
  --body-file <PATH_TO_JSON_FILE> \
  --profile <NODE_MANAGER_PROFILE_NAME>
```
Replace:
- <PATH_TO_JSON_FILE> with the path to the JSON file you created.
- <NODE_MANAGER_PROFILE_NAME> with the name of a profile that has the node-manager role.

Update hooks on an existing skill

To update the lifecycle hooks on an existing skill, follow these steps:

Retrieve the current skill definition:

chef-node-management-cli management skill find-one-skill \
  --skillName <SKILL_NAME> \
  --profile <NODE_MANAGER_PROFILE_NAME> \
  --format json > skill.json

Edit skill.json to add or update the hooks field. To remove all hooks, set hooks to null or omit it.
Warning
Updating a skill overwrites the entire existing skill definition. You must include all existing skill fields (for example, canister, dependencies, and configurationTemplates) alongside the updated hooks field, or the update removes those fields from the skill definition.
To retrieve the current definition, use the find-one-skill command.

Update the skill:

chef-node-management-cli management skill modify-skill \
  --skillName <SKILL_NAME> \
  --body-file skill.json \
  --profile <NODE_MANAGER_PROFILE_NAME>

Replace:

<SKILL_NAME> with the name of the skill you want to update.
<NODE_MANAGER_PROFILE_NAME> with the name of a profile that has the node-manager role.

View hook execution history

To view hook execution results for a node, use the hook-executions endpoint in the Chef Node Management REST API:

GET /node/management/v1/nodes/{nodeId}/hook-executions

Each record includes the following fields:

id: Unique identifier for the hook execution record.
skillName: Name of the skill associated with this hook execution.
skillVersion: Version of the skill at the time of execution.
lifecycleStage: Stage that triggered the hook (pre_install, post_install, pre_update, post_update, pre_delete, post_delete).
status: Execution outcome: success, failure, or timeout.
exitCode: Exit code returned by the script process.
stdout: Standard output captured from the script.
stderr: Standard error captured from the script.
executedAt: Timestamp (RFC 3339) when the hook ran on the node.

How hooks are delivered to agents

Hooks are part of the skill definition and are delivered to agents during each check-in. Before each check-in, the agent calls the skills API to retrieve the latest skill definitions, which include the embedded hooks.

The agent uses hash-based change detection on skill definitions. If you update a hook script, the hash of the affected skill definition changes, which triggers the agent to apply the change immediately at its next check-in.

Hook execution environment

When the agent runs a hook script, it injects the skill’s settings—global defaults merged with any override settings—as environment variables. The agent exposes each setting as CHEF_HOOK_<NAME>, where <NAME> is the setting name converted to uppercase with - and . replaced by _.

For example, a setting named config-name.key is available in the script as CHEF_HOOK_CONFIG_NAME_KEY.

Your scripts can access these settings as environment variables.