Tutorial: Deploy an application to Amazon ECS

To create an IAM Identity Center user

1. Sign in to the AWS Management Console and open the AWS IAM Identity Center console at https://console.aws.amazon.com/singlesignon/.

   Note

   Make sure you sign in using the AWS account that is connected to your CodeCatalyst space. You can verify which account is connected by navigating to your space and choosing the AWS accounts tab. For more information, see Creating a space.

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

3. In Username, enter:

   CodeCatalystECSUser

4. Under Password, choose Generate a one-time password that you can share with this user.

5. In Email address and Confirm email address, enter an email address that doesn't already exist in IAM Identity Center.

6. In First name and Last name, enter:

   CodeCatalystECSUser

7. In Display name, keep the automatically generated name:

   CodeCatalystECSUser CodeCatalystECSUser

8. Choose Next.

9. On the Add user to groups page, choose Next.

10. On the Review and add user page, review the information and choose Add user.

    A One-time password dialog box appears.

11. Choose Copy and then paste the sign-in information, including the AWS access portal URL and the one-time password.

12. Choose Close.

To create a permission set

You'll assign this permission set to CodeCatalystECSUser later.

1. In the navigation pane, choose Permission sets, and then choose Create permission set.

2. Choose Predefined permission set and then select AdministratorAccess. This policy provides full permissions to all AWS services.

3. Choose Next.

4. In Permission set name, enter:

   CodeCatalystECSPermissionSet

5. Choose Next.

6. On the Review and create page, review the information and choose Create.

To assign the permission set to CodeCatalystECSUser

1. In the navigation pane, choose AWS accounts, and then select the check box next to the AWS account that you're currently signed in to.

2. Choose Assign users or groups.

3. Choose the Users tab.

4. Select the check box next to CodeCatalystECSUser.

5. Choose Next.

6. Select the check box next to CodeCatalystECSPermissionSet.

7. Choose Next.

8. Review the information and choose Submit.

   You have now assigned CodeCatalystECSUser and CodeCatalystECSPermissionSet to your AWS account, binding them together.

To sign out and sign back in as CodeCatalystECSUser

1. Before you sign out, make sure you have the AWS access portal URL and the username and one-time password for CodeCatalystECSUser. You should have copied this information to a text editor earlier.

   Note

   If you do not have this information, go to the CodeCatalystECSUser details page in IAM Identity Center, choose Reset password, Generate a one-time password [...], and Reset password again to display the information on the screen.

2. Sign out of AWS.

3. Paste the AWS access portal URL into your browser's address bar.

4. Sign in with the username and one-time password for CodeCatalystECSUser.

5. In New password, enter a password, and choose Set new password.

   An AWS account box appears on the screen.

6. Choose AWS account, and then choose the name of the AWS account to which you assigned the CodeCatalystECSUser user and permission set.

7. Next to the CodeCatalystECSPermissionSet, choose Management console.

   The AWS Management Console appears. You are now signed in as CodeCatalystECSUser with the appropriate permissions.

To launch an AWS CloudShell instance

1. As CodeCatalystECSUser, in the top navigation bar, choose the AWS icon ( ).

   The main page of the AWS Management Console appears.

2. In the top navigation bar, choose the AWS CloudShell icon ( ).

   CloudShell opens. Wait while the CloudShell environment is created.

   Note

   If you don't see the CloudShell icon, make sure that you're in a Region supported by CloudShell. This tutorial assumes you are in the US West (Oregon) Region.

To verify that the AWS CLI is installed

1. In the CloudShell terminal, enter:

   aws --version

2. Check that a version appears.

   The AWS CLI is already configured for the current user, CodeCatalystECSUser, so there is no need to configure AWS CLI keys and credentials, as is normally the case.

To create the task execution role

This role grants Amazon ECS and AWS Fargate permission to make API calls on your behalf.

1. Create a trust policy:

   1. In AWS CloudShell, enter the following command:

      cat > codecatalyst-ecs-trust-policy.json

      A blinking prompt appears in the CloudShell terminal.

   2. Enter the following code at the prompt:

      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Sid": "",
            "Effect": "Allow",
            "Principal": {
              "Service": "ecs-tasks.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
          }
        ]
      }

   3. Place your cursor after the last curly bracket (}).

   4. Press Enter and then Ctrl+d to save the file and exit cat.

