Topics

• Step 1: Create an S3 source bucket for your application

• Step 2: Create Amazon EC2 Windows instances and install the CodeDeploy agent

• Step 3: Create an application in CodeDeploy

• Step 4: Create your first pipeline in CodePipeline

• (Optional) Step 5: Add another stage to your pipeline

• (Optional) Step 6: Disable and enable transitions between stages in CodePipeline

• Step 7: Clean up resources

To create an S3 bucket

1. Sign in to the console at AWS Management Console. Open the S3 console.

2. ChooseCreate bucket.

3. InBucket name, enter a name for your bucket (for example,awscodepipeline-demobucket-example-date).

   Note

   Because all bucket names in Amazon S3 must be unique, use one of your own, not the name shown in the example. You can change the example name just by adding the date to it. Make a note of this name because you need it for the rest of this tutorial.

   InRegion, choose the Region where you intend to create your pipeline, such asUS West (Oregon), and then chooseCreate bucket.

4. After the bucket is created, a success banner displays. ChooseGo to bucket details.

5. On theProperties tab, chooseVersioning. ChooseEnable versioning, and then chooseSave.

   When versioning is enabled, Amazon S3 saves every version of every object in the bucket.

6. On thePermissions tab, leave the defaults. For more information about S3 bucket and object permissions, seeSpecifying Permissions in a Policy.

7. Next, download a sample and save it into a folder or directory on your local computer.

   1. Choose one of the following. ChooseSampleApp_Windows.zip if you want to follow the steps in this tutorial for Windows Server instances.

      • If you want to deploy to Amazon Linux instances using CodeDeploy, download the sample application here:SampleApp_Linux.zip.

      • If you want to deploy to Windows Server instances using CodeDeploy, download the sample application here:SampleApp_Windows.zip.

      The sample application contains the following files for deploying with CodeDeploy:

      • appspec.yml – The application specification file (AppSpec file) is aYAML-formatted file used by CodeDeploy to manage a deployment. For more information about the AppSpec file, seeCodeDeploy AppSpec File reference in theAWS CodeDeploy User Guide.

      • index.html – The index file contains the home page for the deployed sample application.

      • LICENSE.txt – The license file contains license information for the sample application.

      • Files for scripts – The sample application uses scripts to write text files to a location on your instance. One file is written for each of several CodeDeploy deployment lifecycle events as follows:

        • (Linux sample only)scripts folder – The folder contains the following shell scripts to install dependencies and start and stop the sample application for the automated deployment:install_dependencies,start_server, andstop_server.

        • (Windows sample only)before-install.bat – This is a batch script for theBeforeInstall deployment lifecycle event, which will run to remove old files written during previous deployments of this sample and create a location on your instance to which to write the new files.

   2. Download the compressed (zipped) file. Do not unzip the file.

8. In the Amazon S3 console, for your bucket, upload the file:

   1. ChooseUpload.

   2. Drag and drop the file or chooseAdd files and browse for the file.

   3. ChooseUpload.

To create an instance role

1. Open the IAM console athttps://console.aws.amazon.com/iam/).

2. From the console dashboard, chooseRoles.

3. ChooseCreate role.

4. UnderSelect type of trusted entity, selectAWS service. UnderChoose a use case, selectEC2, and then chooseNext: Permissions.

5. Search for and select the policy namedAmazonEC2RoleforAWSCodeDeploy.

6. Search for and select the policy namedAmazonSSMManagedInstanceCore. ChooseNext: Tags.

7. ChooseNext: Review. Enter a name for the role (for example,EC2InstanceRole).

   Note

   Make a note of your role name for the next step. You choose this role when you are creating your instance.

   ChooseCreate role.

To launch instances

1. Open the Amazon EC2 console athttps://console.aws.amazon.com/ec2/.

2. From the side navigation, chooseInstances, and selectLaunch instances from the top of the page.

3. UnderName and tags, inName, enterMyCodePipelineDemo. This assigns the instances a tagKey ofName and a tagValue ofMyCodePipelineDemo. Later, you create a CodeDeploy application that deploys the sample application to the instances. CodeDeploy selects instances to deploy based on the tags.

