Run an ASP.NET Core web API Docker container on an Amazon EC2 Linux instance - AWS Prescriptive Guidance
SummaryPrerequisites and limitationsArchitectureToolsEpicsRelated resources

Run an ASP.NET Core web API Docker container on an Amazon EC2 Linux instance

Created by Vijai Anand Ramalingam (AWS) and Sreelaxmi Pai (AWS)

Environment: PoC or pilot

Technologies: Containers & microservices; Web & mobile apps

Workload: Microsoft

AWS services: Amazon EC2; Elastic Load Balancing (ELB)

Summary

This pattern is for people who are starting to containerize their applications on the Amazon Web Services (AWS) Cloud. When you begin to containerize apps on cloud, usually there are no container orchestrating platforms set up. This pattern helps you quickly set up infrastructure on AWS to test your containerized applications without needing an elaborate container orchestrating infrastructure.

The first step in the modernization journey is to transform the application. If it's a legacy .NET Framework application, you must first change the runtime to ASP.NET Core. Then do the following:

  • Create the Docker container image

  • Run the Docker container using the built image

  • Validate the application before deploying it on any container orchestration platform, such as Amazon Elastic Container Service (Amazon ECS) or Amazon Elastic Kubernetes Service (Amazon EKS). 

This pattern covers the build, run, and validate aspects of modern application development on an Amazon Elastic Compute Cloud (Amazon EC2) Linux instance.

Prerequisites and limitations

Prerequisites 

Product versions

  • Visual Studio Community 2022 or later

Architecture

Target architecture 

This pattern uses an AWS CloudFormation template to create the highly available architecture shown in the following diagram. An Amazon EC2 Linux instance is launched in a private subnet. AWS Systems Manager Session Manager is used to access the private Amazon EC2 Linux instance and to test the API running in the Docker container.

A user accessing the Amazon EC2 Linux instance and testing the API running in the Docker container.

  1. Access to the Linux instance through Session Manager

Tools

AWS services

  • AWS Command Line Interface – AWS Command Line Interface (AWS CLI) is an open source tool for interacting with AWS services through commands in your command line shell. With minimal configuration, you can run AWS CLI commands that implement functionality equivalent to that provided by the browser-based AWS Management Console.

  • AWS Management Console – The AWS Management Console is a web application that comprises and refers to a broad collection of service consoles for managing AWS resources. When you first sign in, you see the console home page. The home page provides access to each service console and offers a single place to access the information you need to perform your AWS related tasks.

  • AWS Systems Manager Session Manager – Session Manager is a fully managed AWS Systems Manager capability. With Session Manager, you can manage your Amazon Elastic Compute Cloud (Amazon EC2) instances. Session Manager provides secure and auditable node management without the need to open inbound ports, maintain bastion hosts, or manage SSH keys.

Other tools

  • Visual Studio 2022 – Visual Studio 2022 is an integrated development environment (IDE).

  • Docker – Docker is a set of platform as a service (PaaS) products that use virtualization at the operating-system level to deliver software in containers.

Code

FROM mcr.microsoft.com/dotnet/aspnet:5.0 AS base
 WORKDIR /app
EXPOSE 80
EXPOSE 443
 
FROM mcr.microsoft.com/dotnet/sdk:5.0 AS build
WORKDIR /src
COPY ["DemoNetCoreWebAPI/DemoNetCoreWebAPI.csproj", "DemoNetCoreWebAPI/"]
RUN dotnet restore "DemoNetCoreWebAPI/DemoNetCoreWebAPI.csproj"
COPY . .
WORKDIR "/src/DemoNetCoreWebAPI"
RUN dotnet build "DemoNetCoreWebAPI.csproj" -c Release -o /app/build
 
FROM build AS publish
RUN dotnet publish "DemoNetCoreWebAPI.csproj" -c Release -o /app/publish
 
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "DemoNetCoreWebAPI.dll"]

Epics

TaskDescriptionSkills required

Create an example ASP.NET Core web API using Visual Studio.

