DVA-C03 Deployment Artifacts: Dependencies, ECR Images, AppConfig and API Gateway Stages

Preparing an artifact means producing one immutable, versioned package (a .zip file, a container image or a library) that contains your code and its dependencies but no environment-specific values, and storing it where AWS deployment services can fetch it. Configuration, secrets and endpoints are supplied by each environment at deploy or run time. This is the build once, deploy many rule: the artifact your tests passed is byte-for-byte the artifact that reaches production.

Task 3.1 covers five skills, and this lesson follows them in order:

• Dependencies inside packages: native libraries, lock files, and keeping configuration out of the package.
• Container images: Dockerfiles, Amazon ECR authentication, tags, digests, tag immutability, lifecycle policies, replication and pull through cache.
• Code and package repositories: AWS CodeConnections for GitHub, GitLab and Bitbucket, CodeBuild source settings and AWS CodeArtifact.
• Environment-specific configuration: AWS AppConfig, Systems Manager Parameter Store, AWS Secrets Manager, Lambda environment variables and API Gateway stage variables.
• API Gateway features: deployments, stages and their URLs, endpoint types and custom domain names.

Choosing between .zip, container image and layer packaging for Lambda belongs to Task 3.3, and test automation to Task 3.2; they are taught in those lessons.

A package must carry exactly the dependencies that were tested, built for the platform it will run on, and nothing that differs per environment. Three habits achieve that.

Lock the whole dependency tree

Version ranges apply at every level of a dependency tree, so pinning only your direct dependencies in package.json or requirements.txt does not pin what they depend on. A build a day later can resolve a newer transitive version than the one you tested. The fix is a committed lock file (package-lock.json, poetry.lock, a fully pinned requirements file) plus an install command that honours it. For npm that is npm ci: it deletes node_modules, installs exactly the locked tree and fails if the lock file and package.json disagree. Only an install that refuses to deviate from the lock file makes a build reproducible: any command that resolves version ranges afresh can drift, and a cache makes an install faster without making it repeatable.

Build native dependencies for the target platform

Libraries with compiled extensions (for example many Python packages with C code) ship platform-specific binaries. Installed on a developer laptop running another operating system, they produce binaries that the Linux-based Lambda runtime cannot load, and the function fails when the module is imported (Linux reports the file as not being a valid ELF binary). Build them in an environment that matches the runtime: sam build --use-container installs dependencies inside a container image that matches the Lambda runtime and architecture. No packaging choice or runtime setting can repair this, because the binaries themselves were compiled for the wrong platform; only rebuilding them for the target does. The same rule applies to x86_64 versus arm64.

Keep environment values out of the artifact

Building a separate package per environment means the package you release was never the one you tested, and packing every environment's settings into one package spreads production values to every environment that receives it. Instead, build one package with no environment values and let each deployment supply them: Lambda environment variables set from template parameters, parameter names the code reads from Parameter Store, or an AppConfig profile per environment. The package then moves unchanged from test to production, and each environment only ever holds its own values. (How Lambda stores and encrypts environment variables is covered in the Lambda development lesson.)

A good deployment image is small, rebuilds quickly and runs on the CPU architecture of its host. Four Dockerfile practices deliver that.

• Multi-stage builds. A Dockerfile can contain several FROM stages. The build stage installs compilers and produces the artifact; the final stage starts from a minimal base and uses COPY --from=<stage> to take only the artifact. Layers of earlier stages are not in the final image, so it is smaller and carries fewer vulnerable packages. Layers are additive: a file deleted by a later instruction still ships inside the earlier layer that created it, which is why leaving build tools behind in a discarded stage is what actually removes them.
• Layer ordering for caching. Docker reuses a cached layer until an instruction's inputs change, then rebuilds every later layer. Copy the dependency manifest first, install dependencies, and only then copy the rest of the source. If COPY . . comes before the install step, any code edit forces a full reinstall. Every layer cache, on a laptop or in a CI service, reuses layers only up to the first changed instruction, so instruction order decides how much a cache can save.
• .dockerignore trims the build context (for example .git, local node_modules, test data, credentials files). It controls which local files the build can see.
• Target architecture. An image built on x86 contains amd64 binaries; on an ARM64 (Graviton) host it fails at start with exec format error. docker buildx build --platform linux/amd64,linux/arm64 --push publishes an image index (manifest list) under one tag, and Docker, ECS and EKS pull the variant that matches the host.

