Observability for AWS App Runner VPC networking
With AWS App Runner, you can quickly deploy web applications and APIs at any scale. You can start with your source code or a container image, and App Runner will fully manage all infrastructure, including servers, networking, and load balancing for your application. If you want, App Runner can also configure a deployment pipeline for you.
This year, AWS announced Amazon Virtual Private Cloud (Amazon VPC) support in February and AWS X-Ray support in April for App Runner services.
With VPC support, applications can now connect to private resources in your Amazon VPC, such as an Amazon Relational Database Service (Amazon RDS), Redis, or Memcached caches in Amazon ElastiCache, or other private services hosted in your VPC.
With X-Ray support, you can take advantage of adding tracing to App Runner services without having to configure and set up the required sidecars or agents. You can trace your containerized applications in AWS X-Ray by instrumenting applications with the AWS Distro for OpenTelemetry (ADOT).
This blog post will help you to learn more about how these two capabilities work together in practice with a Node.js web application connected to an Amazon RDS database.
For this walkthrough, you should have the following prerequisites:
- An AWS account with full privileges to create and access the following resources:
- Internet gateway
- NAT gateway
- Security group
- IAM role
- Amazon RDS database
- Amazon CloudWatch
- App Runner
- Basic knowledge of containers
Step 1: Preparing the Amazon VPC and subnets
Follow these steps to create a VPC called
hotel-app-vpc with subnets to host your database and applications:
- Open the Amazon VPC console.
- On the VPC Dashboard, choose Launch VPC Wizard.
- Enter the following information into the wizard and then choose Create VPC.
- Name tag auto-generation: Enter “hotel-app.”
- Availability Zones: Choose 3.
- NAT gateways: Choose In 1 AZ.
- VPC endpoints: Choose None.
- All other settings: Leave as default.
It takes several minutes to create the VPC, subnets, and other configured resources. Once they are created, you can select the View VPC button at the end of the wizard and check the detail. Note down the name of the VPC and subnets, which you will use later.
Step 2: Create security groups
In order to deploy an application on App Runner that has outbound access to a VPC, you must first create an App Runner VPC connector by specifying one or more subnets and security groups to associate with the application.
With regards to the security groups, it is important to note that App Runner VPC connector is only used for outbound communication from your application. Thus, the inbound rules of the security group(s) are not relevant and are effectively ignored. What matters are the outbound rules, which should allow communication to the desired destination endpoints. Read Deep Dive on AWS App Runner VPC Networking if you’re interested in more detail.
We will create two security groups with corresponding security group rules within the VPC created in Step 1:
hotel-app-svc-sg: The security group for App Runner VPC connector
|Rule||IP version||Type||Protocol||Port range||Destination|
hotel-app-rds-sg: The security group for your Amazon RDS database, which is the desired destination resource for your application communication
|Rule||IP version||Type||Protocol||Port range||Source|
|Inbound||N/A||MYSQL/Aurora||TCP||3306||sg-0f7ff683254111fb2 / hotel-app-svc-sg|
You must ensure the security group associated with the destination resource hotel-app-rds-sg have appropriate inbound rules to allow traffic from the VPC connector security group hotel-app-svc-sg.
Use these steps to create security groups using the console:
- Open the Amazon VPC console. In the navigation pane, choose Security Groups, then choose Create security group.
- Enter a name
hotel-app-svc-sgand description for the security group (see the tables below for our suggested names). You cannot change the name and description of a security group after it is created.
- From VPC, choose the VPC
hotel-app-vpc. Leave security group rules empty for now; we will add them later on.
- You can add tags now, or you can add them later. To add a tag, choose Add new tag and enter the tag key and value. Choose Create security group.
- Repeat Steps 1–3 for another security group
- Add the security group rule by referring to the table above:
- For Type, choose MYSQL/Aurora.
- For Destination, choose
- Choose Create security group.
- Open the Amazon VPC console. In the navigation pane, choose Security Groups. You will see the two security groups created above
- Select the security group
- Choose Actions, Edit outbound rules.
- Choose Add rule and do the following by referring to the table above:
- For Type, choose All traffic.
- For Destination, choose Anywhere-IPv4.
- Choose Save rules.
Note down the name of the security groups, which you will use later when creating the Amazon RDS database and App Runner service.
Step 3: Preparing the Amazon RDS database
This step is to set up the Amazon RDS database to be hosted in a private VPC network.
- Open the Amazon RDS console.
- In the navigation pane, choose Databases.
- Choose Create database and make sure that StandardCreate is chosen.
- For Engine type, choose Amazon Aurora.
- For Edition, choose Amazon Aurora with MySQL compatibility.
- Expand Hide filters, select Show versions that support Serverless v2, and choose an available option.
- For Templates, choose Dev/Test.
- For DB cluster identifier, enter a name for the DB cluster, or leave the default name. Here we put
- For Master username, keep default value
- To use an automatically generated password for the DB cluster, make sure that the Auto generate a password box is selected. To enter your password, clear the Auto generate a password box, and then enter the same password in Master password and Confirm password.
- For DB instance class, choose Serverless.
- For Connectivity, use the VPC
hotel-app-vpcand the security group
hotel-app-rds-sgcreated in Steps 1 and 2. You don’t need to make the database publicly accessible because you’re going to connect using private VPC networking.
13. Keep all the other default values.
14. Choose Create database.
It takes several minutes for the RDS database to be provisioned. You can view the database list on the Amazon RDS Databases page. Choose
hotel-app-database in the DB identifier list and view database detail:
Note down the Writer instance endpoint name, password, and user information for later application connection.
Step 4: Preparing the application source code repository
With App Runner, you can deploy a new service from code hosted in a source code repository or using a container image. In this example, I use a private project that I have on GitHub.
It’s a very simple Node.js web application connecting to the database. The application stores hotel room information in a private MySQL/Aurora database on Amazon RDS. Room information can be retrieved and updated using HTTP(S)
POST requests to the app. The Amazon RDS database is only accessible from within the VPC. You can create tables, add items, and list items. This is the source code of the app (
Instrument your application
Sending traces to X-Ray
To send trace data to X-Ray via the ADOT, you must configure the X-Ray ID generator, X-Ray propagator, and gRPC exporter on the global tracer provider.
Inject tracer in the main code of the app (
Set up Amazon RDS database connection
Update rdsUrl, password, and user with the RDS database endpoint, password and user information in
hotel-app/rds.js from Step 3.
Step 5: Set up an IAM role
App Runner uses an AWS Identity and Access Management (IAM) role to authorize access to other AWS services. In this case, App Runner uses the role to allow the application to send tracing data to X-Ray.
- Open the IAM console.
- In the navigation pane of the IAM console, choose Roles, and then choose Create role.
- For Select trusted entity, choose Custom trust policy. Follow the instructions for instance roles in How App Runner works with IAM in the App Runner Developer Guide, and input the role trust policy:
4. Choose Next.
5. For Add permissions:
a. Attach an AWS-managed policy AWSXRayDaemonWriteAccess that allows App Runner to send tracing data to X-Ray.
b. Attach an AWS-managed policy AmazonRDSDataFullAccess that allows App Runner to integrate with the Amazon RDS database.
6. Choose Next.
7. For Role name, enter
8. Review the role and then choose Create role.
Your IAM role will look like the following screenshot:
Step 6: Create and configure your App Runner service to enable VPC networking and X-Ray tracing
Now that your code is instrumented and you’ve created the necessary role and VPC resources, create your App Runner service and configure it to enable VPC networking and X-Ray tracing.
- Open the App Runner console.
- Navigate to the App Runner Services
- Choose Create service.
- For repository type, choose Source code repository.
- For Connect to GitHub, choose your GitHub repository and the branch to use.
- For the Deployment settings, I chose Manual. Optionally, you could have selected the Automatic deployment trigger to have every push to this branch deploy a new version of your service.
- Choose Next.
- Then, configure the build. This is a very simple application, so I pass the build and start commands in the console:
- Runtime: Nodejs 14
- Build command: npm install
- Start command: npm start
For more advanced use cases, you can add an apprunner.yaml configuration file to your repository as in this sample application.
- Choose Next.
- In the Service settings section, for Service name, enter
- In the Security section, for Instance role, choose the IAM role that was created earlier, hotel-app-instance-role.
- For AWS KMS key, choose Use an AWS-owned key.
- For Networking, select the new option to use a Custom VPC for outgoing network traffic and then add a new VPC connector.
For Add new VPC connector, enter VPC connector name
hotel-app-svc-vpc. To add a new VPC connector, you can select the VPC, subnets, and the hotel-app-svc-sg security group created in Steps 1 and 2. In this way, the App Runner service will be able to connect to the Amazon RDS database.
- For the newly introduced Observability section, enable Tracing with AWS X-Ray.
- Keep all the other default values.
- Choose Next.
- Review all the settings and then choose Create & deploy.
- On the service dashboard page, in the Service overview section, monitor the service status. The service is live and ready to process requests when the status turns to Running.
Step 7: Run application
After a few minutes, the service is running, and the Observability tab shows Tracing On.
Select the Default domain URL to open a new tab in your browser. The application is up and running and connecting to the Amazon RDS database with VPC networking.
/createto create a table in the database if one doesn’t already exist. (You must call this API first if this is the first time using the app.)
/addto insert a new room data item in the database.
/roomsto display rooms in the database.
Step 8: View tracing data in X-Ray
- On the Observability tab, choose View service map.
You are redirected to the CloudWatch console. Notice that HTTP requests and AWS SDK requests are instrumented. The following image shows an X-Ray service map with traces collected from the example application.
- Choose View traces.
The console shows the CloudWatch Traces page.
Suppose that you’ve made a few API calls. Some of them returned 4xx Error. To determine which group of requests caused the service 4xx responses, query the X-Ray traces and filter by the HTTP status code. To troubleshoot the cause of the error, on the Traces list, narrow the results to the group of bad requests by HTTP method. Then review the details of each trace segment. This information can help you to troubleshoot issues.
- Delete the App Runner service
- Delete the App Runner VPC connector
- Delete the IAM role created earlier
- Delete the Amazon RDS database
- Delete the security groups
- Delete the NAT gateway of the VPC
- Detach the internet gateway from the
- Delete the internet gateway.
- Delete the VPC
Resources to learn more
There are more resources to learn about AWS App Runner VPC and X-Ray supports, and we encourage you to check them out!
- Container Day – Docker Con | How Developers can get to production web applications at scale easily
- Containers from the Couch | AWS App Runner X-Ray Integration Feature Launch
- Containers from the Couch | AWS App Runner adds support for Amazon VPC!
- Containers from the Couch | AWS App Runner VPC Support – Launch Demo
- AWS Blog | Tracing an AWS App Runner service using AWS X-Ray with OpenTelemetry
- AWS Blog | Deep Dive on AWS App Runner VPC Networking
- AWS Blog | New for App Runner – VPC Support
- ✨ AWS App Runner Public Roadmap at GitHub ✨ – See the latest roadmap items and leave your requests and feedback to the App Runner team directly!
Follow me on Twitter @pymhq