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 root 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 root 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.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, 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
-
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.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"