AWS App Runner

(1)

AWS App Runner

Developer Guide

(2)

AWS App Runner: Developer Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

What is AWS App Runner?

AWS App Runner is an AWS service that provides a fast, simple, and cost-eﬀective way to deploy from source code or a container image directly to a scalable and secure web application in the AWS Cloud. You don't need to learn new technologies, decide which compute service to use, or know how to provision and conﬁgure AWS resources.

App Runner connects directly to your code or image repository. It provides an automatic integration and delivery pipeline with fully managed operations, high performance, scalability, and security.

Who is App Runner for?

If you're a developer, you can use App Runner to simplify the process of deploying a new version of your code or image repository.

For operations teams, App Runner enables automatic deployments each time a commit is pushed to the code repository or a new container image version is pushed to the image repository.

Accessing App Runner

You can deﬁne and conﬁgure your App Runner service deployments using any one of the following interfaces:

• App Runner console – Provides a web interface for managing your App Runner services.

• App Runner API – Provides a RESTful API for performing App Runner actions. For more information, see AWS App Runner API Reference.

• AWS Command Line Interface (AWS CLI) – Provides commands for a broad set of AWS services, including Amazon VPC, and is supported on Windows, macOS, and Linux. For more information, see AWS Command Line Interface.

(7)

Pricing for App Runner

• AWS SDKs – Provides language-speciﬁc APIs and takes care of many of the connection details, such as calculating signatures, handling request retries, and error handling. For more information, see AWS SDKs.

Pricing for App Runner

App Runner provides a cost-eﬀective way to run your application. You only pay for resources that your App Runner service consumes. Your service scales down to fewer compute instances when request traﬃc is lower. You have control over scalability settings: the lowest and highest number of provisioned instances, and the highest load an instance handles.

For more information about App Runner automatic scaling, see the section called “Auto scaling” (p. 63).

For pricing information, see AWS App Runner pricing.

What's next

Learn how to get started with App Runner in the following topics:

• Setting up (p. 3) – Complete the prerequisite steps for using App Runner.

• Getting started (p. 6) – Deploy your ﬁrst application to App Runner.

(8)

Create an AWS account

Setting up for App Runner

If you're a new AWS customer, complete the setup prerequisites that are listed on this page before you start using AWS App Runner.

For these setup procedures, you use the AWS Identity and Access Management (IAM) service. For complete information about IAM, see the following reference materials:

• AWS Identity and Access Management (IAM)

• IAM User Guide

Create an AWS account

When you sign up with AWS, you get an account number with access to all of the services that AWS oﬀers, including AWS App Runner.

If you already have an AWS account, skip to the next prerequisite.

If you do not have an AWS account, complete the following steps to create one.

To sign up for an AWS account

1. Open https://portal.aws.amazon.com/billing/signup.

2. Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call and entering a veriﬁcation code on the phone keypad.

Create an IAM user

To access an AWS service, you provide credentials. These credentials determine authentication (who you are) and authorization (which permissions you have to perform actions on AWS resources).

When you ﬁrst create an Amazon Web Services (AWS) account, you begin with a single sign-in identity.

That identity has complete access to all AWS services and resources in the account. This identity is called the AWS account root user. When you sign in, enter the email address and password that you used to create the account.

Important

We strongly recommend that you do not use the root user for your everyday tasks, even the administrative ones. Instead, adhere to the best practice of using the root user only to create your ﬁrst IAM user. Then securely lock away the root user credentials and use them to perform only a few account and service management tasks. To view the tasks that require you to sign in as the root user, see Tasks that require root user credentials.

For more information about the root user and IAM user credentials, see AWS account root user credentials and IAM user credentials in the AWS General Reference.

To create an administrator user for yourself and add the user to an administrators group (console)

1. Sign in to the IAM console as the account owner by choosing Root user and entering your AWS account email address. On the next page, enter your password.

(9)

Create an access key for your IAM user

NoteWe strongly recommend that you adhere to the best practice of using the Administrator IAM user that follows and securely lock away the root user credentials. Sign in as the root user only to perform a few account and service management tasks.

2. In the navigation pane, choose Users and then choose Add user.

3. For User name, enter Administrator.

4. Select the check box next to AWS Management Console access. Then select Custom password, and then enter your new password in the text box.

5. (Optional) By default, AWS requires the new user to create a new password when ﬁrst signing in. You can clear the check box next to User must create a new password at next sign-in to allow the new user to reset their password after they sign in.

6. Choose Next: Permissions.

7. Under Set permissions, choose Add user to group.

8. Choose Create group.

9. In the Create group dialog box, for Group name enter Administrators.

10. Choose Filter policies, and then select AWS managed - job function to ﬁlter the table contents.

11. In the policy list, select the check box for AdministratorAccess. Then choose Create group.

Note

You must activate IAM user and role access to Billing before you can use the

AdministratorAccess permissions to access the AWS Billing and Cost Management console. To do this, follow the instructions in step 1 of the tutorial about delegating access to the billing console.

12. Back in the list of groups, select the check box for your new group. Choose Refresh if necessary to see the group in the list.

13. Choose Next: Tags.

14. (Optional) Add metadata to the user by attaching tags as key-value pairs. For more information about using tags in IAM, see Tagging IAM entities in the IAM User Guide.

15. Choose Next: Review to see the list of group memberships to be added to the new user. When you are ready to proceed, choose Create user.

You can use this same process to create more groups and users and to give your users access to your AWS account resources. To learn about using policies that restrict user permissions to speciﬁc AWS resources, see Access management and Example policies.

Important

Protect your AWS account. Never send or share your credentials with anyone outside of your organization. No one who legitimately represents Amazon will ever ask you for your credentials.

After you've created your IAM user, use its credentials to sign in to the AWS Management Console. For more information, see How IAM users sign in to your AWS account in the IAM User Guide.

