Managing Approval Actions

Approval actions halt further progress through a pipeline until an authorized IAM user or IAM rule approves the transition. You can use approvals to review changes manually before final release into production, or as a code review step.

Figure 7.7 shows a pipeline with three stages: Source, Staging, and LambdaStage. The Source stage contains a source action referencing an Amazon S3 bucket. The source action has already completed and passed the source artifact to Staging. In Staging, the deploy action deploys the source artifact to Amazon EC2 with AWS CodeDeploy. If this action completes successfully, the LambdaStage stage begins, which also deploys to Amazon EC2 via AWS CodeDeploy.

Retry a Failed Action

If a pipeline action fails for any reason, you can retry that action on the same revision in the console or use the aws codepipeline retry-stage-execution AWS CLI command. However, there are certain situations where a failed action may become ineligible for retries.

• The pipeline itself has changed after the action failed.
• Other actions in the same stage have not completed.
• The retry attempt is already in progress.

Pipeline Account Steps

In the following steps, the account that contains the pipeline will be the pipeline account. The account to deploy resources will be the target account.

1. Create an AWS Key Management Service (AWS KMS) key in the pipeline account, and apply it to the pipeline. This key encrypts artifacts that pass between stages, and you configure it to allow access to the target account in a later step. After you create the AWS KMS key, you apply a key policy that allows access to the key by both the AWS CodePipeline service role in the pipeline account and the Amazon Resource Name (ARN) of the target account.
2. Apply a bucket policy to the Amazon S3 bucket for the pipeline. This policy must grant access to the bucket by the target account.
3. Create a policy that allows the pipeline account to assume a role in the target account. You attach this policy to the AWS CodePipeline service role.

Target Account Steps

1. Create an IAM role that contains a trust relationship policy that allows the pipeline account to assume the role.
2. Create an IAM policy that allows access to deploy to the pipeline’s resources. Attach this policy to the IAM role.
3. Create an IAM policy that allows access to the Amazon S3 bucket in the pipeline account, and attach it to the IAM role. After completing the previous steps, revisions that pass through the pipeline account will be accessible by the target account.

HTTPS

HTTPS connectivity to a Git-based repository requires a username and password, which pass to the repository as part of a request. To use AWS CodeCommit with HTTPS credentials, you must first add them to an IAM user with sufficient permissions to interact with the repository. To create Git credentials for your IAM user, you open the IAM console, and select the user who will need to authenticate to the AWS CodeCommit repository via HTTPS.

AWS generates security credentials for the usernames and passwords, and they cannot be set to custom values.

After you configure your Git CLI/application to use the repository’s HTTPS endpoint and the username/password, you will have access to the AWS CodeCommit repository.

SSH

With SSH authentication, there is no need to install the AWS CLI to connect to your repository. However, you perform some additional configuration tasks.

• Your IAM user must have the ability to manage their own SSH keys. To accomplish this, you add the IAMUserSSHKeys managed policy to the account.
• Scaling to handle rapid release cycles and large repositories.
• For Windows users, install a bash emulator, such as Git Bash.

To configure SSH authentication to AWS CodeCommit repositories, follow these steps:

1. In the IAM console, select the user account you want to modify.
2. Upload the public SSH key on the Security Credentials tab.
3. Copy the SSH key identity (ID). This follows the form APKAEIGHANK3EXAMPLE.
4. Update the ~/.ssh/config file on your workstation to include these contents:

   Host git-codecommit.*.amazonaws.com
   User YOUR_SSH_KEY_ID
   IdentityFile YOUR_PRIVATE_KEY_FILE

5. To verify the configuration, test a simple SSH connection to the AWS CodeCommit endpoint, as shown here:

   # Format: ssh git-codecommit.[REGION_CODE].amazonaws.com
   ssh git-codecommit.us-east-1.amazonaws.com

Use the Credential Helper

The previous HTTPS and SSH authentication methods both rely on additional credentials aside from IAM access/secret keys. It is also possible to authenticate to AWS CodeCommit with IAM credentials and the AWS CodeCommit credential helper. The credential helper translates IAM credentials to those that AWS CodeCommit can use to perform Git actions, such as to clone a repository or merge a pull request. To configure the credential helper on your workstation, do the following:

