Manifest Reference

View .md

A service is described by committed files under kanject-cli/, at the service root (for a service from kanject new, the API project folder). manifest.json is the service identity — name, entries, cross-repo dependencies, and distributables. stages/<stage>.json is one per stage, carrying the AWS coordinates and config that differ between dev, prod, and the rest. Paths in both are relative to the service root. This page is the field-by-field reference.

manifest.json

json 
{  "$schema": "manifest.schema.json",  "schemaVersion": 2,  "cli": "^1.0.54",  "service": {    "name": "acme-analytics",    "entryProjects": [      {        "id": "api",        "projectPath": "Acme.Analytics.Api.csproj",        "runtimeMode": "lambda-aspnetcore",        "packageType": "zip"      }    ]  },  "aws": {    "defaultStage": "dev",    "stages": ["dev", "prod"]  },  "dependencies": [],  "distributables": [],  "preview": { "enabled": true, "basedOn": "dev", "ttlDays": 7 }}
  • $schema (string, optional) — editor validation; init writes it with manifest.schema.json beside it.
  • schemaVersion (int, required) — 2, the multi-entry shape init writes. 1 is the legacy single-Lambda shape; kanject migrate --schema-v2 upgrades it.
  • cli (string, required) — the CLI versions the manifest needs, as a range such as ^1.0.54.
  • service (object, required) — service identity; see below.
  • aws (object, required) — provider + stage list; see below.
  • dependencies (array, optional) — cross-repo git dependencies. See Dependency Sources & Resolution.
  • distributables (array, optional) — apps and libraries to publish. See Distribute.
  • preview (object, optional) — preview policy; see below.

service

  • name (string, required) — the canonical service id; every AWS resource name derives from it. Lowercase, hyphenated.
  • entryProjects (array, required) — one or more entries deployed as one CloudFormation stack; see below.

In a v2 manifest service holds only these two fields; any other field fails to parse (KANCLI016). A v1 manifest keeps runtimeMode, packageType and architecture on service instead.

service.entryProjects[]

A v2 service hosts one or more entries in a single stack. Each entry:

  • id (string, required) — stable logical id; used in CloudFormation resource names and in a stage's entryEnv key. Lowercase, hyphenated.
  • projectPath (string, required) — path to the entry's .csproj, or to a static site's source folder.
  • runtimeMode (string) — "lambda-aspnetcore" (ASP.NET Core in Lambda), "lambda-tasks" (Lambda Annotations), or "webapi" (an ASP.NET Core host). Required for Lambda and ECS entries; leave it out on a static site.
  • packageType (string, optional, default "zip") — "zip" or "image"; entries may differ.
  • architecture (string, optional, default "arm64") — "arm64" or "x86_64".
  • deployTarget (string, optional, default "lambda") — "lambda", "ecs-fargate", or "static-site". See Deployment.
  • build (object) — how the entry is built. ECS Fargate: kind: "container", mode (sdk-publish or dockerfile), containerPort, plus dockerfile and context for a Dockerfile build. Static site: kind: "static", mode (npm or vite), command, and optionally outputDir.
  • renderMode (string, static site) — "spa".
  • coupledTo (string, static site) — the id of the API entry the site fronts.
  • coupling (string, static site, default "same-origin") — "same-origin" or "cross-origin".
  • httpHost (object, optional) — ASP.NET Lambda hosting/payload declaration for managed HTTP; see Lambda HTTP access.
  • handler (string, optional) — explicit Lambda handler; derived from projectPath by convention when omitted.

aws

  • defaultStage (string, required) — the project's conventional stage for commands that explicitly opt into a default. Progressive commands such as deploy, distribute, and env inspection instead use the sole stage or show a picker; non-interactive runs must pass --env.
  • stages (array of string, required) — every stage name; each needs a matching stages/<stage>.json.
  • provider (string, optional, default "aws") — the cloud provider key.

preview

Preview policy for kanject aws preview. See Deployment → Previews for what the CLI creates and manages.

  • enabled (bool, default false) — turn previews on; every preview command refuses to run until it is true.
  • basedOn (string, default "dev") — the stage previews inherit region, profile and Parameter Store path from; static-site previews publish under its distribution.
  • ttlDays (int, default 7) — how long a preview lives before preview rm --expired reaps it.
  • stackName, apiStage, isolation, shareUrl (optional) — naming and URL settings for stack-backed previews.

stages/<stage>.json

One file per stage in aws.stages. It carries the AWS coordinates and the config that changes between environments.