4. UnderApplication and OS Images (Amazon Machine Image), choose theWindows option. (This AMI is described as theMicrosoft Windows Server 2019 Base and is labeled "Free tier eligible" and can be found underQuick Start..)

5. UnderInstance type, choose the free tier eligiblet2.micro type as the hardware configuration for your instance.

6. UnderKey pair (login), choose a key pair or create one.

   You can also chooseProceed without a key pair.

   Note

   For the purposes of this tutorial, you can proceed without a key pair. To use SSH to connect to your instances, create or use a key pair.

7. UnderNetwork settings, do the following.

   InAuto-assign Public IP, make sure the status isEnable.

   • Next toAssign a security group, chooseCreate a new security group.

   • In the row forSSH, underSource type, chooseMy IP.

   • ChooseAdd security group, chooseHTTP, and then underSource type, chooseMy IP.

8. ExpandAdvanced details. InIAM instance profile, choose the IAM role you created in the previous procedure (for example,EC2InstanceRole).

9. UnderSummary, underNumber of instances, enter2..

10. ChooseLaunch instance.

11. ChooseView all instances to close the confirmation page and return to the console.

12. You can view the status of the launch on theInstances page. When you launch an instance, its initial state ispending. After the instance starts, its state changes torunning, and it receives a public DNS name. (If thePublic DNS column is not displayed, choose theShow/Hide icon, and then selectPublic DNS.)

13. It can take a few minutes for the instance to be ready for you to connect to it. Check that your instance has passed its status checks. You can view this information in theStatus Checks column.

To create a CodeDeploy service role

1. Open the IAM console athttps://console.aws.amazon.com/iam/).

2. From the console dashboard, chooseRoles.

3. ChooseCreate role.

4. UnderSelect trusted entity, chooseAWS service. UnderUse case, chooseCodeDeploy. ChooseCodeDeploy from the options listed. ChooseNext. TheAWSCodeDeployRole managed policy is already attached to the role.

5. ChooseNext.

6. Enter a name for the role (for example,CodeDeployRole), and then chooseCreate role.

To create an application in CodeDeploy

1. Open the CodeDeploy console athttps://console.aws.amazon.com/codedeploy.

2. If theApplications page does not appear, on the AWS CodeDeploy menu, chooseApplications.

3. ChooseCreate application.

4. InApplication name, enterMyDemoApplication.

5. InCompute Platform, chooseEC2/On-premises.

6. ChooseCreate application.

To create a deployment group in CodeDeploy

1. On the page that displays your application, chooseCreate deployment group.

2. InDeployment group name, enterMyDemoDeploymentGroup.

3. InService role, choose the service role you created earlier. You must use a service role that trusts AWS CodeDeploy with, at minimum, the trust and permissions described inCreate a Service Role for CodeDeploy. To get the service role ARN, seeGet the Service Role ARN (Console).

4. UnderDeployment type, chooseIn-place.

5. UnderEnvironment configuration, chooseAmazon EC2 Instances. ChooseName in theKey field, and in theValue field, enterMyCodePipelineDemo.

   Important

   You must choose the same value for theName key here that you assigned to your EC2 instances when you created them. If you tagged your instances with something other thanMyCodePipelineDemo, be sure to use it here.

6. UnderAgent configuration with AWS Systems Manager, chooseNow and schedule updates. This installs the agent on the instance. The Windows instance is already configured with the SSM agent and will now be updated with the CodeDeploy agent.

7. UnderDeployment settings, chooseCodeDeployDefault.OneAtaTime.

8. UnderLoad Balancer, make sure theEnable load balancing box is not selected. You do not need to set up a load balancer or choose a target group for this example. After you de-select the checkbox, the load balancer options do not display.

9. In theAdvanced section, leave the defaults.

10. ChooseCreate deployment group.

To create a CodePipeline automated release process

1. Sign in to the AWS Management Console and open the CodePipeline console athttp://console.aws.amazon.com/codesuite/codepipeline/home.

2. On theWelcome page,Getting started page, or thePipelines page, chooseCreate pipeline.

3. On theStep 1: Choose creation option page, underCreation options, choose theBuild custom pipeline option. ChooseNext.