1. Install and configure the AWS CLI.
2. Install Git.
3. Configure Git to leverage the credential helper from the AWS CLI with these commands:

   git config --global 
   credential.helper '!aws codecommit credential-helper $@'
    
   git config --global credential.UseHttpPath true

Once complete, HTTPS interactions with the AWS CodeCommit repository should work as expected.

Repository Notifications

AWS CodeCommit supports triggers via Amazon SNS, which you can use to leverage other AWS services for post-commit actions, such as firing a webhook with AWS Lambda after a commit is pushed to a development branch. To implement this, AWS CodeCommit uses AWS CloudWatch Events. You create event rules that trigger for each of the event types that you select in AWS CodeCommit. Event types that will fire notifications include the following:

• Pull Request Update Events
• Create a Pull Request
• Close a Pull Request
• Update Code in a Pull Request
• Title or Description Changes
• Pull Request Comment Events
• Commit Comment Events
• Comments on Code Changes
• Comments on Files in a Commit
• Comments on the Commit Itself

Repository Triggers

Repository triggers are not the same as notifications, as the events that fire each differ greatly. Use repository triggers to send notifications to Amazon SNS or AWS Lambda during these events:

• Push to Existing Branch
• Create a Branch or Tag
• Delete a Branch or Tag

Triggers are similar in functionality to webhooks used by other Git providers, like GitHub. You can use triggers to perform automated tasks such as to start external builds, to notify administrators of code pushes, or to perform unit tests. There are some restrictions on how to configure triggers.

• The trigger destination, Amazon SNS or AWS Lambda, must exist in the same AWS region as the repository.
• If the destination is Amazon SNS in another AWS account, the Amazon SNS topic must have a policy that allows notifications from the account that contains the repository.

Repository Account Actions

1. Create a policy for access to the repository. This policy should allow users in the user account to access one or more specific repositories, as well as (optionally) to view a list of all repositories.
2. Attach this policy to a role in the same account, and allow users in the user account to assume this role.

User Account Actions

1. Create an IAM user or IAM group. This user or group will be able to access the repository after the next step.
2. Assign a policy to the user or group that allows them to assume the role created in the repository account as part of the previous steps.

Once these steps are complete, the IAM user will first need to assume the cross-account role before you attempt to clone or otherwise access the repository. You adjust the AWS credentials file ~/.aws/config (Linux/macOS) or drive:Usersusername.awsconfig (Windows). A profile will be added to this config file that specifies the cross-account role to assume.

[profile MyCrossAccountProfile]
region = US East (Ohio)
role_arn=arn:aws:iam:111122223333:role/MyCrossAccountContributorRole
source_profile=default

Lastly, you need to modify the AWS CLI credential helper so that you use MyCrossAccountProfile.

git config --global credential.helper 
  '!aws codecommit credential-helper --profile MyCrossAccountProfile $@'

From this point, the IAM user in the user account will be able to clone and interact with the repository in the repository account.

Migrate a Git Repository

You use an AWS CodeCommit to migrate from a Git repository, as shown in Figure 7.14.

The first step is to create the AWS CodeCommit repository (via either the AWS Management Console or the AWS CLI or AWS SDK). After you create the repository, clone the project to a local workstation. To push this repository to AWS CodeCommit, set the repository’s remote to the AWS CodeCommit repository’s HTTPS or SSH URL.

git push 
  https://git-codecommit.us-east-2.amazonaws.com/v1/repos/MyClonedRepository 
  --all

If you need to push any tags to the new repository, run the following code:

git push 
  https://git-codecommit.us-east-2.amazonaws.com/v1/repos/MyClonedRepository 
  --tags

Migrate Unversioned Content

You can migrate any local or unversioned content to AWS CodeCommit in a similar manner, as if the content exists in another Git-based repository service. The primary difference is that you set up a new repository instead of cloning an existing one to migrate. Refer to Figure 7.15.

