Docker samples for CodeBuild

To run this sample

1. Create the files as described in the "Directory structure" and "Files" sections of this topic, and then upload them to an S3 input bucket or an Amazon CodeCommit, GitHub, or Bitbucket repository.

   Important

   Do not upload (root directory name), just the files inside of (root directory name).

   If you are using an S3 input bucket, be sure to create a ZIP file that contains the files, and then upload it to the input bucket. Do not add (root directory name) to the ZIP file, just the files inside of (root directory name).

2. Create a build project, run the build, and view related build information.

   If you use the Amazon CLI to create the build project, the JSON-formatted input to the create-project command might look similar to this. (Replace the placeholders with your own values.)

   {
     "name": "sample-docker-custom-image-project",
     "source": {
       "type": "S3",
       "location": "codebuild-region-ID-account-ID-input-bucket/DockerCustomImageSample.zip"
     },
     "artifacts": {
       "type": "NO_ARTIFACTS"
     },
     "environment": {
       "type": "LINUX_CONTAINER",
       "image": "docker:dind",
       "computeType": "BUILD_GENERAL1_SMALL",
       "privilegedMode": false
     },
     "serviceRole": "arn:aws:iam::account-ID:role/role-name",
     "encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID"
   }

   Note

   By default, Docker daemon is enabled for non-VPC builds. If you would like to use Docker containers for VPC builds, see Runtime Privilege and Linux Capabilities on the Docker Docs website and enable privileged mode. Also, Windows does not support privileged mode.

3. To see the build results, look in the build's log for the string Hello, World!. For more information, see View build details.

To run this sample