Create an access key for your IAM user

Access keys consist of an access key ID and secret access key, which are used to sign programmatic requests that you make to AWS. If you don't have access keys, you can create them from the AWS Management Console. As a best practice, do not use the AWS account root user access keys for any task where it's not required. Instead, create a new administrator IAM user with access keys for yourself.

The only time that you can view or download the secret access key is when you create the keys. You cannot recover them later. However, you can create new access keys at any time. You must also have

(10)

What's next

permissions to perform the required IAM actions. For more information, see Permissions required to access IAM resources in the IAM User Guide.

To create access keys for an IAM user

1. Sign in to the AWS Management Console and open the IAM console at https://

console.aws.amazon.com/iam/.

2. In the navigation pane, choose Users.

3. Choose the name of the user whose access keys you want to create, and then choose the Security credentials tab.

4. In the Access keys section, choose Create access key.

5. To view the new access key pair, choose Show. You will not have access to the secret access key again after this dialog box closes. Your credentials will look something like this:

• Access key ID: AKIAIOSFODNN7EXAMPLE

• Secret access key: wJalrXUtnFEMI/K7MDENG/bPxRﬁCYEXAMPLEKEY

6. To download the key pair, choose Download .csv ﬁle. Store the keys in a secure location. You will not have access to the secret access key again after this dialog box closes.

Keep the keys conﬁdential in order to protect your AWS account and never email them. Do not share them outside your organization, even if an inquiry appears to come from AWS or Amazon.com. No one who legitimately represents Amazon will ever ask you for your secret key.

7. After you download the .csv ﬁle, choose Close. When you create an access key, the key pair is active by default, and you can use the pair right away.

Related topics

• What is IAM? in the IAM User Guide

• AWS security credentials in AWS General Reference

What's next

You completed the prerequisite steps. To deploy your ﬁrst application to App Runner, see Getting started (p. 6).

(11)

Prerequisites

Getting started with App Runner

AWS App Runner is an AWS service that provides a fast, simple, and cost-eﬀective way to turn an existing container image or source code directly into a running web service in the AWS Cloud.

This tutorial covers how you can use AWS App Runner to deploy your application to an App Runner service. It walks through conﬁguring the source code and deployment, the service build, and the service runtime. It also shows how to deploy a code version, make a conﬁguration change, and view logs.

Last, the tutorial shows how to clean up the resources that you created while following the tutorial's procedures.

Topics

• Prerequisites (p. 6)

• Step 1: Create an App Runner service (p. 7)

• Step 2: Change your service code (p. 12)

• Step 3: Make a conﬁguration change (p. 13)

• Step 4: View logs for your service (p. 14)

• Step 5: Clean up (p. 16)

• What's next (p. 17)

Prerequisites

Before you start the tutorial, be sure to take the following actions:

1. Complete the setup steps in Setting up (p. 3).

2. Create a GitHub account, if you don't already have one. If you're new to GitHub, see Getting started with GitHub in the GitHub Docs.

3. Create a repository in your GitHub account. This tutorial uses the repository name python-hello.

Create ﬁles in the root directory of the repository, with the names and content speciﬁed in the following examples.

Files for the python-hello example repository

Example requirements.txt

pyramid==2.0

Example server.py

from wsgiref.simple_server import make_server from pyramid.config import Configurator from pyramid.response import Response import os

def hello_world(request):

name = os.environ.get('NAME') if name == None or len(name) == 0:

name = "world"

message = "Hello, " + name + "!\n"

(12)

Step 1: Create an App Runner service

return Response(message) if __name__ == '__main__':

port = int(os.environ.get("PORT")) with Configurator() as config:

config.add_route('hello', '/')

config.add_view(hello_world, route_name='hello') app = config.make_wsgi_app()

server = make_server('0.0.0.0', port, app) server.serve_forever()

Step 1: Create an App Runner service

In this step, you create an App Runner service based on the example source code repository that you created on GitHub as part of the section called “Prerequisites” (p. 6). The example contains a simple Python website. These are the main steps you take to create a service:

1. Conﬁgure your source code.

2. Conﬁgure source deployment.

3. Conﬁgure application build.

4. Conﬁgure your service.

5. Review and conﬁrm.

The following diagram outlines the steps for creating an App Runner service:

To create an App Runner service based on a source code repository 1. Conﬁgure your source code.

a. Open the App Runner console, and in the Regions list, select your AWS Region.

b. If the AWS account doesn't have any App Runner services yet, the console home page is displayed. Choose Create an App Runner service.

(13)

If the AWS account has existing services, the Services page with a list of your services is displayed. Choose Create service.

c. On the Source and deployment page, in the Source section, for Repository type, choose Source code repository.

d. Under Connect to GitHub choose Add new, and then, if prompted, provide your GitHub credentials.

NoteThe following steps to install the AWS Connector for GitHub to your GitHub account are one-time steps. You can reuse the connection for creating multiple App Runner services based on repositories in this account. When you have an existing connection, choose it and skip to repository selection.

e. In the Install AWS Connector for GitHub dialog box, if prompted, choose your GitHub account name.

f. If prompted to authorize the AWS Connector for GitHub, choose Authorize AWS Connections.

g. Choose Install.

Your account name appears as the selected GitHub account/organization. You can now choose a repository in your account.

h. For Repository, choose the example repository you created, python-hello. For Branch, choose the default branch name of your repository (for example, main).

2. Conﬁgure your deployments: In the Deployment settings section, choose Automatic, and then choose Next.

NoteWith automatic deployment, each new commit to your repository automatically deploys a new version of your service.

(14)

3. Conﬁgure application build.

a. On the Configure build page, for Configuration file, choose Configure all settings here.

b. Provide the following build settings:

• Runtime – Choose Python 3.

• Build command – Enter pip install -r requirements.txt.

• Start command – Enter python server.py.

• Port – Enter 8080.

c. Choose Next.

NoteThe Python 3 runtime builds a Docker image using a base Python 3 image and your example Python code. It then launches a service that runs a container instance of this image.

(15)

4. Conﬁgure your service.

a. On the Conﬁgure service page, in the Service settings section, enter a service name.

b. Under Environment variables, add a single environment variable. For Key, enter NAME, and for Value, enter any name (for example, your ﬁrst name).

NoteThe example application reads the name you set in this environment variable and displays the name on its webpage.

c. Choose Next.

(16)

5. On the Review and create page, verify all the details you've entered, and then choose Create and deploy.

If the service is successfully created, the console shows the service dashboard, with a Service overview of the new service.

(17)

Step 2: Change your service code

6. Verify that your service is running.

a. On the service dashboard page, wait until the service Status is Running.

b. Choose the Default domain value—it's the URL to the website of your service.

A webpage displays: Hello, your name!

Step 2: Change your service code

In this step, you make a change to your source code repository. The App Runner CI/CD capability automatically builds and deploys the change to your service.

To make a change to your service code 1. Navigate to your example GitHub repository.

2. Choose the ﬁle name server.py to navigate to that ﬁle.

3. Choose Edit this ﬁle (the pencil icon).

4. In the expression assigned to the variable message, change the text Hello to Good morning.

(18)

Step 3: Make a conﬁguration change

5. Choose Commit changes.

The new commit starts to deploy. On the service dashboard page, the service Status changes to Operation in progress.

6. Wait for the deployment to end. On the service dashboard page, the service Status should change back to Running.

7. Verify that the deployment is successful: refresh the browser tab where the webpage of your service is displayed.

The page now displays the modiﬁed message: Good morning, your name!

Step 3: Make a conﬁguration change

In this step, you make a change to the NAME environment variable value, to demonstrate a service conﬁguration change.

To view logs for your service

1. Open the App Runner console, and in the Regions list, select your AWS Region.

2. In the navigation pane, choose Services, and then choose your App Runner service.

The console displays the service dashboard with a Service overview.

(19)

Step 4: View logs for your service

3. On the service dashboard page, choose the Conﬁguration tab.

The console displays your service conﬁguration settings in several sections.

4. In the Conﬁgure service section, choose Edit.

5. For the environment variable with the key NAME, change the value to a diﬀerent name.

6. Choose Apply changes.

App Runner starts the update process. On the service dashboard page, the service Status changes to Operation in progress.

7. Wait for the update to end. On the service dashboard page, the service Status should change back to Running.

8. Verify that the update is successful: refresh the browser tab where the webpage of your service is displayed.

The page now displays the modiﬁed name: Good morning, new name!

Step 4: View logs for your service

In this step, you use the App Runner console to view logs for your App Runner service. App Runner streams logs to Amazon CloudWatch Logs (CloudWatch Logs) and displays them on your service's dashboard. For information about App Runner logs, see the section called “Logs (CloudWatch Logs)” (p. 78).

To view logs for your service

1. Open the App Runner console, and in the Regions list, select your AWS Region.

2. In the navigation pane, choose Services, and then choose your App Runner service.

The console displays the service dashboard with a Service overview.

(20)

Step 4: View logs for your service

3. On the service dashboard page, choose the Logs tab.

The console displays a few types of logs in several sections:

• Event log – Activity in the lifecycle of your App Runner service. The console displays the latest events.

• Deployment logs – Source repository deployments to your App Runner service. The console displays a separate log stream for each deployment.

• Application logs – The output of the web application that's deployed to your App Runner service.

The console combines the output from all running instances into a single log stream.

(21)

Step 5: Clean up

4. To ﬁnd speciﬁc deployments, scope down the deployment log list by entering a search term. You can search for any value that appears in the table.

5. To view a log's content, choose View full log (event log) or the log stream name (deployment and application logs).

6. Choose Download to download a log. For a deployment log stream, select a log stream ﬁrst.

7. Choose View in CloudWatch to open the CloudWatch console and use its full capabilities to explore your App Runner service logs. For a deployment log stream, select a log stream ﬁrst.

Note

The CloudWatch console is particularly useful if you want to view application logs of speciﬁc instances instead of the combined application log.

Step 5: Clean up

You've now learned how to create an App Runner service, view logs, and make some changes. In this step, you delete the service to remove resources that you don't need anymore.

To delete your service

1. On the service dashboard page, choose Actions, and then choose Delete service.

2. In the conﬁrmation dialog, enter the requested text, and then choose Delete.

(22)

What's next

Result: The console navigates to the Services page. The service that you just deleted shows a status of DELETING. A short time later it disappears from the list.

Consider also deleting the GitHub connection that you created as part of this tutorial. For more information, see the section called “Connections” (p. 61).

What's next

Now that you've deployed your ﬁrst App Runner service, learn more in the following topics:

• Architecture and concepts (p. 18) – The architecture, main concepts, and AWS resources related to App Runner.

• Image-based service (p. 22) and Code-based service (p. 25) – The two types of application source that App Runner can deploy.

• Developing for App Runner (p. 39) – Things you should know when developing or migrating application code for deployment to App Runner.

• App Runner console (p. 41) – Manage and monitor your service using the App Runner console.

• Managing your service (p. 44) – Manage the lifecycle of your App Runner service.

• Logging and monitoring (p. 77) – Monitor your App Runner service by viewing metrics, reading logs, and tracking service action calls.

• App Runner configuration file (p. 92) – A configuration-based way to specify options for the build and runtime behavior of your App Runner service.

• App Runner API (p. 98) – Use the App Runner application programming interface (API) to create, read, update, and delete App Runner resources.

