Custom Platforms

Elastic Beanstalk supports custom platforms that can be based on an Amazon Machine Image (AMI) that you create from one of the supported operating systems, Ubuntu, RHEL, or Amazon Linux (see the flavor entry in Platform.yaml File Format for the exact version numbers) and can include further customizations. Create your own Elastic Beanstalk platform with Packer, which is an open-source tool for creating machine images for many platforms, including AMIs for use with Amazon EC2. An Elastic Beanstalk platform comprises an AMI configured to run a set of software that supports an application, and metadata that can include custom configuration options and default configuration option settings.

Note

When using the AWS management console to deploy environments to a custom platform, you must use the new version of the console.

You create a platform by providing Elastic Beanstalk with a Packer template, and the scripts and files that the template invokes to build an AMI. These components are packaged with a platform definition file, which specifies the template and metadata, into a ZIP archive called a platform definition archive.

When you create a custom platform, you launch a single instance environment without an EIP that runs Packer, which launches another instance to build an image. You can reuse this environment for multiple platforms and multiple versions of each platform.

Note

Custom platforms are region-specific. If you use Elastic Beanstalk in multiple regions, you must create your platforms separately in each region.

In certain circumstances, instances launched by Packer are not cleaned up and have to be manually terminated. To learn how to manually clean up these instances, see Packer Instance Cleanup.

Users in your account can use your custom platforms by specifying a platform ARN during environment creation. These ARNs are returned by the eb platform create command that you used to create the custom platform.

Each time you build your custom platform, Elastic Beanstalk creates a new platform version. Users can specify a platform by name to get only the latest version of the platform, or include a version number to get a specific version.

For example, to deploy the latest version of the custom platform with the ARN MyCustomPlatformARN, which could be version 3.0, your EB CLI command line would look like:

eb deploy -p MyCustomPlatformARN

To deploy version 2.1 your EB CLI command line would look like:

eb deploy -p MyCustomPlatformARN --version 2.1

Topics

Creating a Custom Platform
Using a Sample Custom Platform
Platform Definition Archive Contents
Platform Hooks
Platform Scripts
Packer Instance Cleanup
Platform.yaml File Format

Creating a Custom Platform

To create a custom platform, the root of your application must include a platform.yaml file, which defines the type of builder used to create the custom platform. The format of this file is described in the Platform.yaml File Format topic. As an alternative to creating your custom platform from scratch, you can use one of the sample custom platforms.

Using a Sample Custom Platform

One alternative to rolling your own custom platform is to use one of the platform definition archive samples to bootstrap your custom platform.

Note

Do not use a sample custom platform in production. The goal of the samples is to illustrate some of the functionality available for a custom platform, but they have not been hardened for production use.

NodePlatform_Ubuntu.zip: This custom platform is based on Ubuntu 16.04 and supports Node.js 4.4.4. We'll use this custom platform for the examples in this section.
NodePlatform_RHEL.zip: This custom platform is based on RHEL 7.2 and supports Node.js 4.4.4.
NodePlatform_AmazonLinux.zip: This custom platform is based on Amazon Linux 2016.09.1 and supports Node.js 4.4.4.
TomcatPlatform_Ubuntu.zip: This custom platform is based on Ubuntu 16.04 and supports Tomcat 7/Java 8.
CustomPlatform_NodeSampleApp.zip: A Node.js sample that uses express and ejs to display a static web page
CustomPlatform_TomcatSampleApp.zip: A Tomcat sample that displays a static web page when deployed

Download the sample platform definition archive: NodePlatform_Ubuntu.zip. This file contains a platform definition file, Packer template, scripts that Packer runs during image creation, and scripts and configuration files that Packer copies onto the builder instance during platform creation.

Example NodePlatform_Ubuntu.zip

|-- builder                 Contains files used by Packer to create the custom platform
|-- custom_platform.json    Packer template
|-- platform.yaml           Platform definition file
|-- ReadMe.txt              Briefly describes the sample

The platform definition file, platform.yaml, tells Elastic Beanstalk the name of the Packer template, custom_platform.json.

version: "1.0"

provisioner:
  type: packer
  template: custom_platform.json
  flavor: ubuntu1604

The Packer template tells Packer how to build the AMIs for the platform, using an Ubuntu AMI as a base for the platform image for HVM instance types. The provisioners section tells Packer to copy all files in the builder folder within the archive to the instance, and to run the builder.sh script on the instance. When the scripts complete, Packer creates an image from the modified instance.

Elastic Beanstalk creates three environment variables that can be used to tag AMIs in Packer:

AWS_EB_PLATFORM_ARN: The ARN of the custom platform.
AWS_EB_PLATFORM_NAME: The name of the custom platform.
AWS_EB_PLATFORM_VERSION: The version of the custom platform.

The sample custom_platform.json file uses these values to define the following values that it uses in the scripts:

platform_name, which is set by platform.yaml
platform_version, which is set by platform.yaml
platform_arn, which is set by the main build script, builder.sh, which is shown at the end of the sample custom_platform.json file.

Example custom_platform.json

{
  "variables": {
    "platform_name": "{{env `AWS_EB_PLATFORM_NAME`}}",
    "platform_version": "{{env `AWS_EB_PLATFORM_VERSION`}}",
    "platform_arn": "{{env `AWS_EB_PLATFORM_ARN`}}"
  },
  ...,
  "provisioners": [
    {...},
    {
      "type": "shell",
      "execute_command": "chmod +x {{ .Path }}; {{ .Vars }} sudo {{ .Path }}",
      "scripts": [
        "builder/builder.sh"
      ]
    }
  ]
}

The scripts and other files that you include in your platform definition archive will vary greatly depending on the modifications that you want to make to the instance. The sample platform includes the following scripts:

00-sync-apt.sh – Commented out: apt -y update.
01-install-nginx.sh – Installs nginx.
02-setup-platform.sh – Installs wget, tree, and git. Copies hooks and logging configurations to the instance, and creates the following directories:
- /etc/SampleNodePlatform – Where the container configuration file is uploaded during deployment.
- /opt/elasticbeanstalk/deploy/appsource/ – Where the 00-unzip.sh script uploads application source code during deployment (see the Platform Scripts section for information about this script).
- /var/app/staging/ – Where application source code is processed during deployment.
- /var/app/current/ – Where application source code runs after processing.
- /var/log/nginx/healthd/ – Where the enhanced health agent writes logs.
- /var/nodejs – Where the Node.js files are uploaded during deployment.

Use the EB CLI to create your first custom platform with the sample platform definition archive.

To create a custom platform

Install the EB CLI.
Create a directory in which you will extract the sample custom platform.
```
~$ mkdir ~/custom-platform
```

Extract NodePlatform_Ubuntu.zip to the directory.

~$ cd ~/custom-platform
~/custom-platform$ unzip ~/NodePlatform_Ubuntu.zip

Run eb platform init and follow the prompts to initialize a platform repository.

Note

You can shorten eb platform to ebp.
```
~/custom-platform$ ebp init
```
This command also creates the directory .elasticbeanstalk in the current directory and adds the configuration file config.yml to the directory. Don't change or delete this file, because Elastic Beanstalk relies on it when creating the custom platform.

By default, ebp init uses the name of the current folder as the name of the custom platform, which would be custom-platform in this example.
Run eb platform create to launch a Packer environment and get the ARN of the custom platform. You'll need this value later when you create an environment from the custom platform.
```
~/custom-platform$ ebp create
...
```
By default, Elastic Beanstalk creates the instance profile aws-elasticbeanstalk-custom-platform-ec2-role for custom platforms. If, instead, you want to use an existing instance profile, add the option -ip INSTANCE_PROFILE to the eb platform create command.

Note

Packer will fail to create a custom platform if you use the Elastic Beanstalk default instance profile aws-elasticbeanstalk-ec2-role.

The EB CLI shows event output of the Packer environment until the build is complete. You can exit the event view by pressing Ctrl-C.
You can check the logs for errors using the eb platform logs command.
```
~/custom-platform$ ebp logs
...
```
You can check on the process later with eb platform events.
```
~/custom-platform$ ebp events
...
```
Check the status of your platform with eb platform status.
```
~/custom-platform$ ebp status
...
```

When the operation completes, you have a platform that you can use to launch an Elastic Beanstalk environment.

You can use the custom platform when creating a new environment from the console. Learn more at The Create New Environment Wizard.

To launch an environment on your custom platform

Create a new directory for your application.

~$ mkdir custom-platform-app
~$ cd ~/custom-platform-app

Initialize an application repository.
```
~/custom-platform-app$ eb init
...
```
Download the sample application NodeSampleApp.zip.

Unzip the sample application.

~/custom-platform-app$ unzip ~/NodeSampleApp.zip

Run eb create -p CUSTOM-PLATFORM-ARN, where CUSTOM-PLATFORM-ARN is the ARN returned by an eb platform create command, to launch an environment running your custom platform.
```
~/custom-platform-app$ eb create -p CUSTOM-PLATFORM-ARN
...
```

Platform Definition Archive Contents

A platform definition archive is the platform equivalent of an application source bundle. The platform definition archive is a ZIP file that contains a platform definition file, a Packer template, and the scripts and files used by the Packer template to create your platform.

Note

When you use the EB CLI to create a custom platform, the EB CLI creates a platform definition archive from the files and folders in your platform repository, so you don't need to create the archive manually.

The platform definition file is a YAML-formatted file that must be named platform.yaml and be in the root of your platform definition archive. See Creating a Custom Platform for a list of required and optional keys supported in a platform definition file.

You don't need to name the Packer template in a specific way, but the name of the file must match the provisioner template specified in the platform definition file. See the official Packer documentation for instructions on creating Packer templates.