1. If you already have an image repository in Amazon ECR you want to use, skip to step 3. Otherwise, if you are using an user instead of an Amazon root account or an administrator user to work with Amazon ECR, add this statement (between ### BEGIN ADDING STATEMENT HERE ### and ### END ADDING STATEMENT HERE ###) to the user (or IAM group the user is associated with). Using an Amazon root account is not recommended.This statement allows the creation of Amazon ECR repositories for storing Docker images. Ellipses (...) are used for brevity and to help you locate where to add the statement. Do not remove any statements, and do not type these ellipses into the policy. For more information, see Working with inline policies using the Amazon Web Services Management Console in the user Guide.

   {
     "Statement": [
       ### BEGIN ADDING STATEMENT HERE ###
       {
         "Action": [
           "ecr:CreateRepository"
         ],
         "Resource": "*",
         "Effect": "Allow"
       },
       ### END ADDING STATEMENT HERE ###
       ...
     ],
     "Version": "2012-10-17"
   }

   Note

   The IAM entity that modifies this policy must have permission in IAM to modify policies.

2. Create an image repository in Amazon ECR. Be sure to create the repository in the same Amazon Region where you create your build environment and run your build. For more information, see Creating a repository in the Amazon ECR User Guide. This repository's name must match the repository name you specify later in this procedure, represented by the IMAGE_REPO_NAME environment variable. Ensure that the Amazon ECR repository policy grants image push access for your CodeBuild service IAM role.

3. Add this statement (between ### BEGIN ADDING STATEMENT HERE ### and ### END ADDING STATEMENT HERE ###) to the policy you attached to your Amazon CodeBuild service role. This statement allows CodeBuild to upload Docker images to Amazon ECR repositories. Ellipses (...) are used for brevity and to help you locate where to add the statement. Do not remove any statements, and do not type these ellipses into the policy.

   {
     "Statement": [
       ### BEGIN ADDING STATEMENT HERE ###
       {
         "Action": [
           "ecr:BatchCheckLayerAvailability",
           "ecr:CompleteLayerUpload",
           "ecr:GetAuthorizationToken",
           "ecr:InitiateLayerUpload",
           "ecr:PutImage",
           "ecr:UploadLayerPart"
         ],
         "Resource": "*",
         "Effect": "Allow"
       },
       ### END ADDING STATEMENT HERE ###
       ...
     ],
     "Version": "2012-10-17"
   }

   Note

   The IAM entity that modifies this policy must have permission in IAM to modify policies.

4. Create the files as described in the "Directory structure" and "Files" sections of this topic, and then upload them to an S3 input bucket or an Amazon CodeCommit, GitHub, or Bitbucket repository. For more information, see Image definitions file reference in the Amazon CodePipeline User Guide.

   Important

   Do not upload (root directory name), just the files inside of (root directory name).

   If you are using an S3 input bucket, be sure to create a ZIP file that contains the files, and then upload it to the input bucket. Do not add (root directory name) to the ZIP file, just the files inside of (root directory name).

5. Create a build project, run the build, and view build information.

   If you use the console to create your project:

   1. For Operating system, choose Ubuntu.

   2. For Runtime, choose Standard.

   3. For Image, choose aws/codebuild/standard:5.0.

   4. Add the following environment variables:

      • AWS_DEFAULT_REGION with a value of region-ID

      • AWS_ACCOUNT_ID with a value of account-ID

      • IMAGE_TAG with a value of Latest

      • IMAGE_REPO_NAME with a value of Amazon-ECR-repo-name

   If you use the Amazon CLI to create the build project, the JSON-formatted input to the create-project command might look similar to this. (Replace the placeholders with your own values.)

   {
     "name": "sample-docker-project",
     "source": {
       "type": "S3",
       "location": "codebuild-region-ID-account-ID-input-bucket/DockerSample.zip"
     },
     "artifacts": {
       "type": "NO_ARTIFACTS"
     },
     "environment": {
       "type": "LINUX_CONTAINER",
       "image": "aws/codebuild/standard:5.0",
       "computeType": "BUILD_GENERAL1_SMALL",
       "environmentVariables": [
         {
           "name": "AWS_DEFAULT_REGION",
           "value": "region-ID"
         },
         {
           "name": "AWS_ACCOUNT_ID",
           "value": "account-ID"
         },
         {
           "name": "IMAGE_REPO_NAME",
           "value": "Amazon-ECR-repo-name"
         },
         {
           "name": "IMAGE_TAG",
           "value": "latest"
         }
       ],
     },
     "serviceRole": "arn:aws:iam::account-ID:role/role-name",
     "encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID"
   }

6. Confirm that CodeBuild successfully pushed the Docker image to the repository:

   1. Open the Amazon ECR console at https://console.amazonaws.cn/ecr/.

   2. Choose the repository name. The image should be listed in the Image tag column.

1. Replace these Amazon ECR-specific lines of code in the buildspec.yml file:

   ...
     pre_build:
       commands:
         - echo Logging in to Amazon ECR...
         - aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username Amazon --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com
     build:
       commands:
         - echo Build started on `date`
         - echo Building the Docker image...          
         - docker build -t $IMAGE_REPO_NAME:$IMAGE_TAG .
         - docker tag $IMAGE_REPO_NAME:$IMAGE_TAG $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG
     post_build:
       commands:
         - echo Build completed on `date`
         - echo Pushing the Docker image...
         - docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG
   ...

   With these Docker Hub-specific lines of code:

   ...
     pre_build:
       commands:
         - echo Logging in to Docker Hub...
         # Type the command to log in to your Docker Hub account here.          
     build:
       commands:
         - echo Build started on `date`
         - echo Building the Docker image...
         - docker build -t $IMAGE_REPO_NAME:$IMAGE_TAG .
         - docker tag $IMAGE_REPO_NAME:$IMAGE_TAG $IMAGE_REPO_NAME:$IMAGE_TAG
     post_build:
       commands:
         - echo Build completed on `date`
         - echo Pushing the Docker image...
         - docker push $IMAGE_REPO_NAME:$IMAGE_TAG
   ...

2. Upload the edited code to an S3 input bucket or an Amazon CodeCommit, GitHub, or Bitbucket repository.

   Important

   Do not upload (root directory name), just the files inside of (root directory name).

   If you are using an S3 input bucket, be sure to create a ZIP file that contains the files, and then upload it to the input bucket. Do not add (root directory name) to the ZIP file, just the files inside of (root directory name).

3. Replace these lines of code from the JSON-formatted input to the create-project command:

   ...
       "environmentVariables": [
         {
           "name": "AWS_DEFAULT_REGION",
           "value": "region-ID"
         },
         {
           "name": "AWS_ACCOUNT_ID",
           "value": "account-ID"
         },
         {
           "name": "IMAGE_REPO_NAME",
           "value": "Amazon-ECR-repo-name"
         },
         {
           "name": "IMAGE_TAG",
           "value": "latest"
         }
       ]
   ...

   With these lines of code:

   ...
       "environmentVariables": [
         {
           "name": "IMAGE_REPO_NAME",
           "value": "your-Docker-Hub-repo-name"
         },
         {
           "name": "IMAGE_TAG",
           "value": "latest"
         }
       ]
   ...

4. Create a build environment, run the build, and view related build information.

5. Confirm that Amazon CodeBuild successfully pushed the Docker image to the repository. Sign in to Docker Hub, go to the repository, and choose the Tags tab. The latest tag should contain a very recent Last Updated value.

1. For information about how to create a free private repository, see Repositories on Docker Hub. You can also run the following commands in a terminal to pull an image, get its ID, and push it to a new repository.

   docker pull amazonlinux
   docker images amazonlinux --format {{.ID}}
   docker tag image-id your-username/repository-name:tag
   docker login
   docker push your-username/repository-name

2. Follow the steps in Create an Amazon Secrets Manager secret in the Amazon Secrets Manager User Guide.

   1. In step 3, in Choose secret type, choose Other type of secret.

   2. In Key/value pairs, create one key-value pair for your Docker Hub user name and one key-value pair for your Docker Hub password.

   3. Continue following the steps in Create an Amazon Secrets Manager secret.

   4. In step 5, on the Configure automatic rotation page, turn it off because the keys correspond to your Docker Hub credentials.

   5. Finish following the steps in Create an Amazon Secrets Manager secret.

   For more information, see What is Amazon Secrets Manager?

3. When you create an Amazon CodeBuild project in the console, CodeBuild attaches the required permission for you. If you use an Amazon KMS key other than DefaultEncryptionKey, you must add it to the service role. For more information, see Modifying a role (console) in the IAM User Guide.

   For your service role to work with Secrets Manager, it must have, at a minimum, the secretsmanager:GetSecretValue permission.

   

4. To use the console to create a project with an environment stored in a private registry, do the following while you create a project. For information, see Create a build project (console).

   Note

   If your private registry is in your VPC, it must have public internet access. CodeBuild cannot pull an image from a private IP address in a VPC.

   1. In Environment image, choose Custom image.

   2. For Environment type, choose Linux or Windows.

   3. For Image registry, choose Other registry.

   4. In External registry URL, enter the image location and in Registry credential - optional enter the ARN or name of your Secrets Manager credentials.

      Note

      If your credentials do not exist in your current Region, then you must use the ARN. You cannot use the credential name if the credentials exist in a different Region.