Capstone: a three-stage release pipeline with CodePipeline and CodeBuild

Steps

1. Write the application. In CloudShell, make a working folder and a one-line release note:

mkdir -p clf-lab22 && cd clf-lab22
echo 'clf-lab22 release notes. Version 1' > release.txt

Then create buildspec.yml, the instructions CodeBuild follows. Open it with nano buildspec.yml, paste the text below, and save it (Ctrl+O, Enter, Ctrl+X):

version: 0.2
phases:
  build:
    commands:
      - grep -q Version release.txt
      - mkdir -p out
      - cp release.txt out/release.txt
      - date -u > out/built-at.txt
artifacts:
  base-directory: out
  files:
    - '**/*'

The grep line is the test: the build fails if the release note does not contain the word Version. The rest packages the note and a build time into the artefact. Zip both files:

zip app.zip buildspec.yml release.txt

2. Write the infrastructure as a CloudFormation template. Open nano clf-lab22-pipeline.yaml, paste the template below and save it. If pasting into nano spoils the indentation, write the file on your computer instead and upload it with CloudShell's Actions, then Upload file, and move it into the folder with mv ~/clf-lab22-pipeline.yaml .

AWSTemplateFormatVersion: '2010-09-09'
Description: clf-lab22 capstone, a three-stage release pipeline
Resources:
  SourceBucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Sub 'clf-lab22-source-${AWS::AccountId}'
      VersioningConfiguration:
        Status: Enabled
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true
  ArtifactBucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Sub 'clf-lab22-artifacts-${AWS::AccountId}'
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true
  BuildLogs:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: /aws/codebuild/clf-lab22-build
      RetentionInDays: 1
  BuildRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: clf-lab22-codebuild-role
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: codebuild.amazonaws.com
            Action: sts:AssumeRole
      Policies:
        - PolicyName: clf-lab22-codebuild-policy
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Effect: Allow
                Action:
                  - logs:CreateLogStream
                  - logs:PutLogEvents
                Resource: !GetAtt BuildLogs.Arn
              - Effect: Allow
                Action:
                  - s3:GetObject
                  - s3:GetObjectVersion
                  - s3:PutObject
                Resource: !Sub '${ArtifactBucket.Arn}/*'
              - Effect: Allow
                Action:
                  - s3:GetBucketLocation
                  - s3:GetBucketAcl
                Resource: !GetAtt ArtifactBucket.Arn
  BuildProject:
    Type: AWS::CodeBuild::Project
    Properties:
      Name: clf-lab22-build
      ServiceRole: !GetAtt BuildRole.Arn
      TimeoutInMinutes: 10
      Source:
        Type: CODEPIPELINE
      Artifacts:
        Type: CODEPIPELINE
      Environment:
        Type: LINUX_CONTAINER
        ComputeType: BUILD_GENERAL1_SMALL
        Image: aws/codebuild/amazonlinux2-x86_64-standard:5.0
      LogsConfig:
        CloudWatchLogs:
          Status: ENABLED
          GroupName: !Ref BuildLogs
  PipelineRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: clf-lab22-pipeline-role
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: codepipeline.amazonaws.com
            Action: sts:AssumeRole
      Policies:
        - PolicyName: clf-lab22-pipeline-policy
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Effect: Allow
                Action:
                  - s3:GetObject
                  - s3:GetObjectVersion
                  - s3:PutObject
                  - s3:PutObjectAcl
                Resource:
                  - !Sub '${SourceBucket.Arn}/*'
                  - !Sub '${ArtifactBucket.Arn}/*'
              - Effect: Allow
                Action:
                  - s3:GetBucketVersioning
                  - s3:GetBucketLocation
                  - s3:ListBucket
                Resource:
                  - !GetAtt SourceBucket.Arn
                  - !GetAtt ArtifactBucket.Arn
              - Effect: Allow
                Action:
                  - codebuild:StartBuild
                  - codebuild:BatchGetBuilds
                Resource: !GetAtt BuildProject.Arn
  Pipeline:
    Type: AWS::CodePipeline::Pipeline
    Properties:
      Name: clf-lab22-pipeline
      PipelineType: V2
      RoleArn: !GetAtt PipelineRole.Arn
      ArtifactStore:
        Type: S3
        Location: !Ref ArtifactBucket
      Stages:
        - Name: Source
          Actions:
            - Name: Source
              ActionTypeId:
                Category: Source
                Owner: AWS
                Provider: S3
                Version: '1'
              Configuration:
                S3Bucket: !Ref SourceBucket
                S3ObjectKey: app.zip
                PollForSourceChanges: 'false'
              OutputArtifacts:
                - Name: SourceOutput
        - Name: Build
          Actions:
            - Name: Build
              ActionTypeId:
                Category: Build
                Owner: AWS
                Provider: CodeBuild
                Version: '1'
              Configuration:
                ProjectName: !Ref BuildProject
              InputArtifacts:
                - Name: SourceOutput
              OutputArtifacts:
                - Name: BuildOutput
        - Name: Deploy
          Actions:
            - Name: Deploy
              ActionTypeId:
                Category: Deploy
                Owner: AWS
                Provider: S3
                Version: '1'
              Configuration:
                BucketName: !Ref ArtifactBucket
                Extract: 'true'
                ObjectKey: release
              InputArtifacts:
                - Name: BuildOutput