2. Create a task execution role:

   aws iam create-role \
         --role-name codecatalyst-ecs-task-execution-role \
         --assume-role-policy-document file://codecatalyst-ecs-trust-policy.json

3. Attach the AWS managed AmazonECSTaskExecutionRolePolicy policy to the role:

   aws iam attach-role-policy \
         --role-name codecatalyst-ecs-task-execution-role \
         --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy

4. Display the role’s details:

   aws iam get-role \
         --role-name codecatalyst-ecs-task-execution-role

5. Note the role's "Arn": value, for example, arn:aws:iam::111122223333:role/codecatalyst-ecs-task-execution-role. You will need this Amazon Resource Name (ARN) later.

To create an Amazon ECS cluster

This cluster will contain the Apache placeholder application, and later, the Hello World application.

1. As CodeCatalystECSUser, in AWS CloudShell, create an empty cluster:

   aws ecs create-cluster --cluster-name codecatalyst-ecs-cluster

2. (Optional) Verify that the cluster was created successfully:

   aws ecs list-clusters

   The ARN of the codecatalyst-ecs-cluster cluster should appear in the list, indicating a successful creation.

To create a task definition file

The task definition file indicates to run the Apache 2.4 Web server Docker image (httpd:2.4) which is pulled from DockerHub.

1. As CodeCatalystECSUser, in AWS CloudShell, create a task definition file:

   cat > taskdef.json

2. Paste the following code at the prompt:

   {
       "executionRoleArn": "arn:aws:iam::111122223333:role/codecatalyst-ecs-task-execution-role",
       "containerDefinitions": [
           {
               "name": "codecatalyst-ecs-container",
               "image": "httpd:2.4",
               "essential": true,
               "portMappings": [
                   {
                       "hostPort": 80,
                       "protocol": "tcp",
                       "containerPort": 80
                   }
               ]
           }
       ],
       "requiresCompatibilities": [
           "FARGATE"
       ],
       "cpu": "256",
       "family": "codecatalyst-ecs-task-def",
       "memory": "512",
       "networkMode": "awsvpc"
   }

   In the preceding code, replace arn:aws:iam::111122223333:role/codecatalyst-ecs-task-execution-role

   with the ARN of the task execution role that you noted in To create the task execution role.

3. Place your cursor after the last curly bracket (}).

4. Press Enter and then Ctrl+d to save the file and exit cat.

To register the task definition file with Amazon ECS

1. As CodeCatalystECSUser, in AWS CloudShell, register the task definition:

   aws ecs register-task-definition \
       --cli-input-json file://taskdef.json

2. (Optional) Verify that the task definition was registered:

   aws ecs list-task-definitions

   The codecatalyst-ecs-task-def task definition should appear in the list.

To create the Amazon ECS service

The Amazon ECS service runs the tasks (and associated Docker containers) of the Apache placeholder application, and later, the Hello World application.

1. As CodeCatalystECSUser, switch to the Amazon Elastic Container Service console if you haven't done so already.

2. Choose the cluster you created earlier, codecatalyst-ecs-cluster.

3. In the Services tab, choose Create.

4. In the Create page, do the following:

   1. Keep all default settings except for those listed next.

   2. For Launch type, choose FARGATE.

   3. Under Task definition, in the Family drop-down list, choose:

      codecatalyst-ecs-task-def

   4. For Service name, enter:

      codecatalyst-ecs-service

   5. For Desired tasks, enter:

      3

      In this tutorial, each task launches a single Docker container.

   6. Expand the Networking section.

   7. For VPC, choose any VPC.

   8. For Subnets, choose any subnet.

      Note

      Only specify one subnet. That's all that is needed for this tutorial.

      Note

      If you don’t have a VPC and subnet, create them. See Create a VPC, and Create a subnet in your VPC in the Amazon VPC User Guide.

   9. For Security group, choose Create a new security group, and then do the following:

      1. For Security group name, enter:

         codecatalyst-ecs-security-group

      2. For Security group description, enter:

         CodeCatalyst ECS security group

      3. Choose Add rule. For Type, choose HTTP, and for Source, choose Anywhere.

   10. At the bottom, choose Create.

   11. Wait while the service is created. This may take a few minutes.