First create the AWS CodeCommit repository (either via the AWS Management Console or via the AWS CLI or AWS SDK). Next, create a local directory with the files to migrate, and run git init from the command line or terminal in that directory. This will initialize the directory to work with Git so that any file changes are tracked. After the directory initializes, run git add . to add all current files to Git. Run git commit -m 'Initial Commit' to generate a commit. Lastly, push the commit to AWS CodeCommit with git push https://git-codecommit.us-east-2.amazonaws.com/v1/repos/MyFirstRepo --all.

Migrate Incrementally

For large repositories, you can migrate in incremental steps and push many smaller files. This prevents any network issues that may cause the entire push to fail. If any smaller commit fails, it is a trivial matter to restart it when you compare it to a single, monolithic commit.

Additionally, when you push large repositories, AWS recommends that you use SSH over HTTPS, as there is a chance that the HTTPS connection may terminate because of various network or firewall issues.

Create a Build Project

When you create a build project, you first select a source provider. AWS CodeBuild supports AWS CodeCommit, Amazon S3, GitHub, and BitBucket as source providers. When you use GitHub or BitBucket, a separate authentication flow will be invoked. This allows access to the source repository from AWS CodeBuild. GitHub source repositories also support webhooks to trigger builds automatically any time you push a commit to a specific repository and branch.

After AWS CodeBuild successfully connects to the source repository or location, you select a build environment. AWS CodeBuild provides preconfigured build environments for some operating systems, runtimes, and runtime versions, such as Ubuntu with Java 9.

Next, you will configure the build specification. This can be done in one of two ways. You can insert build commands in the console or specify a buildspec.yml file in your source code. Both options are valid, but if you use a buildspec.yml file, you will see additional configuration options.

If your build creates artifacts you would like to use in later steps of your pipeline/process, you can specify output artifacts to save to Amazon S3. Otherwise, you can choose not to save any artifacts. You will need to specify individual filename(s) for AWS CodeBuild to save on your behalf.

AWS CodeBuild supports caching, which you can configure in the next step. Caching saves some components of the build environment to reduce the time to create environments when you submit build jobs.

Every build project requires an IAM service role that is accessible by AWS CodeBuild. When you create new projects, you can automatically create a service role that you restrict to this project only. You can update service roles to work with up to 10 build projects at a time.

Lastly, you can configure AWS CodeBuild to create build environments with connectivity to an Amazon Virtual Private Cloud (Amazon VPC) in your account. To do so, specify the Amazon VPC ID, subnets, and security groups to assign to the build environment. You can configure other settings when you create the build, such as to run the Docker daemon in privileged mode to build Docker images.

After you set the build project properties, you can select the compute type (memory and vCPU settings), any environment variables to pass to the build container, and tags to apply to the project.

Version

AWS supports multiple build specification versions; however, AWS recommends you use the latest version whenever possible.

Environment Variables (env)

You can add optional environment variables to build jobs. Any key/value pairs that you provide in the variables section are available as environment variables in plain text.

The parameter-store mapping specifies parameters to query in AWS Systems Manager Parameter Store.

Phases

The phases mapping specifies commands to run at each stage of the build job. When you specify build settings in the AWS CodeBuild console, AWS CLI, or AWS SDK, you are not able to separate commands into phases. With a build specifications file, you can separate commands into phases.

install Commands to execute during installation of the build environment.

pre_build Commands to be run before the build begins.

build Commands to be run during the build.

post_build Commands to be run after the build completes.

Artifacts

The artifacts mapping specifies where AWS CodeBuild will place output artifacts, if any. This is required only if your build job produces actual outputs. For example, unit tests would not produce output artifacts for later use in a pipeline. The files list specifies individual files in the build environment that will act as output artifacts. You can specify individual files, directories, or recursive directories. You can use discard-paths and base-directory to specify a different directory structure to package output artifacts.

Cache

If you configure caching for the build project, the cache map specifies which files to upload to Amazon S3 for use in subsequent builds.

version: 0.2
 
