CodeDeploy Application: What It Is and How to Create One

A CodeDeploy application is just a name that acts as a container, grouping the revisions you deploy, the deployment configurations and the deployment groups that say where and how, and you create it before anything else in the service.

The first thing newcomers misread is the word application. It is a label for a set of deployments, not the code itself.

Table of contents

• What the application object is
• Choosing the compute platform
• Creating the application, console and CLI
• The appspec file that drives a deployment
• Why deployments fail
• When you may not need it
• Blue/green, in-place and traffic shifting
• How this fits the rest of the stack
• FAQ

What the application object is

AWS CodeDeploy automates getting software onto servers, functions and containers. The word application in its console and API is easy to misunderstand. It does not hold your code and does not run anything. It is a name that ties together three other concepts so the correct revision, configuration and group are used each time.

The AWS documentation describes it exactly that way: a name that functions as a container to ensure the correct combination of revision, deployment configuration and deployment group is referenced during a deployment. Think of it like a project folder with a label on it.

The hierarchy is short.

• Application. The top-level name, plus a compute platform setting.
• Deployment group. A set of target instances, a function or a service, along with settings like rollback behaviour and load balancer integration.
• Revision. The versioned bundle of files to deploy, stored in an S3 bucket or a GitHub repository, including an application specification file.
• Deployment. One execution that applies a revision to a deployment group.

An application can have many deployment groups, such as staging and production, each with its own targets. It can also have many revisions over time. That separation lets you deploy the same revision to staging first and production second.

The existing posts on AWS CodeDeploy and the short overview of the service cover the surrounding product if you need orientation.

Choosing the compute platform

When you create an application you must choose a compute platform. It cannot be changed afterward, so pick carefully.

1. EC2 or on-premises. Deploys to virtual machines or servers that run the CodeDeploy agent. Supports in-place and blue/green deployments.
2. AWS Lambda. Shifts traffic between function versions using aliases. No agent is involved.
3. Amazon ECS. Performs blue/green deployments of containerised services behind a load balancer.

This choice determines which fields and strategies exist later. The EC2 platform uses hooks that run scripts on the machine. The Lambda and ECS platforms use traffic shifting with canary or linear patterns, such as moving ten percent of traffic first and the rest after a wait.

If you are unsure, ask where your code runs today. A traditional application on virtual machines points to EC2. A function-based API points to Lambda. A container service points to ECS. Avoid forcing a platform because it looks easier in a tutorial, since the application and the target must match.

Remember the permissions side too. CodeDeploy needs a service role that lets it read target details and manage deployments, and EC2 instances need an instance profile that lets the agent fetch revisions from the bucket.

Creating the application, console and CLI

In the console, open CodeDeploy, choose Applications, and create one with a name and a compute platform. The page is small on purpose. The CLI equivalent is one command:

aws deploy create-application \
  --application-name my-web-app \
  --compute-platform Server

The value Server is the platform name used for EC2 and on-premises, while Lambda and ECS select the others. You can then create a deployment group:

aws deploy create-deployment-group \
  --application-name my-web-app \
  --deployment-group-name production \
  --service-role-arn arn:aws:iam::123456789012:role/CodeDeployServiceRole \
  --ec2-tag-filters Key=Environment,Value=production,Type=KEY_AND_VALUE \
  --deployment-config-name CodeDeployDefault.OneAtATime

Targets are selected by tags, so tag your instances consistently before you create the group. A mistyped tag results in a deployment that succeeds against zero instances, which looks like success and deploys nothing.

You can also define the application in infrastructure as code, using a CloudFormation resource of the type AWS::CodeDeploy::Application, which keeps the setup reviewable and repeatable.

The appspec file that drives a deployment

For EC2 deployments, the revision contains an appspec.yml file at its root. It maps files to destinations and attaches scripts to lifecycle events.

version: 0.0
os: linux
files:
  - source: /
    destination: /var/www/my-web-app
hooks:
  BeforeInstall:
    - location: scripts/stop_server.sh
      timeout: 60
  AfterInstall:
    - location: scripts/install_deps.sh
      timeout: 300
  ApplicationStart:
    - location: scripts/start_server.sh
      timeout: 60
  ValidateService:
    - location: scripts/health_check.sh
      timeout: 120