• Security (p. 102) – The diﬀerent ways that AWS and you ensure cloud security while you use App Runner and other services.

(23)

App Runner concepts

App Runner architecture and concepts

AWS App Runner takes your source code or source image from a repository, and creates and maintains a running web service for you in the AWS Cloud. Typically, you need to call just one App Runner action, CreateService, to create your service.

With a source image repository, you provide a ready-to-use container image that App Runner can deploy to run your web service. With a source code repository, you provide your code and instructions for building and running a web service, and you target a speciﬁc runtime environment. App Runner supports several programming platforms, each with one or more managed runtimes for platform major versions.

At this time, App Runner can retrieve your source code from a GitHub repository, or retrieve your source image from Amazon Elastic Container Registry (Amazon ECR) in your AWS account.

The following diagram shows an overview of the App Runner service architecture. In the diagram, there are two example services: one deploys source code from GitHub, and the other deploys a source image from Amazon ECR.

App Runner concepts

The following are key concepts related to your web service that's running in App Runner:

• App Runner service – An AWS resource that App Runner uses to deploy and manage your application based on its source code repository or container image. An App Runner service is a running

(24)

App Runner resources

version of your application. For more information about creating a service, see the section called

“Creation” (p. 44).

• Source type – The type of source repository that you provide for deploying your App Runner service:

source code (p. 25) or source image (p. 22).

• Repository provider – The repository service that contains your application source (for example, GitHub (p. 25) or Amazon ECR (p. 22)).

• App Runner connection – An AWS resource that lets App Runner access a repository provider account (for example, a GitHub account or organization). For more information about connections, see the section called “Connections” (p. 61).

• Runtime – A base image for deploying a source code repository. App Runner provides a variety of managed runtimes for diﬀerent programming platforms and versions. For more information, see Code- based service (p. 25).

• Deployment – An action that applies a version of your source repository (code or image) to an App Runner service. The ﬁrst deployment to the service occurs as part of service creation. Later deployments can occur in one of two ways:

• Automatic deployment – A CI/CD capability. You can conﬁgure an App Runner service to

automatically build (for source code) and deploy each version of your application as it appears in the repository. This can be a new commit in a source code repository or a new image version in a source image repository.

• Manual deployment – A deployment to your App Runner service that you explicitly start.

• Custom domain – A domain that you associate with your App Runner service. Users of your web application can use this domain to access your web service instead of the default App Runner subdomain. For more information, see the section called “Custom domain names” (p. 64).

• Maintenance – An activity that App Runner occasionally performs on the infrastructure that runs your App Runner service. When maintenance is in progress, service status temporarily changes to OPERATION_IN_PROGRESS (Operation in progress in the console) for a few minutes. Actions on your service (for example, deployment, conﬁguration update, pause/resume, or deletion) are blocked during this time. Try the action again a few minutes later, when the service status returns to RUNNING.

NoteIf your action fails, it doesn't mean that your App Runner service is down. Your application is active and keeps handling requests. It's unlikely for your service to experience any downtime.

In particular, App Runner migrates your service if it detects issues in the underlying hardware hosting the service. To prevent any service downtime, App Runner deploys your service to a new set of instances and shifts traﬃc to them (a blue-green deployment). You might occasionally see a slight temporary increase in charges.

App Runner resources

When you use App Runner, you create and manage a few types of resources in your AWS account. These resources are used to access your code and manage your services.

The following table provides an overview of these resources:

Resource name Description

Service Represents a running version of your application. Much of the rest of this guide describes service types, management, conﬁguration, and monitoring.

ARN: arn:aws:apprunner:region:account-id:service/service- name[/service-id]

(25)

App Runner resource quotas

Resource name Description

Connection Provides your App Runner services with access to private repositories stored with third-party providers. Exists as a separate resource for sharing across multiple services. For more information about connections, see the section called “Connections” (p. 61).

ARN: arn:aws:apprunner:region:account-

id:connection/connection-name[/connection-id]

AutoScalingConﬁguration Provides your App Runner services with settings that control the automatic scaling of your application. Exists as a separate resource for sharing across multiple services. For more information about automatic scaling, see the section called “Auto scaling” (p. 63).

ARN: arn:aws:apprunner:region:account-

id:autoscalingconfiguration/config-name[/config- revision[/config-id]]

VpcConnector Conﬁgures VPC settings for your App Runner services. Exists as a separate resource for sharing across multiple services. For more information about VPC functionality, see the section called “VPC access” (p. 74).

ARN: arn:aws:apprunner:region:account- id:vpcconnector/connector-name[/connector- revision[/connector-id]]

App Runner resource quotas

AWS imposes some quotas (also known as limits) on your account for AWS resource usage in each AWS Region. The following table lists quotas related to App Runner resources. Quotas are also listed in AWS App Runner endpoints and quotas in the AWS General Reference.

Resource quota Description Default

value Adjustable?

Services The maximum number of services that you can

create in your account for each AWS Region. 10 ✓ Yes Connections The maximum number of connections that you can

create in your account for each AWS Region. You can use a single connection in multiple services.

10 ✓ Yes

names The maximum number of unique names that you can have in auto scaling conﬁgurations that you create in your account for each AWS Region. You can use a single auto scaling conﬁguration in multiple services.

10 ✓ Yes

Auto scaling conﬁgurations

revisions per name

The maximum number of auto scaling conﬁguration revisions that you can create in your account for each AWS Region for each unique name. You can use a single auto scaling conﬁguration revision in multiple services.

10 ☓ No

VPC connectors The maximum number of VPC connectors that you

can create in your account for each AWS Region. 10 ✓ Yes

(26)

App Runner resource quotas

Resource quota Description Default

value Adjustable?

