Menu
Amazon Elastic Container Service
Developer Guide (API Version 2014-11-13)

Tutorial: Continuous Deployment with AWS CodePipeline

This tutorial helps you to create a complete, end-to-end continuous deployment (CD) pipeline with Amazon ECS with AWS CodePipeline.

Prerequisites

There are a few resources that you must have in place before you can use this tutorial to create your CD pipeline. Here are the things you need to get started:

Note

All of these resources should be created within the same AWS Region.

  • A source control repository (this tutorial uses AWS CodeCommit) with your Dockerfile and application source. For more information, see Create an AWS CodeCommit Repository in the AWS CodeCommit User Guide.

  • A Docker image repository (this tutorial uses Amazon ECR) that contains an image you have built from your Dockerfile and application source. For more information, see Creating a Repository and Pushing an Image in the Amazon Elastic Container Registry User Guide.

  • An Amazon ECS task definition that references the Docker image hosted in your image repository. For more information, see Creating a Task Definition in the Amazon Elastic Container Service Developer Guide.

  • An Amazon ECS cluster that is running a service that uses your previously mentioned task definition. For more information, see Creating a Cluster and Creating a Service in the Amazon Elastic Container Service Developer Guide.

After you have satisfied these prerequisites, you can proceed with the tutorial and create your CD pipeline.

Step 1: Add a Build Specification File to Your Source Repository

This tutorial uses AWS CodeBuild to build your Docker image and push the image to Amazon ECR. Add a buildspec.yml file to your source code repository to tells AWS CodeBuild how to do that. The example build specification below does the following:

  • Pre-build stage:

    • Log in to Amazon ECR.

    • Set the repository URI to your ECR image and add an image tag with the first seven characters of the Git commit ID of the source.

  • Build stage:

    • Build the Docker image and tag the image both as latest and with the Git commit ID.

  • Post-build stage:

    • Push the image to your ECR repository with both tags.

    • Write a file called imagedefinitions.json in the build root that has your Amazon ECS service's container name and the image and tag. The deployment stage of your CD pipeline uses this information to create a new revision of your service's task definition, and then it updates the service to use the new task definition. The imagedefinitions.json file is required for the AWS CodeDeploy ECS job worker.

version: 0.2 phases: pre_build: commands: - echo Logging in to Amazon ECR... - aws --version - $(aws ecr get-login --region $AWS_DEFAULT_REGION --no-include-email) - REPOSITORY_URI=012345678910.dkr.ecr.us-west-2.amazonaws.com/hello-world - COMMIT_HASH=$(echo $CODEBUILD_RESOLVED_SOURCE_VERSION | cut -c 1-7) - IMAGE_TAG=${COMMIT_HASH:=latest} build: commands: - echo Build started on `date` - echo Building the Docker image... - docker build -t $REPOSITORY_URI:latest . - docker tag $REPOSITORY_URI:latest $REPOSITORY_URI:$IMAGE_TAG post_build: commands: - echo Build completed on `date` - echo Pushing the Docker images... - docker push $REPOSITORY_URI:latest - docker push $REPOSITORY_URI:$IMAGE_TAG - echo Writing image definitions file... - printf '[{"name":"hello-world","imageUri":"%s"}]' $REPOSITORY_URI:$IMAGE_TAG > imagedefinitions.json artifacts: files: imagedefinitions.json

The build specification was written for the following task definition, used by the Amazon ECS service for this tutorial. The REPOSITORY_URI value corresponds to the image repository (without any image tag), and the hello-world value near the end of the file corresponds to the container name in the service's task definition.

{ "taskDefinition": { "family": "hello-world", "containerDefinitions": [ { "name": "hello-world", "image": "012345678910.dkr.ecr.us-west-2.amazonaws.com/hello-world:6a57b99", "cpu": 100, "portMappings": [ { "protocol": "tcp", "containerPort": 80, "hostPort": 80 } ], "memory": 128, "essential": true } ] } }