4. InStep 2: Choose pipeline settings, inPipeline name, enterMyFirstPipeline.

   Note

   If you choose another name for your pipeline, be sure to use that name instead ofMyFirstPipeline for the rest of this tutorial. After you create a pipeline, you cannot change its name. Pipeline names are subject to some limitations. For more information, seeQuotas in AWS CodePipeline.

5. CodePipeline provides V1 and V2 type pipelines, which differ in characteristics and price. The V2 type is the only type you can choose in the console. For more information, seepipeline types. For information about pricing for CodePipeline, seePricing.

6. InService role, do one of the following:

   • ChooseNew service role to allow CodePipeline to create a new service role in IAM.

   • ChooseExisting service role to use a service role already created in IAM. InRole name, choose your service role from the list.

7. Leave the settings underAdvanced settings at their defaults, and then chooseNext.

8. InStep 3: Add source stage, inSource provider, chooseAmazon S3. InBucket, enter the name of the S3 bucket you created inStep 1: Create an S3 source bucket for your application. InS3 object key, enter the object key with or without a file path, and remember to include the file extension. For example, forSampleApp_Windows.zip, enter the sample file name as shown in this example:

   SampleApp_Windows.zip

   ChooseNext step.

   UnderChange detection options, leave the defaults. This allows CodePipeline to use Amazon CloudWatch Events to detect changes in your source bucket.

   ChooseNext.

9. InStep 4: Add build stage, chooseSkip build stage, and then accept the warning message by choosingSkip again. ChooseNext.

10. InStep 5: Add test stage, chooseSkip test stage, and then accept the warning message by choosingSkip again.

    ChooseNext.

11. InStep 6: Add deploy stage, inDeploy provider, chooseCodeDeploy. TheRegion field defaults to the same AWS Region as your pipeline. InApplication name, enterMyDemoApplication, or choose theRefresh button, and then choose the application name from the list. InDeployment group, enterMyDemoDeploymentGroup, or choose it from the list, and then chooseNext.

    Note

    The name Deploy is the name given by default to the stage created in theStep 4: Add deploy stage step, just as Source is the name given to the first stage of the pipeline.

12. InStep 7: Review, review the information, and then chooseCreate pipeline.

13. The pipeline starts to run. You can view progress and success and failure messages as the CodePipeline sample deploys a webpage to each of the Amazon EC2 instances in the CodeDeploy deployment.

• A source stage namedSource, which detects changes in the versioned sample application stored in the S3 bucket and pulls those changes into the pipeline.

• ADeploy stage that deploys those changes to EC2 instances with CodeDeploy.

To verify your pipeline ran successfully

1. View the initial progress of the pipeline. The status of each stage changes fromNo executions yet toIn Progress, and then to eitherSucceeded orFailed. The pipeline should complete the first run within a few minutes.

2. AfterSucceeded is displayed for the action status, in the status area for theDeploy stage, chooseDetails. This opens the CodeDeploy console.

3. In theDeployment group tab, underDeployment lifecycle events, choose an instance ID. This opens the EC2 console.

4. On theDescription tab, inPublic DNS, copy the address, and then paste it into the address bar of your web browser. View the index page for the sample application you uploaded to your S3 bucket.

   The web page displays for the sample application you uploaded to your S3 bucket.

Topics

• Create a second deployment group in CodeDeploy

• Add the deployment group as another stage in your pipeline

To create a second deployment group in CodeDeploy

1. Open the CodeDeploy console athttps://console.aws.amazon.com/codedeploy.

2. ChooseApplications, and in the list of applications, chooseMyDemoApplication.

3. Choose theDeployment groups tab, and then chooseCreate deployment group.

4. On theCreate deployment group page, inDeployment group name, enter a name for the second deployment group (for example,CodePipelineProductionFleet).

5. InService Role, choose the same CodeDeploy service role you used for the initial deployment (not the CodePipeline service role).

6. UnderDeployment type, chooseIn-place.

7. UnderEnvironment configuration, chooseAmazon EC2 Instances. ChooseName in theKey box, and in theValue box, chooseMyCodePipelineDemo from the list. Leave the default configuration forDeployment settings.