A CodeBuild project that runs Docker builds needs privileged mode, which lets the Docker daemon start inside the build container.

Amazon Elastic Container Registry (ECR) stores images in repositories inside a per-account, per-Region registry at <account>.dkr.ecr.<region>.amazonaws.com. The Docker CLI cannot sign requests with AWS credentials, so before pushing or pulling you exchange IAM credentials for a registry token:

aws ecr get-login-password --region eu-central-1 \
  | docker login --username AWS --password-stdin 444455556666.dkr.ecr.eu-central-1.amazonaws.com

The token is valid for 12 hours. Docker uses only the credentials that docker login (or a credential helper such as the Amazon ECR Docker Credential Helper) stores for the registry host, so a push that fails with no basic auth credentials means that step never ran for this registry. In a buildspec it usually goes in the pre_build phase.

IAM permissions for push and pull

Because GetAuthorizationToken is not a repository-level action, a statement that scopes it to a repository ARN never matches and the login fails with AccessDeniedException. Put it in its own statement with Resource: "*" and keep the push and pull actions scoped to the repository, which preserves least privilege.

ECS tasks pull images with the task execution role (the managed policy AmazonECSTaskExecutionRolePolicy includes these permissions); for a Lambda container-image function, the ECR repository policy must allow the lambda.amazonaws.com service principal ecr:BatchGetImage and ecr:GetDownloadUrlForLayer (the console adds this statement for a repository in the same account).

A tag is a movable label on an image; a digest (sha256:…) is the image's content hash and can never point at anything else. Use each for what it guarantees.

For traceability, tag every build with the commit it was built from. CodeBuild exposes it in CODEBUILD_RESOLVED_SOURCE_VERSION (the commit ID for Git sources). The task definition revision then names the exact commit that is running, and rolling back is a redeploy of an earlier image instead of a rebuild of an old branch.

Amazon ECS protects each service deployment from a moving tag. With software version consistency (the default, controlled per container by versionConsistency), ECS resolves the tag to a digest using the first task of a deployment and starts every other task of that deployment, including scale-out and replacement tasks, from the same digest. The next deployment, such as a new task definition revision or a forced new deployment, resolves the tag again, and so do standalone tasks started with RunTask and containers with version consistency turned off. In a mutable repository that later resolution can pick up a different image, so when a security team approves a specific scanned image, reference it by digest: only a digest guarantees the approved bytes in every future deployment.

Tag mutability settings

Each repository has a tag mutability setting:

• MUTABLE (default): pushing an existing tag moves it to the new image; the old image may become untagged.
• IMMUTABLE: a push that reuses any tag is rejected with ImageTagAlreadyExistsException, so a version tag always identifies the same image. Moving tags such as latest stop working.
• IMMUTABLE_WITH_EXCLUSION: all tags are immutable except those matching wildcard exclusion filters (for example latest and dev-*), which can still move. This protects version tags without changing the pipeline or splitting repositories.
• MUTABLE_WITH_EXCLUSION: the reverse, tags are mutable except those matching the filters.

The mutability setting is the only repository control that decides whether an existing tag can be overwritten. Features that act on images after they arrive, such as scanning and lifecycle rules, cannot prevent it, and IAM or repository policies decide who may push, not whether a tag may move.

Repository hygiene and distribution are handled by registry features, not pipeline scripts: lifecycle policies expire old images, replication and pull through cache copy images, and scanning checks them.

Lifecycle policies

An ECR lifecycle policy is a set of rules that automatically expires images by tag status and by count or age, so repositories do not grow without limit. Each rule has:

• rulePriority: a unique integer; lower numbers are applied first.
• selection.tagStatus: untagged, tagged (with a tagPrefixList or a wildcard tagPatternList) or any.
• countType: imageCountMoreThan (keep the newest N, expire the rest) or sinceImagePushed with countUnit: days (expire images older than N days). ECR also supports sinceImagePulled and archive transitions for repositories that use the archive storage class.
• action: expire (or a transition to archive).

How rules interact

ECR evaluates all rules together and then applies them by priority. The rule that decides most designs: an image that matches the tagging requirements of a higher-priority rule cannot be expired by a lower-priority rule. A tagStatus: any rule must have the lowest priority. For example, "keep the 5 newest images tagged release-, however old, and expire everything else 30 days after it was pushed" is:

{"rules": [
  {"rulePriority": 1,
   "selection": {"tagStatus": "tagged", "tagPrefixList": ["release-"],
                 "countType": "imageCountMoreThan", "countNumber": 5},
   "action": {"type": "expire"}},
  {"rulePriority": 2,
   "selection": {"tagStatus": "any",
                 "countType": "sinceImagePushed", "countUnit": "days", "countNumber": 30},
   "action": {"type": "expire"}}
]}

Rule 1 expires only release- images beyond the newest five; rule 2 cannot touch any release- image because rule 1 already matched it. The protection comes entirely from priority, so a rule that keeps a group of images must always outrank the broad rule that expires by age.

When builds move a tag to each new image, the previous image becomes untagged; a rule with tagStatus: untagged and sinceImagePushed cleans those up. Expiry is asynchronous: ECR acts on matching images within about 24 hours, so a lifecycle rule cannot be relied on to free a tag before the next push. Use the lifecycle policy preview to see which images a draft policy would expire before you save it.

Distributing images: replication, pull through cache and scanning

ECR registry-level features move and check images without extra pipeline steps.

Authenticated upstreams such as Docker Hub need their credentials stored in an AWS Secrets Manager secret (name prefixed ecr-pullthroughcache/) referenced by the rule. The two copy features differ in direction and timing: replication pushes copies between ECR private registries as images arrive, so the destination is ready in advance, while pull through cache fetches from an upstream (including external registries) lazily, when an image is first requested. AWS CodeArtifact stores language packages, not container images.

Build and deployment services fetch source from a Git provider and dependencies from a package repository. On AWS the first is done through AWS CodeConnections and the second through AWS CodeArtifact.

AWS CodeConnections (formerly CodeStar Connections)

A connection links CodePipeline, CodeBuild and other services to GitHub, GitHub Enterprise Server, GitLab or Bitbucket. A connection created with the CLI or CloudFormation starts in PENDING status and can only be completed in the console, where you authorize the provider's app. Until it is AVAILABLE, builds cannot download source, whatever IAM permissions the role has (the role still needs codeconnections:UseConnection).

CodeBuild source settings

• Git submodules: turn on the project's fetch-submodules option (gitSubmodulesConfig) or submodule directories are empty.
• Clone depth (gitCloneDepth): sets how many commits of history are fetched; a shallow clone is faster.
• Secondary sources: extra repositories checked out into their own directories (referenced through CODEBUILD_SRC_DIR_<sourceIdentifier>), which the buildspec addresses by those variables.
• Local source cache: reuses an earlier clone on the build host to speed up repeated builds.
• CODEBUILD_RESOLVED_SOURCE_VERSION gives the commit being built, useful for image tags.

AWS CodeCommit is not in the DVA-C03 in-scope service list; scenarios use a third-party Git provider through a connection.

AWS CodeArtifact

CodeArtifact is a managed package repository for npm, pip/twine (PyPI), Maven, Gradle, NuGet, Cargo, generic and other formats. The structure:

• A domain holds repositories and deduplicates package assets across them; its resource policy controls cross-account access.
• A repository can have up to 10 upstream repositories in the same domain and at most one external connection to a public registry (npmjs, PyPI, Maven Central and others).
• The usual layout is one "store" repository per public registry (for example npm-store connected to npmjs, pypi-store connected to PyPI), all added as upstreams of the team repository. Builds use the team repository for internal and public packages; fetched public versions are retained. Each package format uses its own endpoint URL on that repository.

