Platform script tools

This topic describes tools that AWS Elastic Beanstalk provides for environments that use Amazon Linux platforms. The tools are located on the Amazon EC2 instances of the Elastic Beanstalk environments.

get-config

Use the get-config tool to retrieve environment variable values and other platform and instance information. The tool is available at /opt/elasticbeanstalk/bin/get-config.

get-config commands

Each get-config tool command returns a specific type of information. Use the following syntax to run the commands of any of the tools.

$ /opt/elasticbeanstalk/bin/get-config command [ options ]

The following example runs the environment command.

$ /opt/elasticbeanstalk/bin/get-config environment -k PORT

Depending on the command and options you choose, the tool returns an object (JSON or YAML) with key-value pairs or a single value.

You can test get-config by using SSH to connect to an EC2 instance in your Elastic Beanstalk environment.

The following sections describe the commands for the tools.

$ /opt/elasticbeanstalk/bin/get-config optionsettings
{"aws:elasticbeanstalk:application:environment":{"JDBC_CONNECTION_STRING":""},"aws:elasticbeanstalk:container:tomcat:jvmoptions":{"JVM Options":"","Xms":"256m","Xmx":"256m"},"aws:elasticbeanstalk:environment:proxy":{"ProxyServer":"nginx","StaticFiles":[""]},"aws:elasticbeanstalk:healthreporting:system":{"SystemType":"enhanced"},"aws:elasticbeanstalk:hostmanager":{"LogPublicationControl":"false"}}

$ /opt/elasticbeanstalk/bin/get-config optionsettings -n aws:elasticbeanstalk:container:php:phpini -o memory_limit
256M

$ /opt/elasticbeanstalk/bin/get-config environment
{"JDBC_CONNECTION_STRING":"","RDS_PORT":"3306","RDS_HOSTNAME":"anj9aw1b0tbj6b.cijbpanmxz5u.us-west-2.rds.amazonaws.com","RDS_USERNAME":"testusername","RDS_DB_NAME":"ebdb","RDS_PASSWORD":"testpassword1923851"}

$ /opt/elasticbeanstalk/bin/get-config environment -k TESTPROPERTY
testvalue

$ /opt/elasticbeanstalk/bin/get-config container
{"common_log_list":["/var/log/eb-engine.log","/var/log/eb-hooks.log"],"default_log_list":["/var/log/nginx/access.log","/var/log/nginx/error.log"],"environment_name":"myenv-1da84946","instance_port":"80","log_group_name_prefix":"/aws/elasticbeanstalk","proxy_server":"nginx","static_files":[""],"xray_enabled":"false"}

$ /opt/elasticbeanstalk/bin/get-config container -k environment_name
myenv-1da84946

$ /opt/elasticbeanstalk/bin/get-config addons
{"rds":{"Description":"RDS Environment variables","env":{"RDS_DB_NAME":"ebdb","RDS_HOSTNAME":"ea13k2wimu1dh8i.c18mnpu5rwvg.us-east-2.rds.amazonaws.com","RDS_PASSWORD":"password","RDS_PORT":"3306","RDS_USERNAME":"user"}}}

$ /opt/elasticbeanstalk/bin/get-config addons -a rds
{"Description":"RDS Environment variables","env":{"RDS_DB_NAME":"ebdb","RDS_HOSTNAME":"ea13k2wimu1dh8i.c18mnpu5rwvg.us-east-2.rds.amazonaws.com","RDS_PASSWORD":"password","RDS_PORT":"3306","RDS_USERNAME":"user"}}

$ /opt/elasticbeanstalk/bin/get-config addons -a rds -k RDS_DB_NAME
ebdb

$ /opt/elasticbeanstalk/bin/get-config platformconfig
{"GeneralConfig":{"AppUser":"webapp","AppDeployDir":"/var/app/current/","AppStagingDir":"/var/app/staging/","ProxyServer":"nginx","DefaultInstancePort":"80"},"PlatformSpecificConfig":{"ApplicationPort":"8080","JavaVersion":"11","TomcatVersion":"8.5"}}

$ /opt/elasticbeanstalk/bin/get-config platformconfig -k AppStagingDir
/var/app/staging/

get-config output options

Use the --output option to specify the output object format. Valid values are JSON (default) and YAML. This is a global option. You must specify it before the command name.

The following example returns configuration option values in the YAML format.

$ /opt/elasticbeanstalk/bin/get-config --output YAML optionsettings
aws:elasticbeanstalk:application:environment:
  JDBC_CONNECTION_STRING: ""
aws:elasticbeanstalk:container:tomcat:jvmoptions:
  JVM Options: ""
  Xms: 256m
  Xmx: 256m
aws:elasticbeanstalk:environment:proxy:
  ProxyServer: nginx
  StaticFiles:
        - ""
aws:elasticbeanstalk:healthreporting:system:
  SystemType: enhanced
aws:elasticbeanstalk:hostmanager:
  LogPublicationControl: "false"

pkg-repo

