Manifest Reference

View .md

A service is described by two committed files. kanject-cli/manifest.json is the service identity — name, runtime, entries, cross-repo dependencies, and distributables. kanject-cli/stages/<stage>.json is one per stage, carrying the AWS coordinates and config that differ between dev, prod, and the rest. This page is the field-by-field reference for both.

manifest.json

json 
{  "schemaVersion": 2,  "cli": "1.4.0",  "service": {    "name": "acme-analytics",    "runtimeMode": "webapi",    "packageType": "zip",    "architecture": "arm64",    "entryProjects": [      {        "id": "api",        "projectPath": "src/Acme.Analytics.Api/Acme.Analytics.Api.csproj",        "runtimeMode": "webapi"      }    ]  },  "aws": {    "defaultStage": "dev",    "stages": ["dev", "prod"],    "provider": "aws"  },  "dependencies": [],  "distributables": [],  "preview": { "enabled": true, "basedOn": "dev", "ttlDays": 7 }}
  • schemaVersion (int, required) — manifest schema version. 2 is the multi-entry shape.
  • cli (string, required) — the CLI version that wrote the file.
  • 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) — ephemeral per-PR deployment policy; see below.

service

  • name (string, required) — the canonical service id; every AWS resource name derives from it. Lowercase, hyphenated.
  • runtimeMode (string, required) — "webapi" (ASP.NET Core host), "lambda-aspnetcore" (ASP.NET Core in Lambda), or "lambda-tasks" (Lambda Annotations).
  • packageType (string, optional, default "zip") — "zip" or "image" (container image in ECR).
  • architecture (string, optional, default "arm64") — "arm64" or "x86_64".
  • entryProjects (array, v2) — one or more entries (Lambda, or a single ECS Fargate service) deployed as one CloudFormation stack; see below.

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) — service-relative path to the entry's .csproj.
  • runtimeMode (string, required) — same values as service.runtimeMode.
  • 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" or "ecs-fargate". See ECS Fargate.
  • build (object, optional) — container build descriptor, required for ecs-fargate: kind, mode (sdk-publish / dockerfile), containerPort.
  • 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

Optional ephemeral-deployment policy shared by stack-backed previews and static-site previews published beneath an existing CloudFront distribution.

  • enabled (bool, default false) — turn previews on.
  • basedOn (string, default "dev") — the base stage supplying provider coordinates; static previews use its deployed site stack and shared distribution.
  • ttlDays (int, default 7) — lifespan before the stack is eligible for reaping.
  • stackName (string, default "preview-{name}-{service}") — CFN stack-name template; {name} and {service} are substituted.
  • apiStage (string, default "preview-{name}") — API Gateway stage template.
  • isolation (string, default "shared-dev") / shareUrl (bool, default true).

stages/<stage>.json

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

json 
{  "schemaVersion": 2,  "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" },  "entryEnv": { "api": { "FEATURE_FLAGS": "secret:acme/prod/flags#json" } },  "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) — matches the manifest.
  • 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 repo URI; 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) — per-entry overlays keyed by entryProjects[].id, applied over env.
  • 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.
  • 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 (baked into the function config), param:KEY (resolved from Parameter Store at deploy), or secret:path#key (resolved from Secrets Manager at deploy). entryEnv[<id>] overlays an entry's values over the stage env. Full detail in Core Concepts and Configuration.

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. A target inherits the stage's settings and overrides only what it names.

  • 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.
  • 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?