5. Choose the Tasks tab, and then choose the refresh button. Verify that all three tasks have their Last Status column set to Running.

(Optional) To verify that your Apache placeholder application is running

1. In the Tasks tab, choose any one of the three tasks.

2. In the Public IP field, choose open address.

   An It Works! page appears. This indicates that the Amazon ECS service successfully started a task that launched a Docker container with the Apache image.

   At this point in the tutorial, you have manually deployed an Amazon ECS cluster, service, and task definition, as well as an Apache placeholder application. With all these items in place, you are now ready to create a workflow that will replace the Apache placeholder application with the tutorial’s Hello World application.

To create an image repository in Amazon ECR

1. As CodeCatalystECSUser, in AWS CloudShell, create an empty repository in Amazon ECR:

   aws ecr create-repository --repository-name codecatalyst-ecs-image-repo

2. Display the Amazon ECR repository’s details:

   aws ecr describe-repositories \
         --repository-names codecatalyst-ecs-image-repo
   

3. Note the “repositoryUri”: value, for example, 111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-ecs-image-repo.

   You need it later when adding the repository to your workflow.

To add build and deploy roles to your account connection

1. In CodeCatalyst, navigate to your space.

2. Choose AWS accounts. A list of account connections appears.

3. Choose the account connection that represents the AWS account where you created your build and deploy roles.

4. Choose Manage roles from AWS management console.

   The Add IAM role to Amazon CodeCatalyst space page appears. You might need to sign in to access the page.

5. Select Add an existing role you have created in IAM.

   A drop-down list appears. The list displays all IAM roles with a trust policy that includes the codecatalyst-runner.amazonaws.com and codecatalyst.amazonaws.com service principals.

6. In the drop-down list, choose codecatalyst-ecs-build-role, and choose Add role.

   Note

   If you see The security token included in the request is invalid, it might be because you do not have the right permissions. To fix this issue, sign out of AWS as sign back in with the AWS account that you used when you created your CodeCatalyst space.

7. Choose Add IAM role, choose Add an existing role you have created in IAM, and in the drop-down list, choose codecatalyst-ecs-deploy-role. Choose Add role.

   You have now added the build and deploy roles to your space.

8. Copy the value of the Amazon CodeCatalyst display name. You'll need this value later, when creating your workflow.

To create a source repository

1. Open the CodeCatalyst console at https://codecatalyst.aws/.

2. Navigate to your project, codecatalyst-ecs-project.

3. In the navigation pane, choose Code, and then choose Source repositories.

4. Choose Add repository, and then choose Create repository.

5. In Repository name, enter:

   codecatalyst-ecs-source-repository

6. Choose Create.

To add the index.html file

1. In the CodeCatalyst console, go to your source repository, codecatalyst-ecs-source-repository.

2. In Files, choose Create file.

3. For File name, enter:

   public-html/index.html

   Important

   Make sure to include the public-html/ prefix to create a folder of the same name. The index.html is expected to be in this folder.

4. In the text box, enter the following code:

   <html>
     <head>
       <title>Hello World</title>
       <style>
         body {
         background-color: black;
         text-align: center;
         color: white;
         font-family: Arial, Helvetica, sans-serif;
         }  
       </style>
     </head>
     <body>
       <h1>Hello World</h1>
     </body>
   </html>

5. Choose Commit, and then choose Commit again.

   The index.html is added to your repository in a public-html folder.

To add the Dockerfile

1. In your source repository, choose Create file.

2. For File name, enter:

   Dockerfile

   Do not include a file extension.

   Important

   The Dockerfile must reside in your repository’s root folder. The workflow’s Docker build command expects it to be there.

3. In the text box, enter the following code:

   FROM httpd:2.4
   COPY ./public-html/index.html /usr/local/apache2/htdocs/index.html
   EXPOSE 80

4. Choose Commit, and then choose Commit again.

   The Dockerfile is added to your repository.