env:
  variables:
    JAVA_HOME: "/usr/lib/jvm/java-8-openjdk-amd64"
  parameter-store:
    LOGIN_PASSWORD: "dockerLoginPassword"
 
phases:
  install:
    commands:
      - echo Entered the install phase...
      - apt-get update -y
      - apt-get install -y maven
  pre_build:
    commands:
      - echo Entered the pre_build phase...
      - docker login –u User –p $LOGIN_PASSWORD
  build:
    commands:
      - echo Entered the build phase...
      - echo Build started on 'date'
      - mvn install
  post_build:
    commands:
      - echo Entered the post_build phase...
      - echo Build completed on 'date'
artifacts:
  files:
    - target/messageUtil-1.0.jar
  discard-paths: yes
cache:
  paths:
    - '/root/.m2/**/*'

AWS CodeBuild Environments

AWS CodeBuild provides build environments for Ubuntu and Amazon Linux operating systems, and it supports the following:

• Android
• Docker
• Golang
• Java
• Node.js
• PHP
• Python
• Ruby
• .NET Core

Compute Types

Table 7.3 lists the memory, virtual central processing unit (vCPU), and disk space configurations for build environments.

Environment Variables

AWS CodeBuild provides several environment variables by default, such as AWS_REGION, CODEBUILD_BUILD_ID, and HOME.

When you run builds manually in the AWS CodeBuild console, AWS CLI, or AWS SDK, you have the option to change several properties before you run a build job.

• Source version (Amazon S3)
• Source branch, version, and Git clone depth (AWS CodeCommit, GitHub, and Bitbucket)
• Output artifact type, name, or location
• Build timeout
• Environment variables

In-Place Deployments

In in-place deployments, revisions deploy to new infrastructure instead of an existing one. After deployment completes successfully, the new infrastructure gradually replaces old code in a phased rollout. After all traffic routes to the new infrastructure, you can keep the old code for review or discard it.

Blue/Green Deployments

When you deploy to AWS Lambda functions, blue/green deployments publish new versions of each function, after which traffic shifting routes requests to the new function versions according to the deployment configuration that you define.

Stop Deployments

You can stop deployments via the AWS CodeDeploy console or AWS CLI. If you stop deployments to Amazon EC2 on-premises instances, this can result in some deployment groups being left in an undesired deployment state. For example, when you deploy to instances in an Auto Scaling group, if you stop the deployment, it may result in some instances having different application versions. In situations where this occurs, you can configure the application to roll back to the last valid deployment automatically. To do this, you submit a new deployment to the instances with the previous revision, and they appear as a new deployment in the console.

Rollbacks

AWS CodeDeploy achieves automatic rollbacks by redeploying the last working revision to any instances in the deployment group (this will generate a new deployment ID). If you do not configure automatic rollbacks for the application, you can perform a manual rollback by redeploying a previous revision as a new deployment. This will accomplish the same result as an automatic rollback.

During the rollback process, AWS CodeDeploy will attempt to remove any file(s) that were created on the instance during the failed deployment. A record of the created files is kept in the location on your instances.

• Linux: /opt/codedeploy-agent/deployment-root/deployment-instructions/[deployment-group-id]-cleanup
• Windows: C:ProgramDataAmazonCodeDeploydeployment-instructions [deployment-group-id]-cleanup

The AWS CodeDeploy agent that runs on the instance will reference this cleanup file as a record of what files were created during the last deployment.

AWS CodeDeploy tracks cleanup files; however, script executions are not tracked. Any configuration or modification to the instance that is done by scripts run on your instance cannot be rolled back automatically by AWS CodeDeploy. As an administrator, you will be responsible for implementing logic in your deployment scripts to ensure that the desired state is reached during deployments and rollbacks.

Test Deployments Locally

If you would like to test whether a revision will successfully deploy to an instance you are able to access, you can use the codedeploy-local command in the AWS CodeDeploy agent. This command will search the execution path for an AppSpec file and any content to deploy. If this is found, the agent will attempt a deployment on the instance and provide feedback on the results. This provides a useful alternative to executing the full workflow when you want simply to validate the deployment package.