json 
{  "$schema": "../stage.schema.json",  "schemaVersion": 1,  "region": "eu-west-2",  "profile": "acme-prod",  "stack": "prod-acme-analytics",  "artifactBucket": "prod-acme-analytics-artifacts",  "parameterStore": { "path": "/acme-analytics/prod/" },  "env": { "ASPNETCORE_ENVIRONMENT": "Production" },  "network": {    "vpcId": "vpc-0a1b2c3d",    "subnetIds": ["subnet-1111", "subnet-2222"],    "securityGroupIds": ["sg-3333"]  },  "api": {    "domain": {      "name": "api.acme.com",      "certificateArn": "arn:aws:acm:eu-west-2:111122223333:certificate/abc",      "hostedZoneId": "Z0123456789"    }  },  "function": { "memorySize": 1024, "timeout": 30 },  "targets": [    { "region": "us-east-1", "profile": "acme-prod-us" }  ]}
  • schemaVersion (int, required) — always 1 for stage files, whatever the manifest's version.
  • region (string, required) — AWS region.
  • profile (string, required) — AWS CLI profile / role.
  • stack (string, required) — CloudFormation stack name.
  • artifactBucket (string, required) — S3 bucket for build artifacts and the deployment ledger.
  • ecrRepository (string, optional) — ECR repository name, conventionally <stage>-<service>; required when an entry uses packageType: "image".
  • parameterStore (object, optional) — { "path": "/svc/stage/" }, the SSM Parameter Store prefix.
  • env (map, optional) — stage environment variables; see env forms below.
  • entryEnv (map, optional) — for multi-entry services, per-entry overlays keyed by entryProjects[].id, applied over env. Plain values only: param: and secret: resolve in env.
  • http (map, optional) — per-entry HTTP ownership, REST access and required probes; authored by kanject aws configure http. See Lambda HTTP access.
  • network (object, optional) — VPC attachment; see below.
  • api (object, optional) — API Gateway config (custom domain); see below.
  • function (object, optional) — per-stage Lambda overrides; see below.
  • ecs (object, optional) — the ECS Fargate service shape (cpu, memory, autoscaling, ALB…) for ecs-fargate entries. See ECS Fargate.
  • staticSite (object, optional) — a static-site stage's custom domain, cache control and single-page-app fallback.
  • rollout (object, optional) — canary or linear traffic shifting behind an alarm gate, or blue/green on ECS, for single-entry services; kanject doctor --env validates it.
  • targets (array, optional) — multi-region fan-out; see below.
  • distribution (object, optional) — { "targets": [...] } for kanject aws distribute. See Distribute.

env, entryEnv, and Parameter Store

An env value takes one of three forms: a plain string, param:KEY (resolved from Parameter Store under parameterStore.path at deploy), or secret:path#key (resolved from Secrets Manager at deploy). Deploy applies the result to each function; entryEnv[<id>] then overlays plain values for one entry. How your code reads them is in CLI concepts.

network

Attaches the function to a VPC. All three are referenced — they must pre-exist.

  • vpcId (string, required) — the VPC id.
  • subnetIds (array of string, required) — subnets within the VPC.
  • securityGroupIds (array of string, required) — security groups within the VPC.

Configure it interactively with kanject aws configure vpc.

api.domain

Maps a custom domain onto the stage's API Gateway. The certificate and hosted zone are referenced — they must pre-exist.

  • name (string, required) — the custom domain, e.g. api.acme.com.
  • basePath (string, optional) — base path mapping; omit for the root.
  • certificateArn (string, required) — ACM certificate ARN, in the stage region.
  • hostedZoneId (string, required) — Route 53 hosted-zone id.

Configure it interactively with kanject aws configure domain.

function

  • memorySize (int, optional) — Lambda memory (MB); omit to keep the template value.
  • timeout (int, optional) — Lambda timeout (seconds); omit to keep the template value.

targets[]

When present, targets fans the stage out across regions — each target deploys its own stack, in order. A target inherits the stage's settings and overrides only what it names. Static sites deploy to one region only (KANCLI440).

  • region (string, required) — the target region.
  • artifactBucket (string, optional) — per-region bucket; derived as {stage-bucket}-{region} when omitted.
  • profile (string, optional) — per-region profile; inherits the stage profile when omitted. Enables cross-account via assume-role.
  • http (map, optional) — per-entry HTTP ownership, REST access and required probes; authored by kanject aws configure http. See Lambda HTTP access.
  • network (object, optional) — per-region VPC config; required when fanning across regions, since VPC ids are region-scoped.
  • ecs (object, optional) — per-region ECS references (cluster, vpc, subnets, certificate, hosted zone) for an ecs-fargate target. See ECS Fargate.

manifest.lock.json

Generated, not hand-edited — kanject sync writes it to pin every cross-repo dependency to a resolved commit. Commit it; it's what makes builds reproducible. See Dependency Sources & Resolution.

Was this page helpful?