To add the taskdef.json file

1. In your source repository, choose Create file.

2. For File name, enter:

   taskdef.json

3. In the text box, enter the following code:

   {
       "executionRoleArn": "arn:aws:iam::account_ID:role/codecatalyst-ecs-task-execution-role",
       "containerDefinitions": [
           {
               "name": "codecatalyst-ecs-container",
               # The $REPOSITORY_URI and $IMAGE_TAG variables will be replaced 
               # by the workflow at build time (see the build action in the 
               # workflow)
               "image": $REPOSITORY_URI:$IMAGE_TAG,
               "essential": true,
               "portMappings": [
                   {
                       "hostPort": 80,
                       "protocol": "tcp",
                       "containerPort": 80
                   }
               ]
           }
       ],
       "requiresCompatibilities": [
           "FARGATE"
       ],
       "networkMode": "awsvpc",
       "cpu": "256",
       "memory": "512",
       "family": "codecatalyst-ecs-task-def"
   }

   In the preceding code, replace

   arn:aws:iam::account_ID:role/codecatalyst-ecs-task-execution-role

   with the ARN of the task execution role that you noted in To create the task execution role.

4. Choose Commit, and then choose Commit again.

   The taskdef.json file is added to your repository.

To create a workflow

1. In the CodeCatalyst console, in the navigation pane, choose CI/CD, and then choose Workflows.

2. Choose Create workflow.

3. For Source repository, choose codecatalyst-ecs-source-repository.

4. For Branch, choose main.

5. Choose Create.

6. Delete the YAML sample code.

7. Add the following YAML code:

   Note

   In the YAML code that follows, you can omit the Connections: sections if you want. If you omit these sections, you must ensure that the role specified in the Default IAM role field in your environment includes the permissions and trust policies of both roles described in Step 5: Add AWS roles to CodeCatalyst. For more information about setting up an environment with a default IAM role, see Creating an environment.

   Name: codecatalyst-ecs-workflow
   SchemaVersion: 1.0
   
   Triggers:
     - Type: PUSH
       Branches:
         - main
   Actions:
     BuildBackend:
       Identifier: aws/build@v1
       Environment:
         Name: codecatalyst-ecs-environment
         Connections:
           - Name: codecatalyst-account-connection
             Role: codecatalyst-ecs-build-role
       Inputs:
         Sources:
           - WorkflowSource
         Variables:
           - Name: REPOSITORY_URI
             Value: 111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-ecs-image-repo
           - Name: IMAGE_TAG
             Value: ${WorkflowSource.CommitId}
       Configuration:
         Steps:
           #pre_build:
           - Run: echo Logging in to Amazon ECR...
           - Run: aws --version
           - Run: aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-west-2.amazonaws.com
           #build:
           - Run: echo Build started on `date`
           - Run: echo Building the Docker image...
           - Run: docker build -t $REPOSITORY_URI:latest .
           - Run: docker tag $REPOSITORY_URI:latest $REPOSITORY_URI:$IMAGE_TAG
           #post_build:
           - Run: echo Build completed on `date`
           - Run: echo Pushing the Docker images...
           - Run: docker push $REPOSITORY_URI:latest
           - Run: docker push $REPOSITORY_URI:$IMAGE_TAG
           # Replace the variables in taskdef.json
           - Run: find taskdef.json -type f | xargs sed -i "s|\$REPOSITORY_URI|$REPOSITORY_URI|g"
           - Run: find taskdef.json -type f | xargs sed -i "s|\$IMAGE_TAG|$IMAGE_TAG|g"
           - Run: cat taskdef.json
           # The output artifact will be a zip file that contains a task definition file.
       Outputs:
         Artifacts:
           - Name: TaskDefArtifact
             Files: 
               - taskdef.json
     DeployToECS:
       DependsOn: 
         - BuildBackend
       Identifier: aws/ecs-deploy@v1
       Environment:
         Name: codecatalyst-ecs-environment
         Connections:
           - Name: codecatalyst-account-connection
             Role: codecatalyst-ecs-deploy-role
       Inputs:
         Sources: []
         Artifacts:
           - TaskDefArtifact
       Configuration:
         region: us-west-2
         cluster: codecatalyst-ecs-cluster
         service: codecatalyst-ecs-service
         task-definition: taskdef.json

   In the preceding code, replace:

   • Both instances of codecatalyst-ecs-environment with the name of the environment you created in Prerequisites.

   • Both instances of codecatalyst-account-connection with the display name of your account connection. The display name might be a number. For more information, see Step 5: Add AWS roles to CodeCatalyst.

   • codecatalyst-ecs-build-role with the name of the build role you created in Step 4: Create AWS roles.

   • 111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-ecs-image-repo (in the Value: property) with the URI of the Amazon ECR repository you created in Step 3: Create an Amazon ECR image repository.

   • 111122223333.dkr.ecr.us-west-2.amazonaws.com (in the Run: aws ecr command) with the URI of the Amazon ECR repository without the image suffix (/codecatalyst-ecs-image-repo).

   • codecatalyst-ecs-deploy-role with the name of the deploy role you created in Step 4: Create AWS roles.

   • Both instances of us-west-2 with your AWS Region code. For a list of Region codes, see Regional endpoints in the AWS General Reference.

   Note

   If you decided not to create build and deploy roles, replace codecatalyst-ecs-build-role and codecatalyst-ecs-deploy-role with the name of the CodeCatalystWorkflowDevelopmentRole-spaceName role. For more information about this role, see Step 4: Create AWS roles.

   Tip

   Instead of using the find and sed commands shown in the previous workflow code to update the repository and image name, you can use the Render Amazon ECS task definition action for this purpose. For more information, see Modifying an Amazon ECS task definition.

