App Runner configuration file reference
Note
Configuration files are applicable only to services that are based on source code. You can't use configuration files with image-based services.
This topic is a comprehensive reference guide to the syntax and semantics of an AWS App Runner configuration file. For an overview of App Runner configuration files, see Setting App Runner service options using a configuration file.
The App Runner configuration file is a YAML file. Name it apprunner.yaml
, and place it in the source directory of your application’s repository.
Structure overview
The App Runner configuration file is a YAML file. Name it apprunner.yaml
, and place it in the source directory of your application’s repository.
The App Runner configuration file contains these main parts:
-
Top section – Contains top-level keys
-
Build section – Configures the build stage
-
Run section – Configures the runtime stage
Top section
The keys at the top of the file provide general information about the file and your service runtime. The following keys are available:
-
version
– Required. The App Runner configuration file version. Ideally, use the latest version.Syntax
version:
version
Example
version: 1.0
-
runtime
– Required. The name of the runtime that your application uses. To learn about available runtimes for the different programming platforms that App Runner offers, see App Runner service based on source code.Note
The naming convention of a managed runtime is
<language-name><major-version>
.Syntax
runtime:
runtime-name
Example
runtime: python3
Build section
The build section configures the build stage of the App Runner service deployment. You can specify build commands and environment variables. Build commands are required.
The section starts with the build:
key, and has the following subkeys:
-
commands
– Required. Specifies the commands that App Runner runs during various build phases. Includes the following subkeys:-
pre-build
– Optional. The commands that App Runner runs before the build. For example, install npm dependencies or test libraries. -
build
– Required. The commands that App Runner runs to build your application. For example, use pipenv. -
post-build
– Optional. The commands that App Runner runs after the build. For example, use Maven to package build artifacts into a JAR or WAR file, or run a test.
Syntax
build: commands: pre-build: -
command
-…
build: -command
-…
post-build: -command
-…
Example
build: commands: pre-build: - yum install openssl build: - pip install -r requirements.txt post-build: - python manage.py test
-
-
env
– Optional. Specifies custom environment variables for the build stage. Defined as name-value scalar mappings. You can refer to these variables by name in your build commands.Note
There are two distinct
env
entries in two different locations in this configuration file. One set is in the Build section and the other in the Run section.-
The
env
set in the Build section can be referenced by thepre-build
,build
,post-build
, andpre-run
commands during the build process.Important - Note that the
pre-run
commands are located in the Run section of this file, even though they can only access the environment variables that are defined in the Build section. -
The
env
set in the Run section can be referenced by therun
command in the runtime environment.
Syntax
build: env: - name:
name1
value:value1
- name:name2
value:value2
-…
Example
build: env: - name: DJANGO_SETTINGS_MODULE value: "django_apprunner.settings" - name: MY_VAR_EXAMPLE value: "example"
-
Run section
The run section configures the container running stage of the App Runner application deployment. You can specify runtime version, pre-run commands (revised format only), start command, network port, and environment variables.
The section starts with the run:
key, and has the following subkeys:
-
runtime-version
– Optional. Specifies a runtime version that you want to lock for your App Runner service.By default, only the major version is locked. App Runner uses the latest minor and patch versions that are available for the runtime on every deployment or service update. If you specify major and minor versions, both become locked, and App Runner updates only patch versions. If you specify major, minor, and patch versions, your service is locked on a specific runtime version and App Runner never updates it.
Syntax
run: runtime-version:
major[.minor[.patch]]
Note
The runtimes of some platforms have different version components. See specific platform topics for details.
Example
runtime: python3 run: runtime-version: 3.7
-
pre-run
– Optional. Revised build usage only. Specifies the commands that App Runner runs after copying your application from the build image to the run image. You can enter commands here to the modify the run image outside the/app
directory. For example, if you need to install additional global dependencies that reside outside of the/app
directory, enter the required commands in this sub-section to do so. For more information about the App Runner build process, see Managed runtime versions and the App Runner build.Note
-
Important – Even though the
pre-run
commands are listed in the Run section, they can only reference the environment variables defined in the Build section of this configuration file. They cannot reference the environment variables defined in this Run section. -
The
pre-run
parameter is only supported by the revised App Runner build. Do not insert this parameter in your configuration file if your application uses runtime versions that are supported by the original App Runner build. For more information, see Managed runtime versions and the App Runner build.
Syntax
run: pre-run: -
command
-…
-
-
command
– Required. The command that App Runner uses to run your application after it completes the application build.Syntax
run: command:
command
-
network
– Optional. Specifies the port that your application listens to. It includes the following:-
port
– Optional. If specified, this is the port number that your application listens to. The default is8080
. -
env
– Optional. If specified, App Runner passes the port number to the container in this environment variable, in addition to (not instead of) passing the same port number in the default environment variable,PORT
. In other words, if you specifyenv
, App Runner passes the port number in two environment variables.
Syntax
run: network: port:
port-number
env:env-variable-name
Example
run: network: port: 8000 env: MY_APP_PORT
-
-
env
– Optional. Definition of custom environment variables for the run stage. Defined as name-value scalar mappings. You can refer to these variables by name in your runtime environment.Note
There are two distinct
env
entries in two different locations in this configuration file. One set is in the Build section and the other in the Run section.-
The
env
set in the Build section can be referenced by thepre-build
,build
,post-build
, andpre-run
commands during the build process.Important - Note that the
pre-run
commands are located in the Run section of this file, even though they can only access the environment variables that are defined in the Build section. -
The
env
set in the Run section can be referenced by therun
command in the runtime environment.
Syntax
run: env: - name:
name1
value:value1
- name:name2
value:value2
secrets: - name:name1
value-from:arn:aws:secretsmanager:region:aws_account_id:secret:secret-id
- name:name2
value-from:arn:aws:ssm:region:aws_account_id:parameter/parameter-name
-…
Example
run: env: - name: MY_VAR_EXAMPLE value: "example" secrets: - name: my-secret value-from: "arn:aws:secretsmanager:us-east-1:123456789012:secret:testingstackAppRunnerConstr-kJFXde2ULKbT-S7t8xR:username::" - name: my-parameter value-from: "arn:aws:ssm:us-east-1:123456789012:parameter/parameter-name" - name: my-parameter-only-name value-from: "parameter-name"
-