Configure node lifecycle actions in AWS PCS

You define node lifecycle actions in your compute node group configuration. This topic describes how to define a script, control whether it re-runs on reboot, store it, pass it arguments, handle failures, cache it, validate its integrity, and read its logs.

How to define a script

Each script has a name, a scriptSource, optional arguments, an onError policy, and an executionPolicy. The location and integrity fields are grouped under scriptSource.

{
  "name": "My script",
  "scriptSource": {
    "scriptLocation": "s3://my-bucket/my-script.sh",
    "s3VersionId": "optional, S3 only",
    "checksum": "optional 64-char SHA-256 hex"
  },
  "arguments": ["arg1", "arg2"],
  "onError": "TERMINATE",
  "executionPolicy": "FIRST_BOOT_ONLY"
}

Add lifecycle actions to a compute node group

You can add lifecycle actions when you create or update a compute node group. Use the AWS Management Console or the AWS CLI.

AWS Management Console

To add lifecycle actions using the console

1. Open the AWS PCS console.

2. Open the create or update page for a compute node group.

3. In the Node lifecycle actions section, choose Add script.

4. Select the script source:

   1. Add from AWS PCS scripts library – Reference an AWS-maintained script. For more information, see Use AWS-maintained scripts for node lifecycle actions in AWS PCS.

   2. Add via S3 – Reference a script by its Amazon S3 URI.

   3. Add via HTTPS – Reference a script by its HTTPS URL.

5. Select the node stage.

6. For a script that you add via S3 or HTTPS, specify these settings:

   1. Script location – Enter the S3 URI or HTTPS URL for the script.

   2. Name – Enter a name for the script.

   3. (Optional) Checksum – Enter a SHA-256 checksum to verify the script's integrity. For more information, see Script integrity (checksums).

   4. (Optional) For a script that you add via S3, enter a version to reference a specific version of the object.

7. For all script sources, specify these settings:

   1. Error handling behavior – Select TERMINATE, STOP_SEQUENCE, or CONTINUE.

   2. Execution policy – Select FIRST_BOOT_ONLY or EVERY_BOOT.

   3. (Optional) Arguments – Add arguments to pass to the script.

8. To add more scripts, repeat these steps.

9. Scripts run from top to bottom within a stage. To change the execution order, choose Actions for a script, and then choose Move up or Move down.

10. For Caching policy, select CACHE_ONCE or REFRESH_ON_REBOOT. The caching policy applies to all scripts. For more information, see Script caching and updates.

AWS CLI

Use the --node-lifecycle-actions parameter with the create-compute-node-group or update-compute-node-group command. For the parameter structure, see NodeLifecycleActionsRequest in the AWS PCS API Reference. For example commands, see Node lifecycle action examples for AWS PCS.

Controlling reboot behavior

Set executionPolicy per script to control whether it re-runs on reboot.

Scripts set to FIRST_BOOT_ONLY run once and are skipped on reboot. Scripts set to EVERY_BOOT run on every boot and should be idempotent (safe to run more than once with the same result).

Script storage locations

You can store scripts in Amazon S3 or serve them over HTTPS. Scripts can't be uploaded inline through the API, and each script must be no larger than 2 MiB — the agent rejects any script that exceeds this size.

External storage provides version control, auditability, and reuse across teams. Inline or uploaded scripts are not supported.

Passing arguments to scripts

Pass arguments as an ordered array. They reach your script as positional command-line parameters.

arguments: ["fs-12345678", "/shared", "nfs4"]
# script.sh fs-12345678 /shared nfs4   ($1=fs-12345678, $2=/shared, $3=nfs4)

The agent exports environment variables to every script. These variables contain cluster and node metadata.

#!/usr/bin/env bash
echo "Configuring node $PCS_NODE_ID in cluster $PCS_CLUSTER_NAME"

Error handling

Each script has an onError field that controls what happens when a script exits non-zero or is killed by a signal.

A script fails if it exits non-zero or is killed by a signal (for example, SIGSEGV). Scripts are not retried. If an operation might experience transient failures, add retry logic inside the script. Script retrieval (download), however, is retried — up to 3 attempts with exponential backoff (approximately 17 seconds maximum) — before the onError behavior applies.

Script caching and updates

The agent downloads each script to the instance on first boot and stores it locally. Two fields control behavior on reboot: scriptCachingPolicy controls re-download and executionPolicy controls re-execution.

The lifecycle configuration (which scripts run, their arguments, error handling, and execution policy) is always immutable per instance. Changing it through UpdateComputeNodeGroup affects only new instances and triggers the DRAIN strategy so running jobs finish before nodes are replaced.

Script integrity (checksums)

Optionally provide a SHA-256 checksum in a script's scriptSource, as a 64-character hexadecimal string. The agent validates it on download; a mismatch is treated as a download failure and triggers onError. We recommend a checksum for production, especially for scripts from shared or external sources.

sha256sum mount-efs.sh   # use the 64-char hex hash as the checksum value

Logging and debugging

Each script writes to its own log file, and the agent keeps its own operational log.

# agent: download, caching, checksum, orchestration
/var/log/amazon/pcs/lifecycle/actions/executor.log
# each script's stdout/stderr
/var/log/amazon/pcs/lifecycle/actions/<stage>/<script-name>.log

The log filename uses the script name as you defined it. Spaces are preserved. For example, a script named Mount EFS home directory writes to Mount EFS home directory.log. Connect with SSH or AWS Systems Manager Session Manager to read them — both are available by the nodeBootstrapped stage. Because nodes that fail with TERMINATE are replaced, forward logs off-instance for debugging after termination: add a node bootstrapped script that configures the Amazon CloudWatch agent to ship the lifecycle log directory to Amazon CloudWatch Logs. The AWS-maintained configure-cloudwatch-logs.sh script does this. For more information, see Use AWS-maintained scripts for node lifecycle actions in AWS PCS.