You can use a single VPC connector in multiple services.

Most quotas are adjustable, and you can request a quota increase for them. For more information, see Requesting a quota increase in the Service Quotas User Guide.

(27)

Image repository providers

App Runner service based on a source image

You can use AWS App Runner to create and manage services based on two fundamentally diﬀerent types of service source: source code and source image. Regardless of the source type, App Runner takes care of starting, running, scaling, and load balancing your service. You can use the CI/CD capability of App Runner to track changes to your source image or code. When App Runner discovers a change, it automatically builds (for source code) and deploys the new version to your App Runner service.

This chapter discusses services based on a source image. For information about services based on source code, see Code-based service (p. 25).

A source image is a public or private container image stored in an image repository. You point App Runner to an image, and it starts a service running a container based on this image. No build stage is necessary. Rather, you provide a ready-to-deploy image.

Image repository providers

App Runner supports the following image repository providers:

• Amazon Elastic Container Registry (Amazon ECR) – Stores images that are private to an AWS account.

• Amazon Elastic Container Registry Public (Amazon ECR Public) – Stores images that are publicly readable.

Provider use cases

• Using an image stored in Amazon ECR in your AWS account (p. 22)

• Using an image stored in Amazon ECR in a diﬀerent AWS account (p. 23)

• Using an image stored in Amazon ECR Public (p. 23)

Using an image stored in Amazon ECR in your AWS account

Amazon ECR stores images in repositories. There are private and public repositories. To deploy your image to an App Runner service from a private repository, App Runner needs permission to read your image from Amazon ECR. To give that permission to App Runner, you need to provide App Runner with an access role. This is an AWS Identity and Access Management (IAM) role that has the necessary Amazon ECR action permissions. When you use the App Runner console to create the service, you can choose an existing role in your account. Alternatively, you can use the IAM console to create a new custom role. Or, you can choose for the App Runner console to create a role for you based on managed policies.

When you use the App Runner API or the AWS CLI, you complete a two-step process. First, you use the IAM console to create an access role. You can use a managed policy that App Runner provides or

(28)

Using an image stored in Amazon ECR in a diﬀerent AWS account

enter your own custom permissions. Then, you provide the access role during service creation using the CreateService API action.

For information about App Runner service creation, see the section called “Creation” (p. 44).

Using an image stored in Amazon ECR in a diﬀerent AWS account

When you create an App Runner service, you can use an image stored in an Amazon ECR repository that belongs to an AWS account other than the one that your service is in. There are a few additional considerations to keep in mind when using a cross-account image, in addition to those listed in the previous section about a same-account image.

• The cross-account repository should have a policy attached to it. The repository policy provides your access role with permissions to read images in the repository. Use the following policy for this purpose.

Replace access-role-arn with the Amazon Resource Name (ARN) of your access role.

{ "Version": "2008-10-17", "Statement": [

{

"Effect": "Allow", "Principal": {

"AWS": "access-role-arn"

},

"Action": [

"ecr:BatchGetImage", "ecr:DescribeImages",

"ecr:GetDownloadUrlForLayer"

] } ] }

For information about attaching a repository policy to an Amazon ECR repository, see Setting a repository policy statement in the Amazon Elastic Container Registry User Guide.

• App Runner doesn't support automatic deployment for Amazon ECR images in a diﬀerent account than the one that your service is in.

Using an image stored in Amazon ECR Public

Amazon ECR Public stores publicly readable images. These are the main diﬀerences between Amazon ECR and Amazon ECR Public that you should be aware of in the context of App Runner services:

• Amazon ECR Public images are publicly readable. You don't need to provide an access role when you create a service based on an Amazon ECR Public image. The repository doesn't need any policy attached to it.

• App Runner doesn't support automatic (continuous) deployment for Amazon ECR Public images.

Launch a service directly from Amazon ECR Public

You can directly launch container images of compatible web applications that are hosted on the Amazon ECR Public Gallery as web services running on App Runner. When browsing the gallery, look for Launch with App Runner on the gallery page for an image. An image with this option is compatible with App

(29)

Image example

Runner. For more information about the gallery, see Using the Amazon ECR Public Gallery in the Amazon ECR Public user guide.

To launch a gallery image as an App Runner service

1. On the gallery page of an image, choose Launch with App Runner.

Result: The App Runner console opens in a new browser tab. The console displays the Create service wizard, with most of the required new service details pre-ﬁlled.

2. If you want to create your service in an AWS Region other than the one that the console is showing, choose the Region displayed on the console header. Then, select another Region.

3. For Port, enter the port number that the image application listens on. You can typically ﬁnd it on the gallery page for the image.

4. Optionally, change any other conﬁguration details.

5. Choose Next, review the settings, and then choose Create & deploy.

Image example

The App Runner team maintains the hello-app-runner example image in an Amazon ECR Public Gallery.

You can use this example to get started with creating an image-based App Runner service. For more information, see hello-app-runner.

(30)

Source code repository providers

App Runner service based on source code

You can use AWS App Runner to create and manage services based on two fundamentally diﬀerent types of service source: source code and source image. Regardless of the source type, App Runner takes care of starting, running, scaling, and load balancing your service. You can use the CI/CD capability of App Runner to track changes to your source image or code. When App Runner discovers a change, it automatically builds (for source code) and deploys the new version to your App Runner service.

This chapter discusses services based on source code. For information about services based on a source image, see Image-based service (p. 22).

Source code is application code that App Runner builds and deploys for you. You point App Runner to a source code repository and choose a suitable runtime that corresponds to a programming platform version. App Runner builds an image that's based on the base image of the runtime and your application code. It then starts a service that runs a container based on this image.

App Runner provides convenient platform-specific managed runtimes. Each one of these runtimes builds a container image from your source code, and adds language runtime dependencies into your image. You don't need to provide container configuration and build instructions such as a Dockerfile.