In some urgent circumstances, you might need to update your Amazon EC2 instances with an Amazon Linux 2 security patch that hasn't yet been released with the required Elastic Beanstalk platform versions. You can't perform a manual update on your Elastic Beanstalk environments by default. This is because the platform versions are locked to a specific version of the Amazon Linux 2 repository. This lock ensures that instances run supported and consistent software versions. For urgent cases, the pkg-repo tool allows a workaround to manually update yum packages on Amazon Linux 2 if you need to install it on an environment before it's released in a new Elastic Beanstalk platform version.

The pkg-repo tool on Amazon Linux 2 platforms provides the capability to unlock the yum package repositories. You can then manually perform a yum update for a security patch. Conversely, you can follow the update by using the tool to lock the yum package repositories to prevent further updates. The pkg-repo tool is available at the /opt/elasticbeanstalk/bin/pkg-repo directory of all the EC2 instances in your Elastic Beanstalk environments.

Changes using the pkg-repo tool are made only on the EC2 instance that the tool is used on. They don’t affect other instances or prevent future updates to the environment. The examples that are provided later in this topic explain how to apply the changes across all instances by calling the pkg-repo commands from scripts and configuration files.

If you plan to manually edit yum repository configuration files, run the pkg-repo tool first. The pkg-repo tool might not work as intended in an Amazon Linux 2 environment with manually edited yum repository configuration files. This is because the tool might not recognize the configuration changes.

For more information about the Amazon Linux package repository, see the Package repository topic in the Amazon EC2 User Guide for Linux Instances.

pkg-repo commands

Use the following syntax to run the pkg-repo tool commands.

$ /opt/elasticbeanstalk/bin/pkg-repo command [options]

The pkg-repo commands are the following:

The options apply to the commands as follows:

The following example runs the unlock command.

$ sudo /opt/elasticbeanstalk/bin/pkg-repo unlock
Amazon Linux 2 core package repo successfully unlocked
Amazon Linux 2 extras package repo successfully unlocked

The following example runs the lock command.

$ sudo /opt/elasticbeanstalk/bin/pkg-repo lock
Amazon Linux 2 core package repo successfully locked
Amazon Linux 2 extras package repo successfully locked

The following example runs the status command.

$ sudo /opt/elasticbeanstalk/bin/pkg-repo status
Amazon Linux 2 core package repo is currently UNLOCKED
Amazon Linux 2 extras package repo is currently UNLOCKED

The following example runs the help command for the lock command.

$ sudo /opt/elasticbeanstalk/bin/pkg-repo help lock

The following example runs the help command for the pkg-repo tool.

$ sudo /opt/elasticbeanstalk/bin/pkg-repo help

You can test pkg-repo by using SSH to connect to an instance in your Elastic Beanstalk environment. One SSH option is the EB CLI eb ssh command.

pkg-repo examples

The previous section provides command line examples for testing on an individual EC2 instance of an Elastic Beanstalk environment. This approach can be helpful for testing. However, it updates only one instance at a time, so it isn’t practical for applying changes to all of the instances in an environment.

A more pragmatic approach is to use platform hook scripts or an .ebextensions configuration file to apply the changes across all instances in a consistent manner.

The following example calls pkg-repo from a configuration file in the .ebextensions folder. Elastic Beanstalk runs the commands in the update_package.config file when you deploy your application source bundle.

.ebextensions
└── update_package.config

To receive the latest version of the docker package, this configuration specifies the docker package in the yum update command.

### update_package.config ###

commands:
  update_package:
    command: |
      /opt/elasticbeanstalk/bin/pkg-repo unlock
      yum update docker -y
      /opt/elasticbeanstalk/bin/pkg-repo lock
      yum clean all -y
      rm -rf /var/cache/yum

This configuration doesn't specify any packages in the yum update command. All available updates are applied as a result.

### update_package.config ###

commands:
  update_package:
    command: |
      /opt/elasticbeanstalk/bin/pkg-repo unlock
      yum update -y
      /opt/elasticbeanstalk/bin/pkg-repo lock
      yum clean all -y
      rm -rf /var/cache/yum

The following example calls pkg-repo from a bash script as a platform hook. Elastic Beanstalk runs the update_package.sh script file that's located in the prebuild subdirectory.

.platform
└── hooks
    └── prebuild
        └── update_package.sh

To receive the latest version of the docker package, this script specifies the docker package in the yum update command. If the package name is omitted, all the available updates are applied. The prior configuration file example demonstrates this.

### update_package.sh ###

#!/bin/bash

/opt/elasticbeanstalk/bin/pkg-repo unlock
yum update docker -y
/opt/elasticbeanstalk/bin/pkg-repo lock
yum clean all -y
rm -rf /var/cache/yum

download-source-bundle (Amazon Linux AMI only)

On Amazon Linux AMI platform branches (preceding Amazon Linux 2), Elastic Beanstalk provides an additional tool, which is download-source-bundle. Use this tool to download your application source code when deploying your platform. The tool is available at /opt/elasticbeanstalk/bin/download-source-bundle.

The example script 00-unzip.sh is located in the appdeploy/pre folder on environment instances. It demonstrates how to use download-source-bundle to download the application source code to the /opt/elasticbeanstalk/deploy/appsource folder during deployment.