The following example command attempts to perform a local deployment of an archive file located in Amazon S3:

codedeploy-local --bundle-location s3://mybucket/bundle.tgz --type tgz

On-Premises Instances

You can host instances for an Amazon EC2 on-premises deployment group in either an AWS account or your own data center. To configure an on-premises instance to work with AWS CodeDeploy, you must complete several tasks. Before you begin, you need to ensure that the instance has the ability to communicate with AWS CodeDeploy service endpoints over HTTPS (port 443). You will also need to create an IAM user that the instance assumes and has permissions to interact with AWS CodeDeploy.

1. Install the AWS CLI on the instance.
2. Configure the AWS CLI with an IAM user. Call the aws configure command, and specify the secret key ID and secret access key of the IAM user.
3. Register the instance with AWS CodeDeploy. Call the aws codedeploy register AWS CLI command from the on-premises instance. Provide a unique name with the --instance-name property. When you execute this command, include an IAM user to associate with the instance and tags to apply.

   aws deploy register --instance-name AssetTag12010298EX 
   --iam-user-arn arn:aws:iam::8039EXAMPLE:user/CodeDeployUser-OnPrem 
   --tags Key=Name,Value=CodeDeloyDemo-OnPrem 
   --region us-west-2

4. Register the instance with AWS CodeDeploy. Install the AWS CodeDeploy agent. Run the aws codedeploy install AWS CLI command. By default, it will install a basic configuration file with preconfigured settings. If you would like to override this, you can provide your own configuration file with the --config-file parameter. If you specify the --override-config parameter, this will override the current configuration file on the instance.

   aws deploy install --override-config 
   --config-file /tmp/codedeploy.onpremises.yml 
   --region us-west-2

After you complete the previous steps, the instance will be available for deployments to the deployment group(s).

Deploy to Amazon EC2 Auto Scaling Groups

When you deploy to Amazon EC2 Auto Scaling groups, AWS CodeDeploy will automatically run the latest successful deployment on any new instances created when the group scales out. If the deployment fails on an instance, it updates to maintain the count of healthy instances. For this reason, AWS does not recommend that you associate the same Auto Scaling group with multiple deployment groups (for example, you want to deploy multiple applications to the same Auto Scaling group). If both deployment groups perform a deployment at roughly the same time and the first deployment fails on the new instance, it terminates by AWS CodeDeploy. The second deployment, unaware that the instance terminated, will not fail until the deployment times out (the default timeout value is 1 hour). Instead, you should combine your application deployments into one or consider the use of multiple Auto Scaling groups with smaller instance types.

CodeDeployDefault.AllAtOnce

For in-place deployments, AWS CodeDeploy will attempt to deploy to all instances in the deployment group at the same time. The success criteria for this deployment configuration requires that at least once instance succeed for the deployment to be successful. If all instances fail the deployment, then the deployment itself fails.

For blue/green deployments, AWS CodeDeploy will attempt to deploy to the entire set of replacement instances at the same time and follows the same success criteria as in-place deployments. Once deployment to the replacement instances succeeds (at least one instance deploys successfully), traffic routes to all replacement instances at the same time. The deployment fails only if all traffic routing to replacement instances fails.

CodeDeployDefault.HalfAtATime

For in-place deployments, up to half of the instances in the deployment group deploy at the same time (rounded down). Success criteria for this deployment configuration requires that at least half of the instances (rounded up) deploy successfully.

Blue/green deployments use the same rules for the replacement environment, with the exception that the deployment will fail if less than half of the instances in the replacement environment successfully handle rerouted traffic.

CodeDeployDefault.OneAtATime

For in-place and blue/green deployments, this is the most stringent of the built-in deployment configurations, as it requires all instances to deploy the new application revision successfully, with the exception of the final instance in the deployment. For deployment groups with only one instance, the instance must complete successfully for the deployment to complete.

For blue/green deployments, the same rule applies for traffic routing. If all but the last instance registers successfully, the deployment is successful (with the exception of single-instance environments, where it must register without error).

CodeDeployDefault.AllAtOnce

