Customizing software on Windows servers - AWS Elastic Beanstalk

Customizing software on Windows servers

You may want to customize and configure the software that your application depends on. These files could be either dependencies required by the application—for example, additional packages or services that need to be run. For general information on customizing and configuring your Elastic Beanstalk environments, see Configuring Elastic Beanstalk environments.

Note

YAML relies on consistent indentation. Match the indentation level when replacing content in an example configuration file and ensure that your text editor uses spaces, not tab characters, to indent.

Configuration files support the following keys that affect the Windows server on which your application runs.

Keys are processed in the order that they are listed here.

Note

Older (non-versioned) .NET platform versions do not process configuration files in the correct order. Learn more at Migrating across major versions of the Elastic Beanstalk Windows server platform.

Watch your environment's events while developing and testing configuration files. Elastic Beanstalk ignores a configuration file that contains validation errors, like an invalid key, and doesn't process any of the other keys in the same file. When this happens, Elastic Beanstalk adds a warning event to the event log.

Packages

Use the packages key to download and install prepackaged applications and components.

In Windows environments, Elastic Beanstalk supports downloading and installing MSI packages. (Linux environments support additional package managers. For details, see Packages on the Customizing Software on Linux Servers page.)

You can reference any external location, such as an Amazon Simple Storage Service (Amazon S3) object, as long as the URL is publicly accessible.

If you specify several msi: packages, their installation order isn't guaranteed.

Syntax

Specify a name of your choice as the package name, and a URL to an MSI file location as the value. You can specify multiple packages under the msi: key.

packages: msi: package name: package url ...

Examples

The following example specifies a URL to download mysql from https://dev.mysql.com/.

packages: msi: mysql: https://dev.mysql.com/get/Downloads/Connector-Net/mysql-connector-net-8.0.11.msi

The following example specifies an Amazon S3 object as the MSI file location.

packages: msi: mymsi: https://mybucket.s3.amazonaws.com/myobject.msi

Sources

Use the sources key to download an archive file from a public URL and unpack it in a target directory on the EC2 instance.

Syntax

sources: target directory: location of archive file

Supported formats

In Windows environments, Elastic Beanstalk supports the .zip format. (Linux environments support additional formats. For details, see Sources on the Customizing Software on Linux Servers page.)

You can reference any external location, such as an Amazon Simple Storage Service (Amazon S3) object, as long as the URL is publicly accessible.

Example

The following example downloads a public .zip file from an Amazon S3 bucket and unpacks it into c:/myproject/myapp.

sources: "c:/myproject/myapp": https://mybucket.s3.amazonaws.com/myobject.zip

Files

Use the files key to create files on the EC2 instance. The content can be either inline in the configuration file, or from a URL. The files are written to disk in lexicographic order. To download private files from Amazon S3, provide an instance profile for authorization.

Syntax

files: "target file location on disk": source: URL authentication: authentication name: "target file location on disk": content: | this is my content encoding: encoding format

Options

content

(Optional) A string.

source

(Optional) The URL from which the file is loaded. This option cannot be specified with the content key.

encoding

(Optional) The encoding format. This option is only used for a provided content key value. The default value is plain.

Valid values: plain | base64

authentication

(Optional) The name of a AWS CloudFormation authentication method to use. You can add authentication methods to the Auto Scaling group metadata with the Resources key.

Examples

The following example shows the two ways to provide file content: from a URL, or inline in the configuration file.

files: "c:\\targetdirectory\\targetfile.txt": source: http://foo.bar/myfile "c:/targetdirectory/targetfile.txt": content: | # this is my file # with content
Note

If you use a backslash (\) in your file path, you must precede that with another backslash (the escape character) as shown in the previous example.

The following example uses the Resources key to add an authentication method named S3Auth and uses it to download a private file from an Amazon S3 bucket:

files: "c:\\targetdirectory\\targetfile.zip": source: https://elasticbeanstalk-us-east-2-123456789012.s3.amazonaws.com/prefix/myfile.zip authentication: S3Auth Resources: AWSEBAutoScalingGroup: Metadata: AWS::CloudFormation::Authentication: S3Auth: type: "s3" buckets: ["elasticbeanstalk-us-east-2-123456789012"] roleName: "Fn::GetOptionSetting": Namespace: "aws:autoscaling:launchconfiguration" OptionName: "IamInstanceProfile" DefaultValue: "aws-elasticbeanstalk-ec2-role"

Commands

Use the commands key to execute commands on the EC2 instance. The commands are processed in alphabetical order by name, and they run before the application and web server are set up and the application version file is extracted.

The specified commands run as the Administrator user.

To troubleshoot issues with your commands, you can find their output in instance logs.

Syntax

commands: command name: command: command to run

