# Manifest Reference

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](https://www.kanject.com/docs/cli-dependencies/).
- `distributables` *(array, optional)* — apps and libraries to publish. See [Distribute](https://www.kanject.com/docs/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](https://www.kanject.com/docs/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](https://www.kanject.com/docs/ecs-fargate/).
- `targets` *(array, optional)* — multi-region fan-out; see below.
- `distribution` *(object, optional)* — `{ "targets": [...] }` for `kanject aws distribute`. See [Distribute](https://www.kanject.com/docs/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](https://www.kanject.com/docs/concepts/) and [Configuration](https://www.kanject.com/docs/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](https://www.kanject.com/docs/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](https://www.kanject.com/docs/cli-dependencies/).

> **Referenced resources are diagnosed, not created:** VPCs, subnets, security groups, ACM certificates, and Route 53 zones are referenced by id — Kanject never creates them. kanject doctor flags any referenced resource it can't find before a deploy; omit a block to disable its checks.

---
_Source: https://www.kanject.com/docs/manifest/ · Kanject Docs_