For in-place deployments, AWS CodeDeploy will attempt to deploy to all instances in the deployment group at the same time. The success criteria for this deployment configuration requires that at least one instance succeed for the deployment to be successful. If all instances fail the deployment, then the deployment itself fails.

For blue/green deployments, AWS CodeDeploy will attempt to deploy to the entire set of replacement instances at the same time and follows the same success criteria as in-place deployments. Once deployment to the replacement instances succeeds (at least one instance deploys successfully), traffic routes to all replacement instances at the same time. The deployment fails only if all traffic routing to replacement instances fails.

CodeDeployDefault.HalfAtATime

For in-place deployments, up to half of the instances in the deployment group deploy at the same time (rounded down). Success criteria for this deployment configuration requires that at least half of the instances (rounded up) deploy successfully.

Blue/green deployments use the same rules for the replacement environment, with the exception that the deployment will fail if less than half of the instances in the replacement environment successfully handle rerouted traffic.

CodeDeployDefault.OneAtATime

This is the most stringent of the built-in deployment configurations, as it requires that all instances successfully deploy the new application revision (both in-place and blue/green deployments), with the exception of the final instance in the deployment. For deployment groups with only one instance, the instance must complete successfully for the deployment to complete.

For blue/green deployments, the same rule applies for traffic routing. If all but the last instance registers successfully, the deployment is successful (with the exception of single-instance environments, where it must register without error).

Canary

Traffic shifts in two percentage-based increments. The first increment routes to the new function version, and it is monitored for the number of minutes you define. After this time period, the remainder of traffic routes to the new version if the initial increment of request executes.

AWS CodeDeploy provides a number of built-in canary-based deployment configurations, such as CodeDeployDefault.LambdaCanary10Percent15Minutes. If you use this deployment configuration, 10 percent of traffic shifts in the first increment and is monitored for 15 minutes. After this time period, the 90 percent of traffic that remains shifts to the new function version. You can create additional configurations as needed.

Linear

Traffic can be shifted in a number of percentage-based increments, with a set number of minutes between each increment. During the waiting period between each increment, the requests routed to the new function versions must complete successfully for the deployment to continue.

AWS CodeDeploy provides a number of built-in linear deployment configurations, such as CodeDeployDefault.LambdaLinear10PercentEvery1Minute. With this configuration, 10 percent of traffic is routed to the new function version every minute, until all traffic is routed after 10 minutes.

All-at-Once

All traffic is shifted at once to the new function versions.

Amazon EC2 On-Premises AppSpec

For Amazon EC2 on-premises deployments, the AppSpec file must be YAML formatted and follow the YAML specifications for spacing and indentation. You place the AppSpec file (appspec.yml) in the root of the revision’s source code directory structure (it cannot be in a subfolder).

When you deploy to Amazon EC2 on-premises instances, the AppSpec file defines the following:

• A mapping of files from the revision and location on the instance
• The permissions of files to deploy
• Scripts to execute throughout the lifecycle of the deployment

The AppSpec file specifies scripts to execute at each stage of the deployment lifecycle. These scripts must exist in the revision for AWS CodeDeploy to call them successfully; however, they can call any other scripts, commands, or tools present on the instance. The AWS CodeDeploy agent uses the hooks section of the AppSpec file to reference which scripts must execute at specific times in the deployment lifecycle. When the deployment is at the specified stage (such as ApplicationStop), the AWS CodeDeploy agent will execute any scripts in that stage in the hooks section of the AppSpec file. All scripts must return an exit code of 0 to be successful.

For any files to place on the instance, the AWS CodeDeploy agent refers to the files section of the AppSpec file, where a mapping of files and directories in the revision dictates where on the instance these files reside and with what permissions. Here’s an example of an appspec.yml file:

version: 0.0
os: linux
files:
  - source: /
    destination: /var/www/html/WordPress
hooks:
  BeforeInstall:
    - location: scripts/install_dependencies.sh
      timeout: 300
      runas: root
  AfterInstall:
    - location: scripts/change_permissions.sh
      timeout: 300
      runas: root
  ApplicationStart:
    - location: scripts/start_server.sh
    - location: scripts/create_test_db.sh
      timeout: 300
      runas: root
  ApplicationStop:
    - location: scripts/stop_server.sh
      timeout: 300
      runas: root

