Cluster Launch Plugin API

The Deployment Manager provides a plugin API to customize how nodes are launched. The steps are split into two categories. Launch scripts run on the Deployment Manager to launch nodes, while init scripts run on the launched nodes.

This topic describes the detailed API for each kind of script.

General

The scripts need to be available to the Deployment Manager. They can either be files on a shared FileSystem (including S3) or available on the Deployment Manager host. The Deployment Manager will make a copy of the scripts so subsequent edits do not affect existing uses.

The scripts can be written in any language and we do not inspect them. We simply run them. We recommend writing them in Bash, as it will run without requiring bootstrapping (for example, installing Python).

The scripts should return 0 on success and non-zero on error. The scripts should print to stderr for diagnostics (ignored by Okera except for logging) and print the result to stdout. Okera parses the output from standard out and it must be output exactly as described in this document.

Either a launch script or a cluster launch script are required to create an environment.

Launch script

This script is responsible for creating one EC2 instance when called. Examples of actions in this script are:

  • Launch the EC2 instance in the desired VPC, with SSH keys and the correct security group.
  • Tag the instance as required.

This script must accept a single argument, which is passed as the --user-data option when launching the instance in AWS.

The script must also support the --dryrun flag. The Deployment Manager (DM) will invoke the launch script with this flag when executing an environments create command. When the launch script is called with the --dryrun flag specified, the DM expects the launch script to exit with a return code of zero (indicating success), regardless of whether the script does anything when the --dryrun flag is passed (that is, it can be a no-op). This functionality (the DM calling the script with --dryrun) is an opportunity to instrument your script to pass the parameters that it would use to AWS in combination with the --dry-run flag in order to detect configuration or permissions issues early in the install process. The launch script must not actually launch compute instances when called with the --dryrun flag.

This script should print <instance_id>,<public ip>,<private ip> to stdout. If the host lacks a public IP, then the output would be <instance id>,,<private ip>. It cannot output anything else to stdout.

Template

We recommend looking at the template file that comes as part of the Okera install, by default found at /opt/okera/deploymentmanager/bin/start-ec2-machine-example.sh. This script can help you get started. The sections in it marked by USER are the most common customizations.

Cluster Launch script

The cluster launch script must create an AWS autoscaling group (ASG) when invoked. This script must support the following flags:

  • --numHosts <# of hosts> specifies how many hosts the ASG should contain at any point
  • --name <ASG name> the name of the ASG

NOTE: the cluster launch script does not currently support the --dryrun flag because the underlying AWS call does not support that functionality.

Examples of actions in this script are:

  • Create a launch configuration with the desired IAM role and security groups specified.
  • Launch an autoscaling group in the desired VPC, using the aforementioned launch configuration.
  • Tagging the autoscaling group with the specification that the tags be applied to EC2 instances created by the autoscaling group.

This script should print out a list of n lines to stdout with each containing <instance id>,<public ip>,<private ip> where n is the value passed with the --host flag. If the ASG lacks a public IP, then the output would be <instance id>,,<private ip>. It cannot output anything else to stdout.

Template

We recommend looking at the template file that comes as part of the Okera install, by default found at /opt/okera/deploymentmanager/bin/start-ec2-asg-example.sh. This script can help you get started. The sections in it marked by USER are the most common customizations.

Init scripts

The Deployment Manager allows you to specify a list of scripts that should be run on the instance when it is first provisioned. This is equivalent to running all of these scripts as part of the --user-data AWS EC2 configuration.

These scripts are run in the order provided, always before any Okera instance setup scripts. We’ve included an example that will set up the package repo to an internal location: /opt/okera/deploymentmanager/bin/setup-repo-example.sh.

Init scripts should return non-zero on error and can log to stdout or stderr.