Cloud-Init Extension Points

Learn how to customize Code Ocean EC2 instances using cloud-init extension scripts stored in AWS SSM Parameter Store.

Overview

Code Ocean allows you to run custom shell scripts on EC2 instances during boot (cloud-init) by storing them as AWS Systems Manager (SSM) Parameter Store parameters. This provides a supported extension mechanism for instance-level customizations without modifying the CloudFormation template directly.

Common use cases include:

• Installing security or monitoring agents

• Applying organization-specific OS-level settings

SSM Parameter Paths

Extension scripts are defined as String parameters in SSM Parameter Store. Two levels of targeting are supported:

Scope	Path
Global (all instance types)	/{STACK_NAME}/settings/cloud-init/{script_name}
Per instance type	/{STACK_NAME}/settings/{instance_type}/cloud-init/{script_name}

Replace {STACK_NAME} with your Code Ocean CloudFormation stack name.

Instance types

Instance type	Applies to
services	Code Ocean services instance
worker	All worker instance variants (General, GPU, Dedicated Machine)
jobs	System job instance
pipeline	Pipeline instance

Global parameters run on all instance types. Per-instance-type parameters run only on the specified type.

Script Naming and Execution Order

Script names follow a conf.d-style naming convention with an optional numeric prefix that controls execution order relative to Code Ocean's own initialization commands:

Numeric prefix	Execution phase
0–99	Runs before Code Ocean commands
100–199	Reserved for internal use
200+	Runs after Code Ocean commands

For example:

• 050-network-config — runs before Code Ocean commands

• 250-install-agent — runs after Code Ocean commands

Script names must start with an alphanumeric character and may contain letters, digits, dots, dashes, and underscores. For example: 050-install-agent, install-agent, 250-install_agent.sh.

Error Handling

• If a script fails, the error is logged as a warning but does not prevent the instance from completing its boot sequence.

• If no extension parameters are defined (the default), the system skips this step with no effect on boot.

Creating a Parameter

1. Open the AWS Systems Manager Parameter Store console.

2. Choose Create parameter.

3. For Name, enter the full path, e.g.: /{STACK_NAME}/settings/worker/cloud-init/050-install-agent

4. For Type, select String.

5. For Value, enter the shell script content (see example below).

6. Choose Create parameter.

After creating or updating a parameter, the new script will take effect on the next instance launch.