In the previous example, the following events occur during deployment:

• During the install phase of the deployment, all files from the revision (source: /) are placed on the instance in the /var/www/html/WordPress directory.
• The install_dependencies.sh script (located in the scripts directory of the revision) executes during the BeforeInstall phase.
• The change_permissions.sh script executes in the AfterInstall phase.
• The start_server.sh and create_test_db.sh scripts execute in the ApplicationStart phase.
• The stop_server.sh script executes in the ApplicationStop phase.

The high-level structure of an Amazon EC2 on-premises AppSpec file is as follows:

version: 0.0
os: operating-system-name
files:
  source-destination-files-mappings
permissions:
  permissions-specifications
hooks:
  deployment-lifecycle-event-mappings

version Currently the only supported version number is 0.0.

os The os section defines the target operating system of the deployment group. Either windows or linux (Amazon Linux, Ubuntu, or Red Hat Enterprise Linux) is supported.

files The files section defines the mapping of revision files and their location to deploy on-instance during the install lifecycle event. This section is not required if no files are being copied from the revision to your instance. The files section supports a list of source/ destination pairs.

files:
  - source: source-file-location
    destination: destination-file-location

The source key refers to a file or a directory’s local path within the revision (use / for all files in the revision). If source refers to a file, the file copies to destination, specified as the fully qualified path on the instance. If source refers to a directory, the directory contents copy to the instance.

permissions For any deployed files or directories, the permissions section specifies the permissions to apply to files and directories on the target instance. You can also apply permissions to files on the instance by AWS CodeDeploy using the files directive of the AppSpec configuration.

permissions:
  - object: object-specification
    pattern: pattern-specification
    except: exception-specification
    owner: owner-account-name
    group: group-name
    mode: mode-specification
    acls:
      - acls-specification
    context:
      user: user-specification
      type: type-specification
      range: range-specification
    type:
      - object-type

Each object specification includes a set of files or directories to which the permissions will apply. You can select files based on a pattern expression and ignore them with a comma-delimited list in the except property. The owner, group, and mode properties correspond to their Linux equivalents. You can apply access control lists with the acls property, providing a list of user/group permissions assignments (such as u:ec2-user:rw). The context property is reserved for SELinux-enabled instances. This property corresponds to a set of context labels to apply to objects. Lastly, you use the type property to specify to which types of objects (file or directory) the specified permissions will apply.

hooks The hooks section specifies the scripts to run at each lifecycle event and under what user context to execute them.

One or more scripts can execute for each lifecycle hook.

ApplicationStop Before the application revision downloads to the instance, this lifecycle event can stop any running services on the instance that would be affected by the update. It is important to note that, since the revision has not yet been downloaded, the scripts execute from the previous revision. Because of this, the ApplicationStop hook does not run on the first deployment to an instance.

DownloadBundle The AWS CodeDeploy agent uses this lifecycle event to copy application revision files to a temporary location on the instance.

Linux /opt/codedeploy-agent/deployment-root/[deployment-group-id]/[deployment-id]/deployment-archive

WindowsC:ProgramDataAmazonCodeDeploy[deployment-group-id][deployment-id]deployment-archive

This event cannot run custom scripts, as it is reserved for the AWS CodeDeploy agent.

BeforeInstall Use this event for any pre-installation tasks, such as to clear log files or to create backups.

Install This event is reserved for the AWS CodeDeploy agent.

AfterInstall Use this event for any post-installation tasks, such as to modify the application configuration.

ApplicationStart Use this event to start any services that were stopped during the ApplicationStop event.

ValidateService Use this event to verify deployment completed successfully.

If your deployment group is registered with a load balancer, additional lifecycle events become available. These can be used to control certain behaviors as the instance is registered or deregistered from the load balancer.

BeforeBlockTraffic Use this event to run tasks before the instance is deregistered from the load balancer.