8. UnderDeployment configuration, chooseCodeDeployDefault.OneAtaTime.

9. UnderLoad Balancer, clearEnable load balancing.

10. ChooseCreate deployment group.

Topics

• Create a third stage (console)

• Create a third stage (CLI)

1. Sign in to the AWS Management Console and open the CodePipeline console athttp://console.aws.amazon.com/codesuite/codepipeline/home.

2. InName, choose the name of the pipeline you created, MyFirstPipeline.

3. On the pipeline details page, chooseEdit.

4. On theEdit page, choose+ Add stage to add a stage immediately after the Deploy stage.

   

5. InAdd stage, inStage name, enterProduction. ChooseAdd stage.

6. In the new stage, choose+ Add action group.

7. InEdit action, inAction name, enterDeploy-Second-Deployment. InAction provider, underDeploy, chooseCodeDeploy.

8. In the CodeDeploy section, inApplication name, chooseMyDemoApplication from the drop-down list, as you did when you created the pipeline. InDeployment group, choose the deployment group you just created,CodePipelineProductionFleet. InInput artifacts, choose the input artifact from the source action. ChooseSave.

9. On theEdit page, chooseSave. InSave pipeline changes, chooseSave.

10. Although the new stage has been added to your pipeline, a status ofNo executions yet is displayed because no changes have triggered another run of the pipeline. You must manually rerun the last revision to see how the edited pipeline runs. On the pipeline details page, chooseRelease change, and then chooseRelease when prompted. This runs the most recent revision available in each source location specified in a source action through the pipeline.

    Alternatively, to use the AWS CLI to rerun the pipeline, from a terminal on your local Linux, macOS, or Unix machine, or a command prompt on your local Windows machine, run thestart-pipeline-execution command, specifying the name of the pipeline. This runs the application in your source bucket through the pipeline for a second time.

    aws codepipeline start-pipeline-execution --name MyFirstPipeline

    This command returns apipelineExecutionId object.

11. Return to the CodePipeline console and in the list of pipelines, chooseMyFirstPipeline to open the view page.

    The pipeline shows three stages and the state of the artifact running through those three stages. It might take up to five minutes for the pipeline to run through all stages. You see the deployment succeeds on the first two stages, just as before, but theProduction stage shows theDeploy-Second-Deployment action failed.

12. In theDeploy-Second-Deployment action, chooseDetails. You are redirected to the page for the CodeDeploy deployment. In this case, the failure is the result of the first instance group deploying to all of the EC2 instances, leaving no instances for the second deployment group.

    Note

    This failure is by design, to demonstrate what happens when there is a failure in a pipeline stage.

To create a third stage for your pipeline

1. Open a terminal session on your local Linux, macOS, or Unix machine, or a command prompt on your local Windows machine, and run theget-pipeline command to display the structure of the pipeline you just created. ForMyFirstPipeline, you would type the following command:

   aws codepipeline get-pipeline --name "MyFirstPipeline"

   This command returns the structure of MyFirstPipeline. The first part of the output should look similar to the following:

   {    "pipeline":{        "roleArn": "arn:aws:iam::80398EXAMPLE:role/AWS-CodePipeline-Service",        "stages": [    ...

   The final part of the output includes the pipeline metadata and should look similar to the following:

       ...        ],        "artifactStore":{            "type": "S3"            "location": "amzn-s3-demo-bucket",        },        "name": "MyFirstPipeline",        "version": 4    },    "metadata":{        "pipelineArn": "arn:aws:codepipeline:us-east-2:80398EXAMPLE:MyFirstPipeline",        "updated": 1501626591.112,        "created": 1501626591.112    }}

2. Copy and paste this structure into a plain-text editor, and save the file aspipeline.json. For convenience, save this file in the same directory where you run theaws codepipeline commands.

   Note

   You can pipe the JSON directly into a file with theget-pipeline command as follows:

   aws codepipeline get-pipeline --nameMyFirstPipeline >pipeline.json

3. Copy theDeploy stage section and paste it after the first two stages. Because it is a deploy stage, just like theDeploy stage, you use it as a template for the third stage.