Options

command

Either an array or a string specifying the command to run. If you use an array, you don't need to escape space characters or enclose command parameters in quotation marks.

cwd

(Optional) The working directory. By default, Elastic Beanstalk attempts to find the directory location of your project. If not found, it uses c:\Windows\System32 as the default.

env

(Optional) Sets environment variables for the command. This property overwrites, rather than appends, the existing environment.

ignoreErrors

(Optional) A Boolean value that determines if other commands should run if the command contained in the command key fails (returns a nonzero value). Set this value to true if you want to continue running commands even if the command fails. Set it to false if you want to stop running commands if the command fails. The default value is false.

test

(Optional) A command that must return the value true (exit code 0) in order for Elastic Beanstalk to process the command contained in the command key.

waitAfterCompletion

(Optional) Seconds to wait after the command completes before running the next command. If the system requires a reboot after the command completes, the system reboots after the specified number of seconds elapses. If the system reboots as a result of a command, Elastic Beanstalk will recover to the point after the command in the configuration file. The default value is 60 seconds. You can also specify forever, but the system must reboot before you can run another command.

Example

The following example saves the output of the set command to the specified file. If there is a subsequent command, Elastic Beanstalk runs that command immediately after this command completes. If this command requires a reboot, Elastic Beanstalk reboots the instance immediately after the command completes.

commands: test: command: set > c:\\myapp\\set.txt waitAfterCompletion: 0

Services

Use the services key to define which services should be started or stopped when the instance is launched. The services key also enables you to specify dependencies on sources, packages, and files so that if a restart is needed due to files being installed, Elastic Beanstalk takes care of the service restart.

Syntax

services: windows: name of service: files: - "file name" sources: - "directory" packages: name of package manager: "package name[: version]" commands: - "name of command"

Options

ensureRunning

(Optional) Set to true to ensure that the service is running after Elastic Beanstalk finishes.

Set to false to ensure that the service is not running after Elastic Beanstalk finishes.

Omit this key to make no changes to the service state.

enabled

(Optional) Set to true to ensure that the service is started automatically upon boot.

Set to false to ensure that the service is not started automatically upon boot.

Omit this key to make no changes to this property.

files

A list of files. If Elastic Beanstalk changes one directly via the files block, the service is restarted.

sources

A list of directories. If Elastic Beanstalk expands an archive into one of these directories, the service is restarted.

packages

A map of the package manager to a list of package names. If Elastic Beanstalk installs or updates one of these packages, the service is restarted.

commands

A list of command names. If Elastic Beanstalk runs the specified command, the service is restarted.

Example

services: windows: myservice: enabled: true ensureRunning: true

Container commands

Use the container_commands key to execute commands that affect your application source code. Container commands run after the application and web server have been set up and the application version archive has been extracted, but before the application version is deployed. Non-container commands and other customization operations are performed prior to the application source code being extracted.

Container commands are run from the staging directory, where your source code is extracted prior to being deployed to the application server. Any changes you make to your source code in the staging directory with a container command will be included when the source is deployed to its final location.

To troubleshoot issues with your container commands, you can find their output in instance logs.

Use the leader_only option to only run the command on a single instance, or configure a test to only run the command when a test command evaluates to true. Leader-only container commands are only executed during environment creation and deployments, while other commands and server customization operations are performed every time an instance is provisioned or updated. Leader-only container commands are not executed due to launch configuration changes, such as a change in the AMI Id or instance type.

Syntax

container_commands: name of container_command: command: command to run

Options

command

A string or array of strings to run.

env

(Optional) Set environment variables prior to running the command, overriding any existing value.

cwd

(Optional) The working directory. By default, this is the staging directory of the unzipped application.

leader_only

(Optional) Only run the command on a single instance chosen by Elastic Beanstalk. Leader-only container commands are run before other container commands. A command can be leader-only or have a test, but not both (leader_only takes precedence).

test

(Optional) Run a test command that must return the true in order to run the container command. A command can be leader-only or have a test, but not both (leader_only takes precedence).

ignoreErrors

(Optional) Do not fail deployments if the container command returns a value other than 0 (success). Set to true to enable.

waitAfterCompletion

(Optional) Seconds to wait after the command completes before running the next command. If the system requires a reboot after the command completes, the system reboots after the specified number of seconds elapses. If the system reboots as a result of a command, Elastic Beanstalk will recover to the point after the command in the configuration file. The default value is 60 seconds. You can also specify forever, but the system must reboot before you can run another command.

Example

The following example saves the output of the set command to the specified file. Elastic Beanstalk runs the command on one instance, and reboots the instance immediately after the command completes.

container_commands: foo: command: set > c:\\myapp\\set.txt leader_only: true waitAfterCompletion: 0