To add a buildspec.yml file to your source repository

  1. Open a text editor and then copy and paste the build specification above into a new file.

  2. Replace the REPOSITORY_URI value (012345678910.dkr.ecr.us-west-2.amazonaws.com/hello-world) with your Amazon ECR repository URI (without any image tag) for your Docker image. Replace hello-world with the container name in your service's task definition that references your Docker image.

  3. Commit and push your buildspec.yml file to your source repository.

    1. Add the file.

      git add .
    2. Commit the change.

      git commit -m "Adding build specification."
    3. Push the commit.

      git push

Step 2: Creating Your Continuous Deployment Pipeline

Use the AWS CodePipeline wizard to create your pipeline stages and connect your source repository to your ECS service.

To create your pipeline

  1. Open the AWS CodePipeline console at https://console.aws.amazon.com/codepipeline/.

  2. On the Welcome page, choose Create pipeline.

    If this is your first time using AWS CodePipeline, an introductory page appears instead of Welcome. Choose Get Started Now.

  3. On the Step 1: Name page, for Pipeline name, type the name for your pipeline and choose Next step. For this tutorial, the pipeline name is hello-world.

  4. On the Step 2: Source page, for Source provider, choose AWS CodeCommit.

    1. For Repository name, choose the name of the AWS CodeCommit repository to use as the source location for your pipeline.

    2. For Branch name, choose the branch to use and choose Next step.

  5. On the Step 3: Build page, choose AWS CodeBuild, and then choose Create a new build project.

    1. For Project name, choose a unique name for your build project. For this tutorial, the project name is hello-world.

    2. For Operating system, choose Ubuntu.

    3. For Runtime, choose Docker.

    4. For Version, choose aws/codebuild/docker:17.09.0 .

    5. Choose Save build project.

    6. Choose Next step.

      Note

      The wizard creates an AWS CodeBuild service role for your build project, called code-build-build-project-name-service-role. Note this role name, as you add Amazon ECR permissions to it later.

  6. On the Step 4: Deploy page, for Deployment provider, choose Amazon ECS.

    1. For Cluster name, choose the Amazon ECS cluster in which your service is running. For this tutorial, the cluster is default.

    2. For Service name, choose the service to update and choose Next step. For this tutorial, the service name is hello-world.

  7. On the Step 5: Service Role page, choose Create role. On the IAM console page that describes the role to be created for you, choose Allow.

  8. Choose Next step.

  9. On the Step 6: Review page, review your pipeline configuration and choose Create pipeline to create the pipeline.

    Note

    Now that the pipeline has been created, it attempts to run through the different pipeline stages. However, the default AWS CodeBuild role created by the wizard does not have permissions to execute all of the commands contained in the buildspec.yml file, so the build stage fails. The next section adds the permissions for the build stage.

Step 3: Add Amazon ECR Permissions to the AWS CodeBuild Role

The AWS CodePipeline wizard created an IAM role for the AWS CodeBuild build project, called code-build-build-project-name-service-role. For this tutorial, the name is code-build-hello-world-service-role. Because the buildspec.yml file makes calls to Amazon ECR API operations, the role must have a policy that allows permissions to make these Amazon ECR calls. The following procedure helps you attach the proper permissions to the role.

To add Amazon ECR permissions to the AWS CodeBuild role

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the left navigation pane, choose Roles.

  3. In the search box, type code-build- and choose the role that was created by the AWS CodePipeline wizard. For this tutorial, the role name is code-build-hello-world-service-role.

  4. On the Summary page, choose Attach policy.

  5. Select the box to the left of the AmazonEC2ContainerRegistryPowerUser policy, and choose Attach policy.

Step 4: Test Your Pipeline

Your pipeline should have everything for running an end-to-end native AWS continuous deployment. Now, test its functionality by pushing a code change to your source repository.

To test your pipeline

  1. Make a code change to your configured source repository, commit, and push the change.

  2. Open the AWS CodePipeline console at https://console.aws.amazon.com/codepipeline/.

  3. Choose your pipeline from the list.

  4. Watch the pipeline progress through its stages. Your pipeline should complete and your Amazon ECS service runs the Docker image that was created from your code change.

    
                        AWS CodePipeline completed