4. Change the name of the stage and the deployment group details.

   The following example shows the JSON you add to the pipeline.json file after theDeploy stage. Edit the emphasized elements with new values. Remember to include a comma to separate theDeploy andProduction stage definitions.

   ,{    "name": "Production",     "actions": [{         "inputArtifacts": [{              "name": "MyApp"             }           ],          "name": "Deploy-Second-Deployment",          "actionTypeId":{              "category": "Deploy",              "owner": "AWS",              "version": "1",              "provider": "CodeDeploy"              },         "outputArtifacts": [],         "configuration":{              "ApplicationName": "CodePipelineDemoApplication",              "DeploymentGroupName": "CodePipelineProductionFleet"               },         "runOrder": 1        }    ]}

5. If you are working with the pipeline structure retrieved using theget-pipeline command, you must remove themetadata lines from the JSON file. Otherwise, theupdate-pipeline command cannot use it. Remove the"metadata":{ } lines and the"created","pipelineARN", and"updated" fields.

   For example, remove the following lines from the structure:

   "metadata":{    "pipelineArn": "arn:aws:codepipeline:region:account-ID:pipeline-name",  "created": "date",  "updated": "date"  }

   Save the file.

6. Run theupdate-pipeline command, specifying the pipeline JSON file, similar to the following:

   aws codepipeline update-pipeline --cli-input-json file://pipeline.json

   This command returns the entire structure of the updated pipeline.

   Important

   Be sure to includefile:// before the file name. It is required in this command.

7. Run thestart-pipeline-execution command, specifying the name of the pipeline. This runs the application in your source bucket through the pipeline for a second time.

   aws codepipeline start-pipeline-execution --name MyFirstPipeline

   This command returns apipelineExecutionId object.

8. Open the CodePipeline console and chooseMyFirstPipeline from the list of pipelines.

   The pipeline shows three stages and the state of the artifact running through those three stages. It might take up to five minutes for the pipeline to run through all stages. Although the deployment succeeds on the first two stages, just as before, theProduction stage shows that theDeploy-Second-Deployment action failed.

9. In theDeploy-Second-Deployment action, chooseDetails to see details of the failure. You are redirected to the details page for the CodeDeploy deployment. In this case, the failure is the result of the first instance group deploying to all of the EC2 instances, leaving no instances for the second deployment group.

   Note

   This failure is by design, to demonstrate what happens when there is a failure in a pipeline stage.

To disable and enable transitions between stages in a CodePipeline pipeline

1. Open the CodePipeline console and chooseMyFirstPipeline from the list of pipelines.

2. On the details page for the pipeline, choose theDisable transition button between the second stage (Deploy) and the third stage that you added in the previous section (Production).

3. InDisable transition, enter a reason for disabling the transition between the stages, and then chooseDisable.

   The arrow between stages displays an icon and color change, and theEnable transition button.

   

4. Upload your sample again to the S3 bucket. Because the bucket is versioned, this change starts the pipeline.

5. Return to the details page for your pipeline and watch the status of the stages. The pipeline view changes to show progress and success on the first two stages, but no changes occur on the third stage. This process might take a few minutes.

6. Enable the transition by choosing theEnable transition button between the two stages. In theEnable transition dialog box, chooseEnable. The stage starts running in a few minutes and attempts to process the artifact that has already been run through the first two stages of the pipeline.

   Note

   If you want this third stage to succeed, edit the CodePipelineProductionFleet deployment group before you enable the transition, and specify a different set of EC2 instances where the application is deployed. For more information about how to do this, seeChange deployment group settings. If you create more EC2 instances, you might incur additional costs.

To clean up the resources used in this tutorial

1. To clean up your CodePipeline resources, follow the instructions inDelete a pipeline in AWS CodePipeline.

2. To clean up your CodeDeploy resources, follow the instructions inTo clean up resources (console).

3. To delete the S3 bucket, follow the instructions inDeleting or emptying a bucket. If you do not intend to create more pipelines, delete the S3 bucket created for storing your pipeline artifacts. For more information about this bucket, seeCodePipeline concepts.