Deployment

kanject aws deploy --env <stage> builds and ships one stage of a service, records the release in a deployment ledger, and makes rollback a pointer change rather than a rebuild. Supported service shapes are Lambda entries sharing a stack, one ECS Fargate backend, or a SPA coupled to one Lambda/ECS backend. Independent services keep their own manifests and release histories.

# Deploy a stage (names come from manifest.aws.stages)kanject aws deploy --env dev​# Render what would be deployed, and stop before changing anything in AWSkanject aws deploy --env prod --dry-run​# Read the history, then roll back with no rebuildkanject aws deployments list --env devkanject aws rollback --env dev --to previous

Preview the deployment

--dry-run syncs dependencies, resolves stage environment values and writes local deployment configuration. SSM or Secrets Manager references still require live AWS reads. It stops before building or mutating AWS; a multi-region stage previews only its primary region. --build-once compiles one bundle for the eligible single-entry ZIP path, then deploys it across regions; --no-build remains its compatibility alias and does not mean compilation is skipped.

What a deploy does

For a Lambda service, in order:

• Sync — resolves cross-repo dependencies at their pinned refs (--no-sync skips it).
• Resolve env — reads the stage file and fetches every param: and secret: reference from Parameter Store and Secrets Manager into memory.
• Build and deploy the stack — writes the per-stage aws-lambda-tools.<stage>.json and runs dotnet lambda deploy-serverless, which builds, packages, uploads and updates the CloudFormation stack.
• Apply env — merges the resolved values onto the function's environment. Values your template sets survive; stage values win on a clash. --bake-secrets false skips this for services that load their own config at startup.
• Publish and flip — publishes a Lambda version, which captures code and env together, and points the live alias at it.
• Record — appends the release to the ledger in the stage's artifact bucket: version, commit, who deployed, and hashes of the env values, never the values.

If a step fails, the deploy stops and writes no ledger entry. A service with several Lambdas and one shared release lifecycle deploys them into one stack: each entry builds on its own and their templates merge, and two entries that define the same template section differently fail with KANCLI609 or KANCLI610 before anything ships.

Managed Lambda HTTP access

For one managed .NET arm64 ASP.NET Lambda entry, CLI 1.0.70 can configure a public, buffered REST endpoint through kanject aws configure http. Deployment reconciles a companion HTTP stack against the live alias and requires the configured health probe before recording success. Template/external ownership remains available for other shapes. See Lambda HTTP access for enrollment, authentication, capabilities and interrupted-operation recovery.

What the stack contains

For Lambda, the stack is whatever your SAM template (template.json) declares. It is your file, and the CLI derives each stage's copy from it. The webapi and minimal-api templates start with one arm64 function behind an API Gateway REST API. Give the function the IAM permissions your code needs in that template. ECS Fargate and static-site stacks are generated by the CLI from the manifest and stage files instead. Each stage gets its own stack, {stage}-{service}, so stages never share resources.

Choose where it runs

Each entry in the manifest has a deploy target. Lambda is the default; set deployTarget on the entry for the other two.

• AWS Lambda — a zip or container image (packageType). Rollback moves the live alias; it changes traffic only for triggers routed through that alias.
• ECS Fargate — deployTarget: "ecs-fargate" on a webapi entry runs it as a container behind an Application Load Balancer. Rollback re-promotes the previous task definition, which takes minutes. Setup is on ECS Fargate.
• Static site — the single-page app that fronts your API, served from S3 through CloudFront. One per service, in a single region. It needs deployTarget: "static-site", renderMode: "spa", its source folder in projectPath, a build block such as { "kind": "static", "mode": "vite", "command": "npm run build" }, and the API entry it fronts in coupledTo, so the two deploy and roll back as a pair. Leave runtimeMode out; kanject doctor reports a malformed entry as KANCLI427. A site whose source lives in another repository is a git submodule, and KANCLI563 means it isn't initialized.

The manifest, stage files and ledger work the same on every target; how env reaches the code differs. Lambda bakes resolved values into the function. ECS passes param: and secret: references to the task definition, so ECS reads them when a task starts. A static site gets public values only and refuses anything bound to a secret (KANCLI430).

Changing a deployed stage's target fails with KANCLI391 unless you pass --replace-target, which stands the new target up beside the old one rather than tearing anything down.

Roll back

kanject aws rollback points the stage back at an earlier release from the ledger. Nothing is rebuilt, and code and env come back together. --to takes previous, previous-stable (the latest release not marked broken), a version number, or a commit SHA. Without --to on a terminal, it shows recent releases to pick from. In CI, --to is required and a live rollback also needs --yes.

# Mark a bad release so automated rollbacks skip itkanject aws deployments mark 7 --status broken --env prod​# In CI: name the target and confirmkanject aws rollback --env prod --to previous-stable --yes

For template-owned Lambda triggers, traffic routing through live normally starts on the second deployment, after the alias exists, and only for supported trigger shapes. Other triggers require a redeploy to change traffic. KANCLI657 stops a rollback that would move no traffic; read its remedy rather than pointing new functions at an alias by hand. Managed HTTP uses its recorded alias-bound endpoint and verification evidence.

kanject aws deployments gc deletes the build artifacts of releases outside the rollback window (the newest 10 by default, --window to change it) and keeps their ledger history. It is destructive, so run it with --dry-run first.

Previews

With preview.enabled set in the manifest, a static-site entry can publish a preview per branch or pull request under the base stage's CloudFront distribution. A coupled site finds its API's matching preview when there is one. Previews inherit the region, profile and Parameter Store path of the stage named in preview.basedOn, and expire after preview.ttlDays.

kanject aws preview publish pr-184   # build and publish under /previews/pr-184/kanject aws preview url pr-184kanject aws preview extend pr-184 --by 7dkanject aws preview rm --expired     # reap everything past ttlDays

The CLI has no command that creates a Lambda or ECS preview. ls, extend and rm still list, extend and remove preview stacks you create in your own pipeline, as long as they carry the kanject:preview, kanject:preview-name and kanject:preview-expires tags; url resolves static-site previews only.