Read it before you deploy it: two private buckets, a log group, a build project, a pipeline with three stages, and two roles whose policies name only the buckets, the log group and the project they need. Nothing in it is public. 3. Deploy the template as a stack. CAPABILITY_NAMED_IAM is your explicit consent to it creating named IAM roles:

aws cloudformation deploy --template-file clf-lab22-pipeline.yaml --stack-name clf-lab22-stack --capabilities CAPABILITY_NAMED_IAM
aws cloudformation describe-stacks --stack-name clf-lab22-stack --query 'Stacks[0].StackStatus' --output text

The second command prints CREATE_COMPLETE. A new pipeline runs once by itself as soon as it exists, and this first run fails at the Source stage because app.zip is not in the bucket yet. That is expected; open the CodePipeline console and see that it shows exactly which stage failed. 4. Release version 1. Upload the zip to the source bucket and start the pipeline:

aws s3 cp app.zip s3://clf-lab22-source-111122223333/app.zip
aws codepipeline start-pipeline-execution --name clf-lab22-pipeline

Watch it move through the stages, re-running this every 20 seconds or so:

aws codepipeline get-pipeline-state --name clf-lab22-pipeline --query 'stageStates[].[stageName,latestExecution.status]' --output table

After a few minutes Source, Build and Deploy all read Succeeded. List the release:

aws s3 ls s3://clf-lab22-artifacts-111122223333/release/

It lists built-at.txt and release.txt. CodePipeline orchestrated the release; CodeBuild did the building. 5. Release a broken version. Change the release note so that it fails the test, rebuild the zip, upload it and start the pipeline again:

echo 'clf-lab22 release notes, draft' > release.txt
rm -f app.zip && zip app.zip buildspec.yml release.txt
aws s3 cp app.zip s3://clf-lab22-source-111122223333/app.zip
aws codepipeline start-pipeline-execution --name clf-lab22-pipeline

Watch the stages with the get-pipeline-state command from step 4. Source succeeds, Build reads Failed, and Deploy never runs, so the release folder still holds version 1. This is continuous integration doing its job: a bad change stopped at the build, not in front of users. 6. Find out why, from the build log in CloudWatch Logs:

aws logs tail /aws/codebuild/clf-lab22-build --since 15m

Near the end the log shows the grep -q Version release.txt command and that it did not exit successfully. The same log is linked from the failed build in the CodeBuild console, under Build history. A request that is slow across several services would need AWS X-Ray to trace it; a failed build needs only its log. 7. Release the fix:

echo 'clf-lab22 release notes. Version 2' > release.txt
rm -f app.zip && zip app.zip buildspec.yml release.txt
aws s3 cp app.zip s3://clf-lab22-source-111122223333/app.zip
aws codepipeline start-pipeline-execution --name clf-lab22-pipeline

When all three stages read Succeeded again, the release folder holds version 2. Because the source bucket is versioned, all three uploads of app.zip are still kept, which is how CodePipeline knows exactly which version each run used. 8. Open the CodePipeline console and choose clf-lab22-pipeline. The page draws the three stages and the latest run through them; Execution history lists every run, including the first failed Source run and the failed build. Then open the CodeBuild console, choose the project clf-lab22-build and look at Build history: one failed build between two that succeeded.