Creating an App Runner service

AWS App Runner automates the process of going from a container image or a source code repository to a running web service that scales automatically. You point App Runner to your source image or code, specifying only a small number of required settings. App Runner builds your application if needed, provisions compute resources, and deploys your application to run on them.

When you create a service, App Runner creates a service resource. In some cases, you might need to provide a connection resource. If you use the App Runner console, the console implicitly creates the connection resource. For details about App Runner resource types, see App Runner resources. These resource types have quotas that are associated with your account in each AWS Region. For more information, see App Runner resource quotas.

There are subtle differences in the procedure for creating a service depending on the source type and provider. This topic shows entirely separate procedures for creating these different source types so that you can follow whichever one best matches your situation. For a basic starting procedure with a code example, see Getting started with App Runner.

Prerequisites

Before you create your App Runner service, be sure to complete the following actions:

• Complete the setup steps in Setting up for App Runner.

• Have your application source ready. You can use either a code repository in GitHub or a container image in Amazon Elastic Container Registry (Amazon ECR) to create an App Runner service.

Create a service

This section walks through the creation process for the two App Runner service types: based on source code, and based on a container image.

Create a service from a GitHub code repository

The following sections show how to create an App Runner service when your source is a code repository in GitHub. When you use GitHub, App Runner has to connect to the GitHub organization or account. Therefore, you need to help establish this connection. For more information about App Runner connections, see Managing App Runner connections.

When you create the service, App Runner builds a Docker image containing your application code and dependencies. It then launches a service that runs a container instance of this image.

Creating a service from code using the App Runner console

To create an App Runner service using the console

1. Configure your source code.

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

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

      

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

      

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

   4. For Connect to GitHub, select a GitHub account or organization that you've used before, or choose Add new. Then, go through the process of providing your GitHub credentials and choosing a GitHub account or organization to connect to.

   5. For Repository, select the repository that contains your application code.

   6. For Branch, select the branch that you want to deploy.

2. Configure your deployments.

   1. In the Deployment settings section, choose Manual or Automatic.

      For more information about deployment methods, see Deployment methods.

   2. Choose Next.

   

3. Configure the application build.

   1. On the Configure build page, for Configuration file, choose Configure all settings here if your repository doesn't contain an App Runner configuration file, or Use a configuration file if it does.

      Note

      An App Runner configuration file is a way to maintain your build configuration as part of your application source. When you provide one, App Runner reads some values from the file and doesn't let you set them in the console.

   2. Provide the following build settings:

      • Runtime – Choose a specific managed runtime for your application.

      • Build command – Enter a command that builds your application from its source code. This might be a language-specific tool or a script provided with your code.

      • Start command – Enter the command that starts your web service.

      • Port – Enter the IP port that your web service listens to.

   3. Choose Next.

   

4. Configure your service.

   1. On the Configure service page, in the Service settings section, enter a service name.

      Note

      All other service settings are either optional or have console-provided defaults.

   2. Optionally change or add other settings to meet your application requirements.

   3. Choose Next.

   

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

   Result: If service creation succeeds, the console should show the service dashboard, with a Service overview of the new service.

   

6. Verify that your service is running.

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

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

   3. Use your website and verify that it's running properly.

Creating a service from code using the App Runner API or AWS CLI

To create a service using the App Runner API or AWS CLI, call the CreateService API action. For more information and an example, see CreateService. If this is the first time you're creating a service using a specific GitHub organization or account, start by calling CreateConnection. This establishes a connection between App Runner and the GitHub organization or account. For more information about App Runner connections, see Managing App Runner connections.

Your service creation starts if the call returns a successful response with a Service object showing "Status": "CREATING".

For an example call, see Create a source code repository service in the AWS App Runner API Reference

Create a service from an Amazon ECR image

The following sections show how to create an App Runner service when your source is a container image stored in Amazon ECR. Amazon ECR is an AWS service. Therefore, to create a service based on an Amazon ECR image, you provide App Runner with an access role containing the necessary Amazon ECR action permissions.

Note

An access role isn't required if your image is stored in Amazon ECR Public, where images are publicly available.

During service creation, App Runner launches a service that runs a container instance of the image you provide. There is no build phase in this case.

For more information, see App Runner service based on a source image.

Topics

• Creating a service from an image using the App Runner console
• Creating a service from an image using the App Runner API or AWS CLI

Creating a service from an image using the App Runner console

To create an App Runner service using the console

1. Configure your source code.

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

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

      

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

      

   3. On the Source and deployment page, in the Source section, for Repository type, choose Container registry.

   4. For Provider, choose the provider where your image is stored:

      • Amazon ECR – A private image stored in Amazon ECR.

      • Amazon ECR Public – A publicly readable image stored in Amazon ECR Public.

   5. For Container image URI, choose Browse.

   6. In the Select Amazon ECR container image dialog box, for Image repository, select the repository that contains your image.

   7. For Image tag, select the specific image tag that you want to deploy, for example, latest, and then choose Continue.

   

2. Configure your deployments.

   1. In the Deployment settings section, choose Manual or Automatic.

      Note

      App Runner doesn't support automatic deployment for Amazon ECR Public images, and for images in an Amazon ECR repository that belongs to a different AWS account than the one that your service is in.

      For more information about deployment methods, see Deployment methods.

   2. [Amazon ECR provider] For ECR access role, choose an existing service role in your account or choose to create a new role. If you're using manual deployment, you can also choose to use the IAM user role at the time of deployment.

   3. Choose Next.

   

3. Configure your service.

   1. On the Configure service page, in the Service settings section, enter a service name and the IP port that your service web site listens to.

      Note

      All other service settings are either optional or have console-provided defaults.

   2. (Optional) Change or add other settings to suit your application's needs.

   3. Choose Next.

   

4. On the Review and create page, verify all the details that you entered, and then choose Create and deploy.

   Result: If service creation succeeds, the console should show the service dashboard, with a Service overview of the new service.

   

5. Verify that your service is running.

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

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

   3. Use your website and verify that it's running properly.

Creating a service from an image using the App Runner API or AWS CLI

To create a service using the App Runner API or AWS CLI, call the CreateService API action.

Your service creation starts if the call returns a successful response with a Service object showing "Status": "CREATING".

For an example call, see Create a source image repository service in the AWS App Runner API Reference

When service creation fails

If your attempt to create an App Runner service fails, the service shows a status of CREATE_FAILED (Create failed on the console). Your attempt to create a service might fail because of issues with one of the following:

• your application code

• the build process

• configuration

• resource quotas

• temporary issues with the underlying AWS services that your service needs to use

To troubleshoot a failure, we recommend that you take the following actions.

1. Read the service events and logs to find out what caused the failure.

2. Make any necessary changes to your code or configuration.

3. If you reached your service quota, delete one or more services.

4. If you reached another resource quota, you may be able to increase it if it's adjustable.

5. Try creating the service again after completing all of these steps.

   Note

   One of the adjustable resource quotas that might be causing an issue is the Fargate On-Demand vCPU resource.

   The number of instances that App Runner can provide to your service is determined by the vCPU resource count. This is an adjustable quota value for the Fargate On-Demand vCPU resource count that resides in the AWS Fargate (Fargate) service. To view the vCPU quota settings for your account, or to request a quota increase, use the Service Quotas console in the AWS Management Console. For more information, see AWS Fargate service quotas in the Amazon Elastic Container Service Developer Guide.

Important

The failed service isn't usable. You don't incur any additional charges for it beyond the initial creation attempt. However, App Runner doesn't automatically delete the failed service, and it still counts towards your service quota. When you're done analyzing the failure, make sure that you delete the failed service.