Clients authenticate with a token: aws codeartifact login --tool npm|pip|twine --domain … --repository … calls GetAuthorizationToken and configures the tool. The token lasts 12 hours by default (configurable from 15 minutes to 12 hours). The caller needs codeartifact:GetAuthorizationToken and sts:GetServiceBearerToken in its identity-based policy (often with the condition sts:AWSServiceName = codeartifact.amazonaws.com); sts:GetServiceBearerToken has no effect in a domain resource policy. Reading packages then needs codeartifact:ReadFromRepository and codeartifact:GetRepositoryEndpoint.

Choose the configuration service by what the value is and how a change must roll out. A sensitive value belongs in Secrets Manager; a plain or encrypted setting read by name belongs in Parameter Store; a setting or feature flag whose change must roll out gradually, be validated and roll back on alarm belongs in AppConfig.

AWS AppConfig

AppConfig organizes data as an application with environments (dev, prod) and configuration profiles (feature flags, or free-form JSON, YAML or text from the AppConfig hosted store, S3, Parameter Store and other sources). A deployment sends one profile version to one environment using a deployment strategy:

• Validators: a profile can have up to two, a JSON Schema validator (free-form JSON) and/or a Lambda validator. They run when StartDeployment is called, so malformed data never starts deploying.
• Deployment strategy: growth type linear or exponential, growth factor, deployment time and bake time (monitoring after the rollout reaches 100%). Predefined strategies include AppConfig.AllAtOnce, AppConfig.Linear50PercentEvery30Seconds and AppConfig.Canary10Percent20Minutes; AllAtOnce gives no gradual protection.
• Monitors: CloudWatch alarms attached to the environment. If one goes into alarm during the deployment or bake time, AppConfig rolls the configuration back automatically.

Validators catch bad data; alarms with a gradual strategy catch values that are valid but harmful. You need both to cover both failure types.

Retrieving AppConfig data in code

• AppConfig Agent (recommended): on Lambda it is the AWS AppConfig Agent Lambda extension, added as a layer, which serves configuration at http://localhost:2772/applications/<app>/environments/<env>/configurations/<profile>. It caches data in the execution environment and only calls AppConfig when its poll interval has passed (default 45 seconds, set by AWS_APPCONFIG_EXTENSION_POLL_INTERVAL_SECONDS), cutting latency and priced requests. An agent is also available for ECS, EKS and EC2. The AWS Parameters and Secrets Lambda Extension is the equivalent cache for Parameter Store and Secrets Manager, not for AppConfig.
• AppConfig Data API: call StartConfigurationSession once for an InitialConfigurationToken, then GetLatestConfiguration, each time passing the NextPollConfigurationToken from the previous response (tokens are single-use and expire after 24 hours). Respect RequiredMinimumPollIntervalInSeconds. The response body is empty when you already have the latest version, so code must keep its cached configuration instead of treating an empty body as new data.

Parameter Store hierarchies and tiers

Name parameters by hierarchy, such as /orders/prod/db-host, so each environment reads its own subtree with GetParametersByPath (with Recursive for nested paths) and IAM can scope access by path. GetParametersByPath is a separate IAM action from GetParameter and GetParameters. With WithDecryption, SecureString values are decrypted with the caller's permissions, so a customer managed key also requires kms:Decrypt on that key (allowed by the key policy).

The Intelligent-Tiering option lets Parameter Store choose Advanced automatically when a request needs it, such as a value over 4 KB. The size limit belongs to the tier alone; the parameter type and the throughput setting are separate choices.

To give a container an environment-specific secret without the value appearing in the image or the task definition, reference the secret in the container definition's secrets section and let ECS inject it at task start.

"secrets": [
  { "name": "PAYMENT_API_KEY",
    "valueFrom": "arn:aws:secretsmanager:ap-southeast-2:444455556666:secret:staging/payments/gateway-Xy9Zt1:apiKey::" }
]