The other files in your platform definition archive are scripts and files used by the template to customize an instance before creating an AMI.

Platform Hooks

Elastic Beanstalk uses a standardized directory structure for hooks, which are scripts that are run during lifecycle events and in response to management operations: when instances in your environment are launched, or when a user initiates a deployment or uses the restart application server feature.

Hooks are organized into the following folders:

appdeploy — Scripts run during an application deployment. Elastic Beanstalk performs an application deployment when new instances are launched and when a client initiates a new version deployment.
configdeploy — Scripts run when a client performs a configuration update that affects the software configuration on-instance, for example, by setting environment properties or enabling log rotation to Amazon S3.
restartappserver — Scripts run when a client performs a restart app server operation.
preinit — Scripts run during instance bootstrapping.
postinit — Scripts run after instance bootstrapping.

The appdeploy, configdeploy, and restartappserver folders contain pre, enact, and post subfolders. In each phase of an operation, all scripts in the pre folder are run in alphabetical order, then the enact folder, then the post folder.

When an instance is launched, Elastic Beanstalk runs preinit, postinit, and appdeploy. On subsequent deployments to running instances, Elastic Beanstalk runs appdeploy hooks. configdeploy hooks are run when a user updates instance software configuration settings. restartappserver hooks are run only when the user initiates an application server restart.

When your scripts encounter errors, they can exit with a non-zero status and write to stderr to fail the operation. The message that you write to stderr will appear in the event that is output when the operation fails. Elastic Beanstalk also captures this information in the log file /var/log/eb-activity.log If you don't want to fail the operation, return 0. Messages that you write to stderr or stdout appear in the deployment logs, but won't appear in the event stream unless the operation fails.

Platform Scripts

Elastic Beanstalk installs the shell script get-config that you can use to get environment variables and other information in hooks that run on-instance in environments launched with your custom platform.

This tool is available at /opt/elasticbeanstalk/bin/get-config and can be used in the following ways:

get-config optionsettings – Returns a JSON object listing the configuration options set on the environment, organized by namespace.

$ /opt/elasticbeanstalk/bin/get-config optionsettings
{"aws:elasticbeanstalk:container:php:phpini":{"memory_limit":"256M","max_execution_time":"60","display_errors":"Off","composer_options":"","allow_url_fopen":"On","zlib_output_compression":"Off","document_root":""},"aws:elasticbeanstalk:hostmanager":{"LogPublicationControl":"false"},"aws:elasticbeanstalk:application:environment":{"TESTPROPERTY":"testvalue"}}

get-config environment – Returns a JSON object containing a list of environment properties, including both user-configured properties and those provided by Elastic Beanstalk.
```
$ /opt/elasticbeanstalk/bin/get-config environment
{"TESTPROPERTY":"testvalue","RDS_PORT":"3306","RDS_HOSTNAME":"anj9aw1b0tbj6b.cijbpanmxz5u.us-west-2.rds.amazonaws.com","RDS_USERNAME":"testusername","RDS_DB_NAME":"ebdb","RDS_PASSWORD":"testpassword1923851"}
```
For example, Elastic Beanstalk provides environment properties for connecting to an integrated RDS DB instance (RDS_HOSTNAME, etc.). These properties appear in the output of get-config environment but not in the output of get-config optionsettings, because they are not set by the user.

You can test the previous commands by using SSH to connect to an instance in an Elastic Beanstalk environment running a Linux-based platform.

See the following files in the sample platform definition archive for an example of get-config usage:

builder/platform-uploads/opt/elasticbeanstalk/hooks/configdeploy/enact/02-gen-envvars.sh – Gets environment properties.
builder/platform-uploads/opt/SampleNodePlatform/bin/createPM2ProcessFile.js – Parses the output.

Elastic Beanstalk installs the shell script download-source-bundle that you can use to download your application source code during the deployment of your custom platform. This tool is available at /opt/elasticbeanstalk/bin/download-source-bundle. See the sample script 00-unzip.sh, which is in the appdeploy/pre folder, for an example of how to use download-source-bundle to download application source code to the /opt/elasticbeanstalk/deploy/appsource folder during deployment.

Packer Instance Cleanup

In certain circumstances, such as killing the Packer builder process before it has finished, instances launched by Packer are not cleaned up. These instances are not part of the Elastic Beanstalk environment and can only be viewed and terminated using the Amazon EC2 service.

To manually clean up these instances

Open the https://console.aws.amazon.com/ec2/
Make sure you are in the same region in which you created the instance with Packer.
Under Resources select N Running Instances, where N indicates the number of running instances.
Click in the query text box.
Select the Name tag.
Type packer.

The query should look like: tag:Name: packer
Select any instances that match the query.
If the Instance State is running, select Actions, Instance State, Stop, then Actions, Instance State, Terminate.

Document Conventions

« Previous Next »