The hooks run in a fixed order. Stop the old process, copy the files, install dependencies, start the new process, then validate. The validation script is the one most teams skip and most regret skipping. A deployment that reports success while the app is broken is worse than one that fails loudly.

Make scripts idempotent and make them exit non-zero on failure, since CodeDeploy judges success by exit code. Keep them in the repository next to the code, so history shows how a deploy changed. And test the appspec file on a throwaway instance before pointing it at production.

Why deployments fail

The most common failures are mundane.

• The agent is not running or is too old. Check the service status on the instance and the agent log.
• Permissions. The instance profile cannot read the revision from the bucket, or the service role lacks rights.
• A script returned a non-zero code. The deployment events page shows which hook failed and its output.
• Wrong tags. The group matches no instances, so nothing is deployed.
• Timeouts. A hook ran longer than its timeout, often an install step on a slow instance.
• Port or health check problems. The app starts but the load balancer health check fails, so the instance never receives traffic.

Read the lifecycle event details in the console first. They show the failing hook and the last lines of its output, which usually names the cause. Then read the agent log on the instance for anything that happened outside the script’s output.

Add automatic rollback for failed deployments and for alarms. It turns a bad release into a short blip instead of an incident. Test it at least once, deliberately, so you know it works.

When you may not need it

CodeDeploy is a sensible tool inside an AWS-centred pipeline. It is more machinery than a simple project needs, and the surrounding setup of roles, agents, buckets, tags and pipelines is substantial work.

Ask what you need from the deployment layer. If it is run a build on every push, start the new version, check it is healthy and roll back if not, a platform that does that from a repository connection removes a lot of configuration. If you need fine-grained traffic shifting across a fleet you manage yourself, the service earns its complexity.

On RunxBuild, a web service deploys from a GitHub repository with a build log, a live route, runtime logs and rollback to the previous deploy, and no agent or role setup. The tradeoff is that you run on the platform’s infrastructure rather than your own AWS account. For many small and mid-sized apps that is the point. The GitHub getting started guide shows the connection.

Blue/green, in-place and traffic shifting

The deployment strategy is a setting on the deployment group, and it decides how users experience a release.

An in-place deployment stops the application on each instance, installs the new revision and starts it again, usually a batch at a time. It needs no extra capacity, and it reduces your serving capacity during the rollout. With a load balancer, instances are taken out of rotation while they update, so users never reach a half-deployed machine.

A blue/green deployment creates a fresh set of instances running the new version, shifts traffic to them once they are healthy and then retires the old set. It costs extra capacity for a while and gives you a clean, instant way back, because the old environment still exists until you remove it.

For Lambda and ECS the equivalents are canary and linear shifts. Canary sends a small share first, say ten percent, waits and then sends the rest. Linear increases traffic in equal steps on a timer.

Whichever you choose, attach CloudWatch alarms so a rising error rate stops the rollout automatically.

How this fits the rest of the stack

Deployment tooling is cheap compared with the infrastructure it deploys to, so cost the servers before you perfect the pipeline. Check what the target environment runs you each month in the RunxBuild hosting calculator. If a simpler repository-driven deploy covers your needs, the RunxBuild dashboard is where you connect the repo.

Useful related references:

• AWS CodeDeploy: What a Deployment Controller Does, and When You Need One
• Scaling an Application: The Decision Tree
• Platform for AI: What an AI Application Actually Needs to Run
• Services on RunxBuild

FAQ

What is an application in AWS CodeDeploy?

It is a name that acts as a container grouping revisions, deployment configurations and deployment groups, so the correct combination is used each time you deploy. It does not contain your code.

Can I change the compute platform after creating an application?

No. The platform, which is EC2 or on-premises, Lambda or ECS, is fixed at creation. If you chose wrongly, create a new application.

What is the difference between a deployment group and an application?

The application is the top-level label. A deployment group defines the targets and settings for one environment, such as staging or production, within that application.

Where does the appspec file go?

At the root of your revision bundle. For EC2 it is appspec.yml and maps files to destinations and runs scripts at lifecycle events.

Why did my deployment succeed but nothing changed?

Commonly the deployment group’s tag filters matched no instances, so it deployed to zero targets. Check tags and the group’s target count.