To create an example ASP.NET Core web API, do the following:

  1. Open Visual Studio 2022.

  2. Choose Create a new project.

  3. Select the ASP.NET Core Web API project template, and choose Next.

  4. For the project name, enter DemoNetCoreWebAPI, and choose Next.

  5. Choose Create.

  6. To run the project locally, press F5.

  7. Verify that the default WeatherForecast API endpoint is returning the results using Swagger.

  8. Open the command prompt, navigate to the .csproj project folder, and run the following commands to push the new web API to your GitHub repository. 

    git add --all
git commit -m “Initial Version”
git push
App developer

Create a Dockerfile.

To create a Dockerfile, do one of the following:

  • Create the Dockerfile manually using the sample Dockerfile in the Code section. Based on the requirements, select the appropriate .NET base image. For information about .NET and ASP.NET Core related images, see Docker hub. 

  • Create the Dockerfile using Visual Studio and Docker Desktop. In the solution explorer, right click on the project, choose Add->Docker Support. For Target OS, select Linux. Ensure that the new Dockerfile is in the same path as the solution file (.sln). 

To push the changes to your GitHub repository, run the following command.

git add --all
git commit -m “Dockerfile added”
git push
App developer
TaskDescriptionSkills required

Set up the infrastructure.

Launch the AWS CloudFormation template to create the infrastructure, which includes the following: 

  • A virtual private cloud (VPC), using the AWS VPC Quick Start, with two public and two private subnets spanning two Availability Zones.

  • The required IAM role to enable AWS Systems Manager.

  • In one of the private subnets, an Amazon Linux 2 demo instance with the latest SSM Agent. Although this instance doesn’t have any direct connectivity from the internet, it can be accessed securely by using AWS Systems Manager Session Manager without requiring a bastion host.

    Note: Amazon Linux 2 is nearing end of support. For more information, see the Amazon Linux 2 FAQs.

To learn more about accessing a private Amazon EC2 instance using Session Manager without requiring a bastion host, see the Toward a bastion-less world blog post.

App developer, AWS administrator, AWS DevOps

Log in to the Amazon EC2 Linux instance.

To connect to the Amazon EC2 Linux instance in the private subnet, do the following:

  1. Open the Amazon EC2 console.       

  2. In the navigation pane, choose Instances.

  3. Select the Amazon Linux 2 demo instance, and choose Connect.

    Note: Amazon Linux 2 is nearing end of support. For more information, see the Amazon Linux 2 FAQs.

  4. Choose Session Manager.

  5. Choose Connect to open a new terminal window.

  6. Run the following command.

     sudo su
App developer

Install and start Docker.

To install and start Docker in the Amazon EC2 Linux instance, do the following:

  1. To install Docker, run the following command.

    yum install -y docker

  2. To start the Docker service, run the following command.

     service docker start

  3. To verify Docker installation, run the following command.

    docker info
App developer, AWS administrator, AWS DevOps

Install Git and clone the repository.

To install Git on the Amazon EC2 Linux instance and clone the repository from GitHub, do the following.

  1. To install Git, run the following command.

    yum install git -y

  2. To clone the repository, run the following command.

    git clone https://github.com/<username>/<repo-name>.git

  3. To navigate to the Dockerfile, run the following command.

    cd <repo-name>/DemoNetCoreWebAPI/
App developer, AWS administrator, AWS DevOps

Build and run the Docker container.

To build the Docker image and run the container inside the Amazon EC2 Linux instance, do the following:

  1. To create the Docker image, run the following command.

    docker build -t aspnetcorewebapiimage -f Dockerfile .

  2. To view all the Docker images, run the following command.

    docker images

  3. To create and run the container, run the following command.

    docker run -d -p 80:80 --name aspnetcorewebapicontainer aspnetcorewebapiimage
App developer, AWS administrator, AWS DevOps
TaskDescriptionSkills required

Test the web API using the curl command.

To test the web API, run the following command.

curl -X GET "http://localhost/WeatherForecast" -H  "accept: text/plain"

Verify the API response.

Note: You can get the curl commands for each endpoint from Swagger when you are running it locally.

App developer
TaskDescriptionSkills required

Delete all resources.

Delete the stack to remove all the resources. This ensures that you aren’t charged for any services that you aren’t using.

AWS administrator, AWS DevOps

Related resources