Lesson 363 · AWS Learning Path

AWS 363: CodeDeploy applications, deployment groups, AppSpec, and lifecycle hooks

Anil Jalela · Published Jun 23, 2026 · 5 min read

Why this lesson matters

CodeDeploy coordinates deployment, but applications, deployment groups, revisions, AppSpec files, hooks, and target identity mean different things for EC2/on-premises, Lambda, and ECS. A valid file for one platform can be meaningless for another.

Resource and trust model

application (compute platform)
 -> deployment group (targets + configuration + service role + alarms)
 -> deployment (one revision + settings)
 -> lifecycle events/hooks -> validation -> result

The CodeDeploy service role manages target selection, load balancers, Auto Scaling, ECS/Lambda, alarms, and related actions needed by the deployment group. EC2 instances additionally need an instance role and CodeDeploy agent to retrieve revisions and report lifecycle state. Lambda/ECS hook functions have their own execution roles.

Applications and deployment groups

An application fixes the compute platform. A deployment group defines target scope and release policy. For EC2, targets may use tags or Auto Scaling groups; test overlapping tags and prevent one instance joining conflicting groups. For ECS, bind the cluster/service, target groups/listeners, role, and deployment configuration. For Lambda, bind function/alias and traffic policy.

Record owner, environment, account, Region, deployment-group ARN/name, compute platform, target selection, service role, load balancer, alarms, rollback events, previous revision, and retention. Protect edits to deployment groups because changing target selectors or role can expand blast radius without changing source.

Revisions and integrity

An EC2 revision bundle should contain the AppSpec at the required root plus application files/scripts. Store it under an immutable S3 version or provider revision with SHA-256/provenance. Verify archive file list, size, ownership, modes, line endings, interpreter, and AppSpec before release.

Lambda/ECS revisions use AppSpec content to identify exact versions/task definitions and traffic targets. Do not deploy $LATEST, mutable image tags, or an unversioned task definition intent. Correlate source commit -> build -> artifact/image digest -> AppSpec -> deployment ID -> runtime release marker.

EC2 AppSpec contract

EC2 AppSpec can define files, optional permissions, and lifecycle hooks. A simplified example:

version: 0.0
os: linux
files:
  - source: /
    destination: /opt/orders/releases/current
permissions:
  - object: /opt/orders/releases/current
    owner: orders
    group: orders
hooks:
  ApplicationStop:
    - location: scripts/stop.sh
      timeout: 60
      runas: root
  AfterInstall:
    - location: scripts/install.sh
      timeout: 180
      runas: root
  ApplicationStart:
    - location: scripts/start.sh
      timeout: 120
      runas: root
  ValidateService:
    - location: scripts/validate.sh
      timeout: 60
      runas: orders

This is not universally safe: overwriting current directly can leave mixed files. A stronger application design installs into versioned directories, verifies, atomically switches a symlink, preserves the prior release, and separates persistent state. Hook scripts must be idempotent, bounded, logged, and fail non-zero.

ApplicationStop can come from the prior successful revision, creating a first-deployment and missing-prior-script boundary. Test fresh host, repeat deployment, partial hook failure, agent restart, and rollback.

ECS and Lambda AppSpec/hooks

ECS AppSpec identifies task definition, load balancer container/port, and optional platform/network properties plus lifecycle Lambda hooks. Lambda AppSpec identifies current/target function version and supports validation hooks around traffic shifting.

Hook functions report status to CodeDeploy and must be least privilege, bounded, idempotent, and correlated with deployment ID. Test listeners can validate green before production traffic, but tests must verify business behavior and data compatibility rather than merely HTTP 200.

Agent and host lifecycle

For EC2/on-premises, inspect agent installation/version, service state, configuration, deployment root/disk, logs, instance identity/registration, IAM role, S3/KMS/network path, proxy, clock, and target tags. Agent health does not prove the application is healthy.

Patching/replacing immutable instances often reduces drift compared with long-lived in-place hosts. If using in-place, define configuration ownership, persistent paths, concurrent deployment prevention, package-lock behavior, reboot handling, and recovery after half-applied scripts.

Read-only inventory

aws deploy list-applications --region ap-south-1
aws deploy get-application --application-name APPLICATION_NAME --region ap-south-1
aws deploy list-deployment-groups --application-name APPLICATION_NAME --region ap-south-1
aws deploy get-deployment-group --application-name APPLICATION_NAME --deployment-group-name GROUP_NAME --region ap-south-1
aws deploy list-deployments --application-name APPLICATION_NAME --deployment-group-name GROUP_NAME --include-only-statuses Failed Succeeded InProgress --region ap-south-1

Redact application/group names, roles, tags, target groups, alarm names, revisions, instance IDs, and accounts.

Diagnosis by lifecycle

Failure lab and acceptance

Design one EC2 and one ECS or Lambda deployment group. Inject: wrong target tag, overlapping groups, missing revision version, KMS deny, agent offline, non-executable hook, hook timeout, first-deployment ApplicationStop, wrong ECS container/port, validation false positive, alarm delay, and rollback after incompatible writes.

Submit platform matrix, target/IAM flow, full AppSpec, bundle tree/digest, hook contracts, agent runbook, telemetry, 12 failure records, rollback/data strategy, cost, and cleanup.

Pass requires exact immutable revision, platform-correct AppSpec, bounded idempotent hooks, positive/negative validation, role separation, target-proof before deployment, and no claim that CodeDeploy rollback reverses data.

Official sources

• CodeDeploy overview
• AppSpec reference
• EC2 lifecycle hooks
• ECS AppSpec hooks
• CodeDeploy agent operations