• valueFrom takes a Secrets Manager secret ARN, optionally followed by :json-key:version-stage:version-id. Empty version fields mean the AWSCURRENT version, but the colons must remain. Omitting the JSON key injects the whole JSON string. A Parameter Store parameter can be referenced by ARN (or by name in the same Region).
• The task execution role fetches the value, so it needs secretsmanager:GetSecretValue (or ssm:GetParameters) on that secret, plus kms:Decrypt for a customer managed key. The task role is the application's identity for its own AWS API calls once it is running; injection happens before that, with the execution role.
• Values are read when the container starts. A rotated secret reaches a running service only when new tasks start, for example after a forced new deployment.

The secrets section keeps only a reference in the task definition. Approaches that resolve the value earlier put plaintext somewhere else: a CloudFormation dynamic reference ({{resolve:secretsmanager:…}}) used in a container's environment section is resolved at deploy time, so the value is written into the task definition, and an environment file (environmentFiles) holds its values in an S3 object. Dynamic references suit properties designed to accept a secret, such as a database master password; for ECS containers, secrets is the native mechanism.

Lambda functions usually read secrets at run time with the SDK or the Parameters and Secrets Lambda Extension; for an ordinary environment variable the value is visible in the function configuration. Encryption and rotation details are covered in the encryption and secrets lesson.

API Gateway gives each environment its own stage URL and settings from one API definition; the endpoint type and custom domain decide where and under what host name clients reach it.

Deployments and stages

In an API Gateway REST API, edits to resources and methods change only the working definition; a stage serves nothing new until you create a deployment to it. A deployment is a snapshot of the API, and each stage (dev, test, prod) points at one deployment and has its own invoke URL:

https://{api-id}.execute-api.{region}.amazonaws.com/{stage-name}/{resource-path}
e.g. https://x9y8z7w6v5.execute-api.ap-south-1.amazonaws.com/staging/invoices

The stage name is always the first path segment of the default endpoint. Each stage also has its own settings: throttling, logging and metrics, caching, client certificate, AWS WAF association and stage variables. HTTP APIs can turn on automatic deployment for a stage (commonly the $default stage, served at the root of the invoke URL), so changes publish without a manual deployment.

Stage variables

Stage variables are name-value pairs set per stage and referenced as ${stageVariables.name} in integration settings, mapping templates and some other fields. They let one API definition target different backends per stage:

• HTTP integration: https://${stageVariables.backendHost}/orders, with backendHost set to a different host on each stage.
• Lambda integration: a function name such as inventory:${stageVariables.env}, where each stage sets env to the name of an alias of the same function, such as beta or live.

With a Lambda stage variable, API Gateway invokes a qualified function (inventory:live), and the function's resource-based policy must allow apigateway.amazonaws.com for that alias. You add one permission per value the variable can take (for example aws lambda add-permission --function-name inventory:live …). Without that permission (and with no credentials role on the integration), API Gateway cannot invoke the alias and returns 500 Internal Server Error for calls through that stage only. Use the function name (with the variable as the qualifier), not a full ARN, in the stage variable value.

Stage variables decide which backend a stage calls; custom-domain API mappings (below) decide which API and stage serve a path. Canary release settings on a stage are a deployment strategy, covered in the CI/CD lesson.

Endpoint types

Every REST API has one endpoint type that decides where it can be reached from:

A private API needs two things: an interface VPC endpoint (AWS PrivateLink) for the execute-api service in each VPC that calls it, and a resource policy on the API that allows those VPC endpoints or VPCs (a private API without a resource policy cannot be deployed). Controls placed in front of a Regional or edge-optimized API filter who may call it, but the endpoint itself stays on the internet; only the private endpoint type removes it.

Custom domain names

A custom domain name (for example api.example.com) holds the TLS certificate and a set of API mappings that map a base path to an API and stage, so /v1 can point to one API's prod stage and /v2 to another API under the same host. Certificate placement depends on the domain's endpoint type:

• Regional custom domain: the ACM certificate must be in the same Region as the domain.
• Edge-optimized custom domain: the ACM certificate must be in us-east-1.

DNS (for example a Route 53 alias record) then points the host name at the custom domain's target domain name. A plain CNAME to the execute-api host name does not work, because that endpoint does not present your certificate or route base paths.