AWS App Runner Explained: What It Is, How It Works, and When to Use It

App Runner in plain English

Imagine you have a Django or FastAPI application packaged as a Docker image. You want it running on the internet with HTTPS and automatic scaling. Without App Runner, deploying that image to AWS involves: pushing it to Amazon ECR, creating an ECS cluster, writing a task definition, creating a service, provisioning an Application Load Balancer, attaching a target group, requesting a TLS certificate, and writing Auto Scaling policies. Each one is a separate AWS resource to understand and maintain.

With App Runner, you point it at your image or source repo, configure CPU and memory, and deploy. App Runner creates all of those components internally and hands you a URL. You never see the load balancer or the cluster. They exist, but App Runner manages them.

Why App Runner exists

Before App Runner launched in 2021, running a containerised web service on AWS had a meaningful learning curve. Lambda solves the “no infrastructure” problem but imposes a 15-minute timeout and a function-based programming model that does not fit a standard HTTP server. ECS Fargate removes the need to manage EC2 instances but still requires you to understand clusters, task definitions, services, and load balancers.

App Runner targets the gap: a fully managed platform that accepts a standard container image or source code and requires no cluster, load balancer, or certificate configuration. The trade-off is reduced control; App Runner makes networking and infrastructure decisions that you cannot override without moving to a different service. For many web applications, that trade-off is well worth it.

How App Runner works

When you create an App Runner service, it follows this sequence:

1. Source: You provide either a container image URI (from ECR or a public registry) or a GitHub repository URL with runtime settings.
2. Build: For source-code deployments, App Runner builds the container image using a managed build environment. For image-based deployments, it pulls the image from the registry.
3. Deploy: App Runner provisions instances and starts your application container, injecting any environment variables you configured.
4. Route: A fully managed load balancer accepts incoming HTTPS traffic and distributes it across running instances. You do not create or configure this load balancer; App Runner manages it internally.
5. Scale: App Runner monitors concurrent request count per instance. When requests exceed your MaxConcurrency threshold, it starts new instances. When traffic drops, it scales back in.
6. Observe: Application logs flow automatically to CloudWatch Logs. CloudWatch Metrics reports request counts, latency, active instance counts, and HTTP response code distribution.
7. Update: When you push a new image to ECR or merge to the connected GitHub branch, App Runner detects the change and performs a rolling deployment to the new version.

Your application only needs to listen on the port you specify (typically 8000 or 8080) and respond to HTTP requests. Everything else is managed by App Runner.

Two deployment paths

App Runner accepts applications in two forms.

Source code repository

Connect App Runner to a GitHub repository. You specify the branch, runtime, build command, and start command. App Runner builds the container image in a managed environment and deploys it. When you push to the connected branch, App Runner automatically rebuilds and redeploys.

Supported runtimes include Python, Node.js, Java (Corretto), Go, .NET, PHP, and Ruby. This path is the fastest way to get from code to production without setting up a Docker build pipeline. There is no Dockerfile to write and no need to configure GitHub Actions before your first deployment.

The limitation: the managed build environment has fixed dependency support. For applications with complex system-level requirements or non-standard binaries, the container image path gives you more control.

Container image

Provide a container image URI from Amazon ECR (private or public) or a public registry such as Docker Hub. App Runner pulls the image and runs it. You are responsible for building and pushing the image; App Runner only runs it.

This is the recommended path for production deployments. You control the entire build environment, runtime, and dependency set. See Container Images in AWS for guidance on building production-ready Docker images.

Enable automatic deployments and App Runner polls ECR for new image versions. When it detects a new image, it deploys without any manual step. This pairs naturally with a CI/CD pipeline where pushing a tagged image to ECR is the final deploy step.

# Create an App Runner service from a private ECR image
aws apprunner create-service \
  --service-name my-web-api \
  --source-configuration '{
    "ImageRepository": {
      "ImageIdentifier": "123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:latest",
      "ImageRepositoryType": "ECR",
      "ImageConfiguration": {
        "Port": "8000",
        "RuntimeEnvironmentVariables": {
          "ENVIRONMENT": "production"
        }
      }
    },
    "AutoDeploymentsEnabled": true,
    "AuthenticationConfiguration": {
      "AccessRoleArn": "arn:aws:iam::123456789012:role/AppRunnerECRAccessRole"
    }
  }' \
  --instance-configuration '{
    "Cpu": "1 vCPU",
    "Memory": "2 GB",
    "InstanceRoleArn": "arn:aws:iam::123456789012:role/AppRunnerInstanceRole"
  }'

The response includes a service URL, such as abc123.us-east-1.awsapprunner.com, once the service finishes deploying.

When to use App Runner

App Runner is a good fit when:

• You are deploying a web application or HTTP API. A Django app, a FastAPI service, a Node.js REST API: App Runner is purpose-built for this pattern.
• You want minimal infrastructure to configure. A small team or solo developer who needs something running on AWS without spending days learning ECS.
• Your application runs as a single container. Standard web services (one process, one container) fit App Runner’s model exactly.
• You want automatic deployments without a separate deploy step. App Runner’s built-in ECR polling and GitHub integration removes the need for a dedicated deployment pipeline on many projects.
• Traffic is variable or unpredictable. Concurrency-based auto scaling handles spikes without pre-provisioning capacity.
• You are migrating from a PaaS. App Runner is the closest AWS equivalent to Heroku or Railway. Teams moving from those platforms will find the operational model familiar.

Concrete examples: a B2B SaaS API backend, an internal admin tool, a mobile app backend, a Django or FastAPI service with moderate traffic, or a prototype you need running quickly on AWS.

When not to use App Runner

• You need multiple containers per service instance. App Runner runs one container per instance. Sidecar patterns (an application alongside an Envoy proxy, a log forwarder, or a monitoring agent) are not supported. Use ECS Fargate tasks for multi-container workloads.
• You need fine-grained VPC control. The VPC connector gives egress access to your VPC, but you cannot control ingress routing, place instances in specific subnets, or use private load balancers. ECS Fargate gives you full VPC control.
• Your workload is event-driven rather than HTTP-driven. If you process SQS messages, respond to S3 events, or run scheduled jobs, Lambda is a better fit. App Runner is built for handling HTTP requests.
• You need background workers without HTTP traffic. App Runner scales based on request concurrency. A worker process with no incoming requests has no scale signal to stay running. Use AWS Batch or ECS with an SQS-driven task pattern instead.
• You need Kubernetes-native tooling. If your team relies on Helm, Kustomize, or Kubernetes operators, Amazon EKS is the right environment. App Runner is not Kubernetes.
• Cost at very high sustained volumes. At consistently high request volumes, ECS Fargate or a right-sized EC2 deployment may be cheaper per unit of compute. Model the costs before committing App Runner to high-throughput production workloads.

IAM, networking, scaling, and operations

IAM roles

App Runner uses two separate IAM roles:

• Access role: Used by App Runner to pull your image from a private ECR repository. The trust policy must allow the principal build.apprunner.amazonaws.com. Attach the AWS-managed policy AWSAppRunnerServicePolicyForECRAccess. Not required if your image is on a public registry.

• Instance role: Used by your application code at runtime. If your application calls DynamoDB, S3, Secrets Manager, or any other AWS service, those permissions go on the instance role. The trust policy must allow the principal tasks.apprunner.amazonaws.com. Apply least privilege: grant only the permissions the application actually uses, scoped to specific resources.

Auto scaling

App Runner scales based on the number of concurrent requests being handled per instance. You configure three values in an auto scaling configuration:

• MinSize: Minimum instances kept running. Default is 1. Set to 0 to allow scale-to-zero.
• MaxSize: Maximum instances App Runner will add.
• MaxConcurrency: Concurrent requests per instance before a new instance starts. Default is 100. Lower this for memory-intensive workloads that cannot safely handle 100 simultaneous requests.

VPC connector and private resource access

By default, App Runner instances run in an AWS-managed network. They can reach public AWS endpoints but cannot access resources in your private VPC: RDS databases, ElastiCache clusters, or internal services.

A VPC connector attaches App Runner’s outbound traffic to subnets and security groups in your VPC. Once attached, your application can connect to a private RDS database on port 5432 or an ElastiCache cluster on port 6379. The security group on the database must allow inbound connections from the security group assigned to the VPC connector.

Custom domains

App Runner provides a default HTTPS endpoint at *.awsapprunner.com. To use your own domain, associate it with the service through the console or CLI. App Runner requests a TLS certificate automatically from AWS Certificate Manager. You add CNAME records at your DNS provider or in Route 53 to complete the setup. Certificate renewal is automatic.

Observability

App Runner delivers application logs to CloudWatch Logs automatically, with no agent needed. System events (deployments, scaling activity, health check results) are written to a separate log group. CloudWatch Metrics tracks request count, request latency (p50, p90, p99), active instance count, and HTTP response code distribution.

For distributed tracing, instrument your application with the AWS X-Ray SDK. App Runner does not inject traces automatically; the instrumentation lives in your application code.

App Runner vs Lambda vs ECS Fargate

For most web applications and APIs, App Runner is the simplest starting point on AWS. When you outgrow its networking model or need multiple containers, ECS Fargate is the natural next step (more complexity, but full control). Lambda is the right choice when the work is event-driven and short-lived rather than request-handling. For the full decision framework including EC2, see the EC2 vs Lambda vs containers guide.