8. (Optional) Choose Validate to make sure that the YAML code is valid before committing.

9. Choose Commit.

10. In the Commit workflow dialog box, enter the following:

    1. For Commit message, remove the text and enter:

       Add first workflow

    2. For Repository, choose codecatalyst-ecs-source-repository.

    3. For Branch name, choose main.

    4. Choose Commit.

    You have now created a workflow. A workflow run starts automatically because of the trigger defined at the top of the workflow. Specifically, when you committed (and pushed) the workflow.yaml file to your source repository, the trigger started the workflow run.

To view the workflow run progress

1. In the navigation pane of the CodeCatalyst console, choose CI/CD, and then choose Workflows.

2. Choose the workflow you just created, codecatalyst-ecs-workflow.

3. Choose BuildBackend to see the build progress.

4. Choose DeployToECS to see the deployment progress.

   For more information about viewing run details, see Viewing workflow run status and details.

To verify the deployment

1. Open the Amazon ECS classic console at https://console.aws.amazon.com/ecs/.

2. Choose your cluster, codecatalyst-ecs-cluster.

3. Choose the Tasks tab.

4. Choose any one of the three tasks.

5. In the Public IP field, choose open address.

   A "Hello World" page appears in the browser, indicating that the Amazon ECS service successfully deployed your application.

To change the index.html

1. In the CodeCatalyst console, in the navigation pane, choose Code, then choose Source repositories, and then choose your repository, codecatalyst-ecs-source-repository.

2. Choose public-html, and then choose index.html.

   The contents of index.html appear.

3. Choose Edit.

4. On line 14, change the Hello World text to Tutorial complete!.

5. Choose Commit, and then choose Commit again.

   The commit causes a new workflow run to start.

6. (Optional) Go to your source repository's main page, choose View commits, and then note the commit ID for the index.html change.

7. Watch the deployment progress:

   1. In the navigation pane, choose CI/CD, and then choose Workflows.

   2. Choose codecatalyst-ecs-workflow to view the latest run.

   3. Choose BuildBackend, and DeployToECS to see the workflow run progress.

8. Verify that your application was updated, as follows:

   1. Open the Amazon ECS classic console at https://console.aws.amazon.com/ecs/.

   2. Choose your cluster, codecatalyst-ecs-cluster.

   3. Choose the Tasks tab.

   4. Choose any one of the three tasks.

   5. In the Public IP field, choose open address.

      A Tutorial complete! page appears.

9. (Optional) In AWS, switch to the Amazon ECR console and verify that the new Docker image was tagged with the commit ID from step 6.