Subtopics of this chapter discuss the various platforms that App Runner supports— managed platforms that provide managed runtimes for diﬀerent programming environments and versions.

Topics

• Source code repository providers (p. 25)

• App Runner managed platforms (p. 26)

• Using the Python platform (p. 26)

• Using the Node.js platform (p. 29)

• Using the Java platform (p. 34)

Source code repository providers

App Runner deploys your source code by reading it from a source code repository. App Runner supports one source code repository provider: GitHub.

Deploying from GitHub

To deploy your source code to an App Runner service from a GitHub repository, App Runner establishes a connection to GitHub. If your repository is private (that is, it isn't publicly accessible on GitHub), you must provide App Runner with connection details. When you use the App Runner console to create a service (p. 44), you provide connection details as part of the service creation procedure.

When you use the App Runner API or the AWS CLI, a connection is a separate resource. First, you create the connection using the CreateConnection API action. Then, you provide the connection's ARN during service creation using the CreateService API action.

For more information about App Runner service creation, see the section called “Creation” (p. 44). For more information about App Runner connections, see the section called “Connections” (p. 61).

(31)

App Runner managed platforms

App Runner managed platforms provide managed runtimes for various programming environments.

Each managed runtime makes it easy to build and run containers based on a version of a programming language or runtime environment. When you use a managed runtime, App Runner starts with a managed runtime image. This image is based on the Amazon Linux Docker image and contains a language runtime package as well as some tools and popular dependency packages. App Runner uses this managed runtime image as a base image, and adds your application code to build a Docker image. It then deploys this image to run your web service in a container.

You specify a runtime for your App Runner service when you create a service (p. 44) using the App Runner console or the CreateService API. You can also specify a runtime as part of your source code.

Use the runtime keyword in a App Runner configuration file (p. 92) that you include in your code repository. The naming convention of a managed runtime is <language-name><major-version>. App Runner updates the runtime for your service to the latest version on every deployment or service update. If your application requires a specific version of a managed runtime, you can specify it using the runtime-version keyword in the App Runner configuration file (p. 92). You can lock to any level of version (for example, major or minor), and App Runner only makes lower-level updates to the runtime of your service.

Using the Python platform

The AWS App Runner Python platform provides managed runtimes. Each runtime makes it easy to build and run containers with web applications based on a Python version. When you use a Python runtime, App Runner starts with a managed Python runtime image. This image is based on the Amazon Linux Docker image and contains the runtime package for a version of Python and some tools and popular dependency packages. App Runner uses this managed runtime image as a base image, and adds your application code to build a Docker image. It then deploys this image to run your web service in a container.

Use the runtime keyword in a App Runner conﬁguration ﬁle (p. 92) that you include in your code repository. The naming convention of a managed runtime is <language-name><major-version>. For valid Python runtime names, see the section called “Release information” (p. 29).

App Runner updates the runtime for your service to the latest version on every deployment or service update. If your application requires a specific version of a managed runtime, you can specify it using the runtime-version keyword in the App Runner configuration file (p. 92). You can lock to any level of version (for example, major or minor), and App Runner only makes lower-level updates to the runtime of your service.

Version syntax for Python runtimes: major[.minor[.patch]]

For example: 3.8.5

The following examples demonstrate version locking:

• 3.8 – Lock the major and minor versions. App Runner updates only patch versions.

• 3.8.4 – Lock to a speciﬁc patch version. App Runner doesn't update your runtime version.

Topics

(32)

Python runtime conﬁguration

• Python runtime conﬁguration (p. 27)

• Python runtime examples (p. 27)

• Python runtime release information (p. 29)

Python runtime conﬁguration

When you choose a managed runtime, you must also conﬁgure, as a minimum, build and run commands.

You conﬁgure them while creating (p. 44) or updating (p. 57) your App Runner service. There are a few ways to do it:

• Using the App Runner console – Specify the commands in the Conﬁgure build section of the creation process or conﬁguration tab.

• Using the App Runner API – Call CreateService or UpdateService. Specify the commands using the BuildCommand and StartCommand members of the CodeConﬁgurationValues data type.

• Using a conﬁguration ﬁle (p. 92) – Specify one or more build commands in up to three build

phases, and a single run command that serves to start your application. There are additional optional conﬁguration settings.

Providing a configuration file is optional. When creating an App Runner service using the console or the API, you specify if App Runner gets your configuration settings directly during creation or from a configuration file.

Python runtime examples

The following examples show App Runner conﬁguration ﬁles for building and running a Python service.

The last example is the source code for a complete Python application that you can deploy to a Python runtime service.

Minimal Python conﬁguration ﬁle

This example shows a minimal conﬁguration ﬁle that you can use with a Python managed runtime.

For the assumptions that App Runner makes with a minimal conﬁguration ﬁle, see the section called

“Conﬁguration ﬁle examples” (p. 92).

Example apprunner.yaml

version: 1.0 runtime: python3 build:

commands:

build:

- pip install pipenv - pipenv install run:

command: python app.py

Extended Python conﬁguration ﬁle

This example shows the use of all conﬁguration keys with a Python managed runtime.

version: 1.0

(33)

Python runtime examples

runtime: python3 build:

commands:

pre-build:

- wget -c https://s3.amazonaws.com/DOC-EXAMPLE-BUCKET/test-lib.tar.gz -O - | tar -xz build:

- pip install pipenv - pipenv install post-build:

- python manage.py test env:

- name: DJANGO_SETTINGS_MODULE value: "django_apprunner.settings"

- name: MY_VAR_EXAMPLE value: "example"

run:

runtime-version: 3.7.7

command: pipenv run gunicorn django_apprunner.wsgi --log-file - network:

port: 8000

env: MY_APP_PORT env:

Complete Python application source

This example shows the source code for a complete Python application that you can deploy to a Python runtime service.

Example requirements.txt

pyramid==2.0

Example server.py

from wsgiref.simple_server import make_server from pyramid.config import Configurator from pyramid.response import Response import os

def hello_world(request):

name = os.environ.get('NAME') if name == None or len(name) == 0:

name = "world"

message = "Hello, " + name + "!\n"

return Response(message) if __name__ == '__main__':

port = int(os.environ.get("PORT")) with Configurator() as config:

config.add_route('hello', '/')

config.add_view(hello_world, route_name='hello') app = config.make_wsgi_app()

server = make_server('0.0.0.0', port, app) server.serve_forever()

version: 1.0 runtime: python3

(34)

Release information

build:

commands:

build:

- pip install -r requirements.txt run: command: python server.py

Python runtime release information

This topic lists the full details for the Python runtime versions that App Runner supports.

Python 3

Detail Description

Runtime name python3

Minor versions 3.7, 3.8

Included packages python, pip, setuptools, wheel, virtualenv

Using the Node.js platform

The AWS App Runner Node.js platform provides managed runtimes. Each runtime makes it easy to build and run containers with web applications based on a Node.js version. When you use a Node.js runtime, App Runner starts with a managed Node.js runtime image. This image is based on the Amazon Linux Docker image and contains the runtime package for a version of Node.js and some tools. App Runner uses this managed runtime image as a base image, and adds your application code to build a Docker image. It then deploys this image to run your web service in a container.

Use the runtime keyword in a App Runner conﬁguration ﬁle (p. 92) that you include in your code repository. The naming convention of a managed runtime is <language-name><major-version>. For valid Node.js runtime names, see the section called “Release information” (p. 33).

Version syntax for Node.js runtimes: major[.minor[.patch]]

For example: 12.22.6

• 12.22 – Lock the major and minor versions. App Runner updates only patch versions.

• 12.22.3 – Lock to a speciﬁc patch version. App Runner doesn't update your runtime version.

Topics

• Node.js runtime conﬁguration (p. 30)

(35)

Node.js runtime conﬁguration

• Node.js runtime examples (p. 31)

• Node.js runtime release information (p. 33)

Node.js runtime conﬁguration

With Node.js runtimes specifically, you can also configure the build and runtime using a JSON file named package.json in the root of your source repository. Using this file, you can configure the Node.js engine version, dependency packages, and various commands (command line applications). Package managers such as npm or yarn interpret this file as input for their commands.

For example:

• npm install installs packages deﬁned by the dependencies and devDependencies node in package.json.

• npm start or npm run start runs the command deﬁned by the scripts/start node in package.json.

The following is an example package.json ﬁle.

package.json

{ "name": "node-js-getting-started", "version": "0.3.0",

"description": "A sample Node.js app using Express 4", "engines": {

"node": "12.18.4"

},

"scripts": {

"start": "node index.js", "test": "node test.js"

}, "dependencies": {

"cool-ascii-faces": "^1.3.4", "ejs": "^2.5.6",

"express": "^4.15.2"

}, "devDependencies": { "got": "^11.3.0", "tape": "^4.7.0"

(36)

Node.js runtime examples

} }

For more information about package.json, see The package.json guide on the Node.js website.

Tips

• If your package.json file defines a start command, you can use it as a run command in your App Runner configuration file, as the following example shows.

Example package.json

{

"scripts": {

"start": "node index.js"

} }

apprunner.yaml

run: command: npm start

• When you run npm install in your development environment, npm creates the ﬁle package- lock.json. This ﬁle contains a snapshot of the package versions npm just installed.

Thereafter, when npm installs dependencies, it uses these exact versions. Similarly, yarn creates yarn.json. Commit these ﬁles to your source code repository to ensure that your application is installed with the versions of dependencies that you developed and tested it with.

• You can also use an App Runner configuration file to configure the Node.js version and start command. When you do this, these definitions override the ones in package.json. A conflict between the node version in package.json and the runtime-version value in the App Runner configuration file causes the App Runner build phase to fail.

Node.js runtime examples

The following examples show App Runner conﬁguration ﬁles for building and running a Node.js service.

Minimal Node.js conﬁguration ﬁle

This example shows a minimal conﬁguration ﬁle that you can use with a Node.js managed runtime.

version: 1.0 runtime: nodejs12 build:

commands:

build:

- npm install --production run:

command: node app.js

(37)

Node.js runtime examples

Extended Node.js conﬁguration ﬁle

This example shows the use of all the conﬁguration keys with a Node.js managed runtime.

commands:

pre-build:

- npm install --only=dev - node test.js

build:

- npm install --production post-build:

- node node_modules/ejs/postinstall.js env:

run:

runtime-version: 12.18.4 command: node app.js network:

port: 8000 env: APP_PORT env:

Node.js app with Grunt

This example shows how to configure a Node.js application that's developed with Grunt. Grunt is a command line JavaScript task runner. It runs repetitive tasks and manages process automation to reduce human error. Grunt and Grunt plugins are installed and managed using npm. You configure Grunt by including the Gruntfile.js file in the root of your source repository.

Example package.json

{ "scripts": {

"build": "grunt uglify", "start": "node app.js"

}, "devDependencies": { "grunt": "~0.4.5",

"grunt-contrib-jshint": "~0.10.0", "grunt-contrib-nodeunit": "~0.4.1", "grunt-contrib-uglify": "~0.5.0"

}, "dependencies": { "express": "^4.15.2"

}, }

Example Gruntﬁle.js

module.exports = function(grunt) { // Project configuration.

(38)

Release information

grunt.initConfig({

pkg: grunt.file.readJSON('package.json'), uglify: {

options: {

banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n' },

build: {

src: 'src/<%= pkg.name %>.js', dest: 'build/<%= pkg.name %>.min.js' }

} });

// Load the plugin that provides the "uglify" task.

grunt.loadNpmTasks('grunt-contrib-uglify');

// Default task(s).

grunt.registerTask('default', ['uglify']);

};

commands:

pre-build:

- npm install grunt grunt-cli - npm install --only=dev - npm run build

build:

- npm install --production run: runtime-version: 12.18.4 command: node app.js network:

port: 8000 env: APP_PORT

Node.js runtime release information

This topic lists the full details for the Node.js runtime versions that App Runner supports.

Node.js 14

Runtime name nodejs14

Minor versions latest

Included packages nodejs (including npm), yarn

Node.js 12

Runtime name nodejs12

(39)

Java platform

Minor versions latest

Included packages nodejs (including npm), yarn

Using the Java platform

The AWS App Runner Java platform provides managed runtimes. Each runtime makes it easy to build and run containers with web applications based on a Java version. When you use a Java runtime, App Runner starts with a managed Java runtime image. This image is based on the Amazon Linux Docker image and contains the runtime package for a version of Java and some tools. App Runner uses this managed runtime image as a base image, and adds your application code to build a Docker image. It then deploys this image to run your web service in a container.

Use the runtime keyword in a App Runner conﬁguration ﬁle (p. 92) that you include in your code repository. The naming convention of a managed runtime is <language-name><major-version>. At this time, all the supported Java runtimes are based on Amazon Corretto. For valid Java runtime names, see the section called “Release information” (p. 38).

Version syntax for Amazon Corretto runtimes:

Runtime Syntax Example

corretto11 11.0[.openjdk-update[.openjdk-

build[.corretto-specific- revision]]]

11.0.13.08.1

corretto8 8[.openjdk-update[.openjdk-

build[.corretto-specific- revision]]]

8.312.07.1

• 11.0.13 – Lock the Open JDK update version. App Runner updates only Open JDK and Amazon Corretto lower-level builds.

• 11.0.13.08.1 – Lock to a speciﬁc version. App Runner doesn't update your runtime version.

Topics

• Java runtime conﬁguration (p. 35)

• Java runtime examples (p. 35)

• Java runtime release information (p. 38)

(40)

Java runtime conﬁguration

Java runtime examples

The following examples show App Runner conﬁguration ﬁles for building and running a Java service.

The last example is the source code for a complete Java application that you can deploy to a Corretto 11 runtime service.

Minimal Corretto 11 conﬁguration ﬁle

This example shows a minimal conﬁguration ﬁle that you can use with a Corretto 11 managed runtime.

version: 1.0

runtime: corretto11 build:

commands:

build:

- mvn clean package

run:

command: java -jar target/MyApp-1.0-SNAPSHOT.jar -Xms256m .

Extended Corretto 11 conﬁguration ﬁle

This example shows how you can use all the conﬁguration keys with a Corretto 11 managed runtime.

version: 1.0

commands:

pre-build:

- yum install some-package - scripts/prebuild.sh build:

- mvn clean package post-build:

(41)

Java runtime examples

- mvn clean test env:

- name: M2

value: "/usr/local/apache-maven/bin"

- name: M2_HOME

value: "/usr/local/apache-maven/bin"

run: runtime-version: 11.0.13.08.1

command: java -jar target/MyApp-1.0-SNAPSHOT.jar -Xms256m . network:

port: 8000 env: APP_PORT env:

Complete Corretto 11 application source

This example shows the source code for a complete Java application that you can deploy to a Corretto 11 runtime service.

Example src/main/java/com/HelloWorld/HelloWorld.java

package com.HelloWorld;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RestController;

@RestController

public class HelloWorld { @RequestMapping("/") public String index(){

String s = "Hello World";

return s;

} }

Example src/main/java/com/HelloWorld/Main.java

package com.HelloWorld;

import org.springframework.boot.SpringApplication;

import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication public class Main {

public static void main(String[] args) { SpringApplication.run(Main.class, args);

} }

version: 1.0

commands:

build:

AWS App Runner

AWS App Runner

Developer Guide

AWS App Runner: Developer Guide

Table of Contents

What is AWS App Runner?

Who is App Runner for?

Accessing App Runner

Pricing for App Runner

What's next

Setting up for App Runner

Create an AWS account

Create an IAM user

Create an access key for your IAM user

What's next

Getting started with App Runner

Prerequisites

Files for the python-hello example repository

Step 1: Create an App Runner service

Step 2: Change your service code

Step 3: Make a conﬁguration change

Step 4: View logs for your service

Step 5: Clean up

What's next

App Runner architecture and concepts

App Runner concepts

App Runner resources

App Runner resource quotas

App Runner service based on a source image

Image repository providers

Using an image stored in Amazon ECR in your AWS account

Using an image stored in Amazon ECR in a diﬀerent AWS account

Using an image stored in Amazon ECR Public

Launch a service directly from Amazon ECR Public

Image example

App Runner service based on source code

Source code repository providers

Deploying from GitHub

App Runner managed platforms

Using the Python platform

Python runtime conﬁguration

Python runtime examples

Minimal Python conﬁguration ﬁle

Extended Python conﬁguration ﬁle

Complete Python application source

Python runtime release information

Using the Node.js platform

Node.js runtime conﬁguration

package.json

Node.js runtime examples

Minimal Node.js conﬁguration ﬁle

Extended Node.js conﬁguration ﬁle

Node.js app with Grunt

Node.js runtime release information

Using the Java platform

Java runtime conﬁguration

Java runtime examples

Minimal Corretto 11 conﬁguration ﬁle

Extended Corretto 11 conﬁguration ﬁle

Complete Corretto 11 application source