Alvecta.Foundation.Deployment.Cdk 6.3.64

Alvecta.Foundation.Deployment.Cdk

Reusable AWS CDK (C#) building blocks that deploy an Alvecta application from one cdk.json manifest: DNS and certificates, one Lambda per service (.NET behind HTTP API Gateway, Node.js/SSR behind CloudFront), SNS notification topics, SSM secrets and IAM grants, plus an optional Aurora DSQL cluster in a separate database app.

It sits outside the Clean Architecture layers: it is referenced only by a solution's *.Deployment.Cdk project, never by application code. Dependencies: Amazon.CDK.Lib, Constructs, Alvecta.Utils and Alvecta.Utils.Json.

Two CDK apps

Both pick the environment from the env context value (cdk deploy -c env=Dev) and read its block from Environments in cdk.json. The database app is deployed on its own and first. It writes the cluster's endpoint and ARN to SSM Parameter Store, where the application stack reads them at deploy time, so the two apps share no CloudFormation export and an application deploy never touches the database.

What the regional stack gets

A single Composition.ServicesConstruct builds the whole regional stack from a list of ServiceDefinitions:

• ServiceDefinition.DotNet<TSettings>(serviceName, projectName, iamPolicies) — a .NET Lambda published from src/Parts/<serviceName>/<projectName>/<projectName>.csproj, fronted by HTTP API Gateway on <hostName>.<subdomain>, with throttling, an optional warm-up schedule and an optional long-timeout migration function.
• ServiceDefinition.Node<TSettings>(...) — a Node.js (SSR) Lambda fronted by CloudFront.
• Settings checked at synth time — each service's EnvironmentVariables block must deserialize into TSettings, so a missing required setting fails cdk synth, not the running service. The block is flattened into Lambda environment variables with __ separators.
• secret:<ssm-name> values — each referenced parameter is created as a SecureString with the placeholder default when it does not exist yet (an existing value is never overwritten). The service resolves it at startup with Alvecta.Foundation.Infrastructure.AmazonSsm.
• variable:<name> and ${variable:<name>} values — replaced with stack values: the ARN of a declared notification topic, or DsqlClusterEndpoint / DsqlClusterArn. An unknown name fails synth.
• IAM — Helpers.ServiceIamPolicyFactory.CreateServicePolicies grants SSM read/write under the environment's parameter prefix, dsql:DbConnectAdmin on the cluster (when there is one) and sns:Publish on the topics the service references; CreateFrontendPolicies grants SSM read only.

The lower-level constructs (DotNetLambdaApiConstruct, NodeLambdaApiConstruct, CloudFrontFrontendConstruct, SsmSecretInitializerConstruct) and stacks (DnsAndCertificateStack, DsqlClusterStack) are public for stacks that need a different shape.

Usage

dotnet add package Alvecta.Foundation.Deployment.Cdk

The application app's entry point and regional stack:

using Alvecta.Foundation.Deployment.Cdk;
using Alvecta.Foundation.Deployment.Cdk.Composition;
using Alvecta.Foundation.Deployment.Cdk.Helpers;
using Alvecta.Foundation.Deployment.Cdk.Hosting;
using Amazon.CDK;
using Constructs;

public static class Program
{
    public static void Main() =>
        CdkApplicationHost.Run(
            applicationName: "Shop",
            createApplicationStack: (app, id, props) => new ShopStack(app, id, props));
}

public class ShopStack : Stack
{
    public ShopStack(Construct scope, string id, ApplicationStackProps props)
        : base(scope, id, props)
    {
        _ = new ServicesConstruct(
            this,
            "Services",
            new ServicesConstructProps
            {
                EnvironmentName = props.EnvironmentName,
                ApplicationName = props.ApplicationName,
                EnvironmentConfig = props.EnvironmentConfig,
                CloudFrontCertificate = props.CloudFrontCertificate,
                SubdomainZone = props.SubdomainZone,
                ServicesFolder = "src/Parts",
                Services =
                [
                    ServiceDefinition.DotNet<BackendSettings>(
                        "Backend",
                        "Acme.Shop.Backend.Hosting.WebApi.AmazonLambda",
                        ServiceIamPolicyFactory.CreateServicePolicies),
                ],
            });
    }
}

The database app is a second entry point with its own --app command:

public static class Program
{
    public static void Main() => CdkDatabaseHost.Run(applicationName: "Shop");
}

The cdk.json context both apps read (property names are case-insensitive; DsqlConfig, Notifications, WarmupConfig, ThrottlingConfig and MigrationLambdaConfig are optional):

{
  "context": {
    "Environments": {
      "Dev": {
        "AwsConfig": { "Account": "123456789012", "Region": "eu-central-1" },
        "DnsConfig": {
          "ParentHostedZoneId": "Z0123456789ABCDEFGHIJ",
          "ParentHostedZoneName": "example.com",
          "SubdomainName": "dev-shop",
          "BaseDomainName": "example.com"
        },
        "SsmParameterPrefix": "/DevShop",
        "DsqlConfig": { "DeletionProtection": true },
        "Notifications": [
          { "Name": "Orders", "Emails": [ "ops@example.com" ], "ResultSnsTopicArnVariableName": "OrdersTopicArn" }
        ],
        "Services": {
          "Backend": {
            "DomainConfig": { "HostName": "api" },
            "LambdaConfig": { "MemorySizeMb": 1024, "TimeoutSeconds": 20 },
            "ThrottlingConfig": { "RequestsPerSecond": 100, "BurstRequests": 50 },
            "WarmupConfig": { "IntervalMinutes": 3 },
            "MigrationLambdaConfig": { "MemorySizeMb": 1024, "TimeoutSeconds": 900 },
            "EnvironmentVariables": {
              "Database": {
                "ConnectionString": "Server=${variable:DsqlClusterEndpoint};Database=postgres;User Id=admin;SearchPath=Shop"
              },
              "Payments": { "ApiKey": "secret:/DevShop/PaymentsApiKey" },
              "Notifications": { "OrdersTopicArn": "variable:OrdersTopicArn" }
            }
          }
        }
      }
    }
  }
}