BlockTraffic This event is reserved for the AWS CodeDeploy agent.

AfterBlockTraffic Use this event to run tasks after the instance is deregistered from the load balancer.

BeforeAllowTraffic Similar in concept to BeforeBlockTraffic, this event occurs before instances register with the load balancer.

AllowTraffic This event is reserved for the AWS CodeDeploy agent.

AfterAllowTraffic Similar in concept to AfterBlockTraffic, this event occurs after instances register with the load balancer.

hooks:
   deployment-lifecycle-event-name:
     - location: script-location
       timeout: timeout-in-seconds
       runas: user-name

In the hooks section, the lifecycle name must match one of the previous event names, which are not reserved for the AWS CodeDeploy agent. The location property refers to the relative path in the revision archive where the script is located. You can configure an optional timeout to limit how long a script can run before it is considered failed. (Note that this does not stop the script’s execution.) The maximum script duration is 1 hour (3,600 seconds) for each lifecycle event. Lastly, the runas property can specify the user to execute the script. This user must exist on the instance and cannot require a password.

Figure 7.20 displays lifecycle hooks and their availability for in-place deployments with and without a load balancer.

Figure 7.21 displays lifecycle hooks and their availability for blue/green deployments.

AWS Lambda AppSpec

When you deploy to AWS Lambda functions, the AppSpec file can be in JSON or YAML format, and it specifies the function versions to deploy as well as other functions to execute for validation testing.

The high-level structure of an AWS Lambda deployment AppSpec file is as follows:

version: 0.0
resources:
  lambda-function-specifications
hooks:
  deployment-lifecycle-event-mappings

version Currently the only supported version number is 0.0.

resources The resources section defines the AWS Lambda functions to deploy.

resources:
  - name-of-function-to-deploy:
      type: "AWS::Lambda::Function"
      properties:
        name: name-of-lambda-function-to-deploy
        alias: alias-of-lambda-function-to-deploy
        currentversion: lambda-function-version-traffic-currently-points-to
        targetversion: lambda-function-version-to-shift-traffic-to

Name each function in the resources list both as the list item name and in the name property. The alias property specifies the function alias, which maps from the version specified in currentversion to the version specified in targetversion after the update deploys.

hooks The hooks section specifies the additional AWS Lambda functions to run at specific stages of the deployment lifecycle to validate success. The following lifecycle events support hooks in AWS Lambda deployments:

BeforeAllowTraffic For running any tasks prior to traffic shifting taking place

AfterAllowTraffic For any tasks after all traffic shifting has completed

hooks:
   - BeforeAllowTraffic: BeforeAllowTrafficHookFunctionName
   - AfterAllowTraffic: AfterAllowTrafficHookFunctionName

Figure 7.22 displays the lifecycle hook availability for AWS Lambda deployments.

For any functions in the hooks section, the function is responsible for notifying AWS CodeDeploy of success or failure with the PutLifecycleEventHookExecutionStatus call API from within your validation function. Here’s an example for Node.js:

CodeDeploy the prepared validation test results.
codedeploy.putLifecycleEventHookExecutionStatus(params, function(err, data) {
    if (err) {
        // Validation failed.
        callback('Validation test failed');
    } else {
        // Validation succeeded.
        callback(null, 'Validation test succeeded');
    }
});

When the agent installs, a codedeployagent.yml configuration file copies to the instances. You can use this file to adjust the behavior of the AWS CodeDeploy agent on instances throughout various deployments. This configuration file is stored in /etc/codedeploy-agent/conf on Linux instances and C:ProgramDataAmazonAWS CodeDeploy on Windows Server instances.

The most common settings are as follows:

max_revisions Use this to configure how many application revisions to archive on an instance. If you are experiencing storage limitations on your instances, turn this value down and release some storage space consumed by the agent.

root_dir Use this to change the default storage location for revisions, scripts, and archives.

verbose Set this to true to enable verbose logging output for debugging purposes.

proxy_url For environments that use an HTTP proxy, this specifies the URL and credentials to authenticate to the proxy and connect to the AWS CodeDeploy service.