Lambda quick start

A green-field service from dotnet new to kanject aws deploy --env dev in under 10 minutes. Assumes you've completed Installation and have an AWS account / profile configured.

1. Scaffold the project

kanject new wraps dotnet new, installs the template pack if missing, and offers to run kanject init on every Lambda entry project it finds.

kanject new minimal-api --name Kanject.Analyticscd Kanject.Analytics

You get:

Kanject.Analytics/├── kanject-cli/│   ├── manifest.json│   ├── manifest.lock.json│   └── stages/│       ├── dev.json│       ├── stage.json│       └── prod.json├── src/│   └── Kanject.Analytics.Api/│       ├── Kanject.Analytics.Api.csproj│       ├── Program.cs│       ├── appsettings.json│       └── aws-lambda-tools-defaults.json├── tests/│   └── Kanject.Analytics.Api.Tests/└── Kanject.Analytics.sln

The Minimal API starter keeps the application surface small and includes a wired xUnit test project. Use webapi instead when you want the controller-based structure from day one; pass --include-tests false only when you deliberately do not want tests.

2. Run it locally

kanject test

For this Lambda-hosted Minimal API, kanject test launches the Amazon.Lambda.TestTool with the project pre-loaded. Add --http to run it as a normal local web host, or --pull-env --env dev only when you deliberately need live stage parameters and secrets in the process.

3. Verify the toolchain and stage

kanject doctor --env dev

Doctor checks the local toolchain and, with --env dev, the stage configuration and provider preflight. Fix red findings before deployment.

4. Inspect what got generated

The generated Program.cs is a real Minimal API: one host registration and normal MapGet endpoints. Lambda is a hosting detail, not an application framework. The template does not preselect a database or register optional Kanject Core services; add those only when the application needs them.

using Amazon.Lambda.AspNetCoreServer;​var builder = WebApplication.CreateBuilder(args);​// Standard ASP.NET Core, hosted by Lambda in AWS.builder.Services.AddAWSLambdaHosting(LambdaEventSource.RestApi);​var app = builder.Build();​app.MapGet("/health", () => Results.Ok(new{    status = "healthy",    timestamp = DateTimeOffset.UtcNow}));​app.Run();

5. Configure the dev stage

Open kanject-cli/stages/dev.json and fill in the AWS specifics. The bare minimum:

{  "schemaVersion": 2,  "region": "eu-west-1",  "profile": "default",  "stack": "dev-kanject-analytics",  "artifactBucket": "dev-kanject-analytics-artifacts",  "parameterStore": {    "path": "/kanject-analytics/dev/"  },  "env": {    "ASPNETCORE_ENVIRONMENT": "Development"  }}

If the artifact bucket and Parameter Store path don't exist yet, the deploy fails with a clear AWS error — create them in the AWS console (or via your team's IaC) and try again.

6. Add a secret

Push a value to AWS Secrets Manager and bind it to an env var in one shot:

kanject add secret ANALYTICS_API_KEY \  kanject-analytics/dev/api#key \  --value "$(openssl rand -base64 32)" \  --env dev

This creates or updates the secret, stores the value under JSON key key, and adds ANALYTICS_API_KEY = secret:kanject-analytics/dev/api#key to the stage file. Verify the binding with kanject env --env dev without fetching or leaking its remote value.

7. Deploy and rehearse rollback

# Deploykanject aws deploy --env dev​# Practise the rollback drill on a fresh deploykanject aws deployments list --env devkanject aws rollback --env dev --to previous-stable

deploy syncs deps, resolves every param: and secret: reference, regenerates the per-stage aws-lambda-tools.dev.json, calls dotnet lambda deploy-serverless, publishes a Lambda version, flips the alias, and writes a deployment-ledger entry to S3. Rollback flips the alias back — no rebuild.