From 2287ed2cbb17797e7022b1fb3545430f4482f09b Mon Sep 17 00:00:00 2001 From: Eduardo Date: Wed, 21 May 2025 12:48:39 +0200 Subject: [PATCH 1/7] Adding limitations about support on cdk local --- content/en/user-guide/integrations/aws-cdk/index.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/content/en/user-guide/integrations/aws-cdk/index.md b/content/en/user-guide/integrations/aws-cdk/index.md index 68dc2c9da3..f89c284255 100644 --- a/content/en/user-guide/integrations/aws-cdk/index.md +++ b/content/en/user-guide/integrations/aws-cdk/index.md @@ -96,6 +96,15 @@ By default, stacks with validated certificates may not be deployed using the `lo This originates from the way how CDK ensures the certificate is ready - it creates a single-file lambda function with a single dependency on `aws-sdk` which is usually preinstalled and available globally in lambda runtime. When this lambda is executed locally from the `/tmp` folder, the package can not be discovered by Node due to the way how Node package resolution works. +### Version support + +`cdklocal` supports all installed versions of the node `aws-cdk` package, however some complications are present for `aws-cdk >= 2.177.0`. + +For these CDK versions, we remove AWS configuration environment variables like `AWS_PROFILE` from the shell environment before invoking the `cdk` command, and explicitly set `AWS_ENDPOINT_URL` and `AWS_ENDPOINT_URL_S3` to target LocalStack. + +1. We do this because other environment variables may lead to a conflicting set of configuration options, where the wrong region is used to target LocalStack, or `cdklocal` tries to deploy into upstream AWS by mistake. If individual configuration variables are needed for the deploy process (e.g. `AWS_REGION`) these configuration variables can be propagated to the `cdk` command by configuring `AWS_ENVAR_ALLOWLIST`, for example: `AWS_ENVAR_ALLOWLIST=AWS_REGION,AWS_DEFAULT_REGION AWS_DEFAULT_REGION=eu-central-1 AWS_REGION=eu-central-1 cdklocal ...`. +2. If you are manually setting `AWS_ENDPOINT_URL`, the new value will continue to be read from the environment, however `AWS_ENDPOINT_URL_S3` _must_ also be set and should include a `.s3.` component to ensure we correctly detect S3 requests. + ## Other resources * [Hot-reloading Lambda functions with CDK]({{< ref "user-guide/lambda-tools/hot-reloading#aws-cloud-development-kit-cdk-configuration" >}}) From 439c3221b5223a35a3981ec5937a801cf31816d5 Mon Sep 17 00:00:00 2001 From: Eduardo Date: Wed, 21 May 2025 12:54:37 +0200 Subject: [PATCH 2/7] Fixing lint and adding configuration for cdk local --- .../en/user-guide/integrations/aws-cdk/index.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/content/en/user-guide/integrations/aws-cdk/index.md b/content/en/user-guide/integrations/aws-cdk/index.md index f89c284255..1b1fa7bd66 100644 --- a/content/en/user-guide/integrations/aws-cdk/index.md +++ b/content/en/user-guide/integrations/aws-cdk/index.md @@ -102,9 +102,24 @@ When this lambda is executed locally from the `/tmp` folder, the package can not For these CDK versions, we remove AWS configuration environment variables like `AWS_PROFILE` from the shell environment before invoking the `cdk` command, and explicitly set `AWS_ENDPOINT_URL` and `AWS_ENDPOINT_URL_S3` to target LocalStack. -1. We do this because other environment variables may lead to a conflicting set of configuration options, where the wrong region is used to target LocalStack, or `cdklocal` tries to deploy into upstream AWS by mistake. If individual configuration variables are needed for the deploy process (e.g. `AWS_REGION`) these configuration variables can be propagated to the `cdk` command by configuring `AWS_ENVAR_ALLOWLIST`, for example: `AWS_ENVAR_ALLOWLIST=AWS_REGION,AWS_DEFAULT_REGION AWS_DEFAULT_REGION=eu-central-1 AWS_REGION=eu-central-1 cdklocal ...`. +1. We do this because other environment variables may lead to a conflicting set of configuration options, where the wrong region is used to target LocalStack, or `cdklocal` tries to deploy into upstream AWS by mistake. +If individual configuration variables are needed for the deploy process (e.g. `AWS_REGION`) these configuration variables can be propagated to the `cdk` command by configuring `AWS_ENVAR_ALLOWLIST`, for example: `AWS_ENVAR_ALLOWLIST=AWS_REGION,AWS_DEFAULT_REGION AWS_DEFAULT_REGION=eu-central-1 AWS_REGION=eu-central-1 cdklocal ...`. 2. If you are manually setting `AWS_ENDPOINT_URL`, the new value will continue to be read from the environment, however `AWS_ENDPOINT_URL_S3` _must_ also be set and should include a `.s3.` component to ensure we correctly detect S3 requests. +#### Configurations + +The following environment variables can be configured: + +* `AWS_ENDPOINT_URL`: The endpoint URL to connect to (combination of `USE_SSL`/`LOCALSTACK_HOSTNAME`/`EDGE_PORT` below) +* `AWS_ENDPOINT_URL_S3`: The endpoint URL to connect to (combination of `USE_SSL`/`LOCALSTACK_HOSTNAME`/`EDGE_PORT` below) for S3 requests +* `AWS_ENVAR_ALLOWLIST`: Allow specific `AWS_*` environment variables to be used by the CDK +* `EDGE_PORT` (deprecated): Port under which LocalStack edge service is accessible (default: `4566`) +* `LOCALSTACK_HOSTNAME` (deprecated): Target host under which LocalStack edge service is accessible (default: `localhost`) +* `USE_SSL` (deprecated): Whether to use SSL to connect to the LocalStack endpoint, i.e., connect via HTTPS. +* `LAMBDA_MOUNT_CODE`: Whether to use local Lambda code mounting (via setting `__local__` S3 bucket name). Note: may require CDK version <2.14.0 to be fully functional. +* `BUCKET_MARKER_LOCAL`: Magic S3 bucket name for Lambda mount and [hot reloading](https://docs.localstack.cloud/user-guide/tools/lambda-tools/hot-reloading) (default: `__local__`, will default to `hot-reload` in a future release) + + ## Other resources * [Hot-reloading Lambda functions with CDK]({{< ref "user-guide/lambda-tools/hot-reloading#aws-cloud-development-kit-cdk-configuration" >}}) From 194057b75b2106ab1d5cc927fc81f20bd84abe38 Mon Sep 17 00:00:00 2001 From: Eduardo Date: Wed, 21 May 2025 12:58:31 +0200 Subject: [PATCH 3/7] fixing lint --- content/en/user-guide/integrations/aws-cdk/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/user-guide/integrations/aws-cdk/index.md b/content/en/user-guide/integrations/aws-cdk/index.md index 1b1fa7bd66..bf89818357 100644 --- a/content/en/user-guide/integrations/aws-cdk/index.md +++ b/content/en/user-guide/integrations/aws-cdk/index.md @@ -116,10 +116,10 @@ The following environment variables can be configured: * `EDGE_PORT` (deprecated): Port under which LocalStack edge service is accessible (default: `4566`) * `LOCALSTACK_HOSTNAME` (deprecated): Target host under which LocalStack edge service is accessible (default: `localhost`) * `USE_SSL` (deprecated): Whether to use SSL to connect to the LocalStack endpoint, i.e., connect via HTTPS. -* `LAMBDA_MOUNT_CODE`: Whether to use local Lambda code mounting (via setting `__local__` S3 bucket name). Note: may require CDK version <2.14.0 to be fully functional. +* `LAMBDA_MOUNT_CODE`: Whether to use local Lambda code mounting (via setting `__local__` S3 bucket name). + Note: may require CDK version <2.14.0 to be fully functional. * `BUCKET_MARKER_LOCAL`: Magic S3 bucket name for Lambda mount and [hot reloading](https://docs.localstack.cloud/user-guide/tools/lambda-tools/hot-reloading) (default: `__local__`, will default to `hot-reload` in a future release) - ## Other resources * [Hot-reloading Lambda functions with CDK]({{< ref "user-guide/lambda-tools/hot-reloading#aws-cloud-development-kit-cdk-configuration" >}}) From 8f8e8d0f12f5684d68757832b0913f8ae9a5abae Mon Sep 17 00:00:00 2001 From: Eduardo Date: Thu, 22 May 2025 14:19:56 +0200 Subject: [PATCH 4/7] Removing cdk configuration from limitations --- .../en/user-guide/integrations/aws-cdk/index.md | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/content/en/user-guide/integrations/aws-cdk/index.md b/content/en/user-guide/integrations/aws-cdk/index.md index bf89818357..ae63f007b9 100644 --- a/content/en/user-guide/integrations/aws-cdk/index.md +++ b/content/en/user-guide/integrations/aws-cdk/index.md @@ -106,19 +106,7 @@ For these CDK versions, we remove AWS configuration environment variables like ` If individual configuration variables are needed for the deploy process (e.g. `AWS_REGION`) these configuration variables can be propagated to the `cdk` command by configuring `AWS_ENVAR_ALLOWLIST`, for example: `AWS_ENVAR_ALLOWLIST=AWS_REGION,AWS_DEFAULT_REGION AWS_DEFAULT_REGION=eu-central-1 AWS_REGION=eu-central-1 cdklocal ...`. 2. If you are manually setting `AWS_ENDPOINT_URL`, the new value will continue to be read from the environment, however `AWS_ENDPOINT_URL_S3` _must_ also be set and should include a `.s3.` component to ensure we correctly detect S3 requests. -#### Configurations - -The following environment variables can be configured: - -* `AWS_ENDPOINT_URL`: The endpoint URL to connect to (combination of `USE_SSL`/`LOCALSTACK_HOSTNAME`/`EDGE_PORT` below) -* `AWS_ENDPOINT_URL_S3`: The endpoint URL to connect to (combination of `USE_SSL`/`LOCALSTACK_HOSTNAME`/`EDGE_PORT` below) for S3 requests -* `AWS_ENVAR_ALLOWLIST`: Allow specific `AWS_*` environment variables to be used by the CDK -* `EDGE_PORT` (deprecated): Port under which LocalStack edge service is accessible (default: `4566`) -* `LOCALSTACK_HOSTNAME` (deprecated): Target host under which LocalStack edge service is accessible (default: `localhost`) -* `USE_SSL` (deprecated): Whether to use SSL to connect to the LocalStack endpoint, i.e., connect via HTTPS. -* `LAMBDA_MOUNT_CODE`: Whether to use local Lambda code mounting (via setting `__local__` S3 bucket name). - Note: may require CDK version <2.14.0 to be fully functional. -* `BUCKET_MARKER_LOCAL`: Magic S3 bucket name for Lambda mount and [hot reloading](https://docs.localstack.cloud/user-guide/tools/lambda-tools/hot-reloading) (default: `__local__`, will default to `hot-reload` in a future release) +For reference on which configuration you can use on cdk in LocalStack in this scenario please refer to the following [documentation](https://github.com/localstack/aws-cdk-local?tab=readme-ov-file#configurations). ## Other resources From 5c7069cb8d4cd17308aa7a6b01bae1bb72df9091 Mon Sep 17 00:00:00 2001 From: Eduardo Date: Thu, 22 May 2025 14:24:05 +0200 Subject: [PATCH 5/7] Fixing typo --- content/en/user-guide/integrations/aws-cdk/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/user-guide/integrations/aws-cdk/index.md b/content/en/user-guide/integrations/aws-cdk/index.md index ae63f007b9..f800c3f5c2 100644 --- a/content/en/user-guide/integrations/aws-cdk/index.md +++ b/content/en/user-guide/integrations/aws-cdk/index.md @@ -106,7 +106,7 @@ For these CDK versions, we remove AWS configuration environment variables like ` If individual configuration variables are needed for the deploy process (e.g. `AWS_REGION`) these configuration variables can be propagated to the `cdk` command by configuring `AWS_ENVAR_ALLOWLIST`, for example: `AWS_ENVAR_ALLOWLIST=AWS_REGION,AWS_DEFAULT_REGION AWS_DEFAULT_REGION=eu-central-1 AWS_REGION=eu-central-1 cdklocal ...`. 2. If you are manually setting `AWS_ENDPOINT_URL`, the new value will continue to be read from the environment, however `AWS_ENDPOINT_URL_S3` _must_ also be set and should include a `.s3.` component to ensure we correctly detect S3 requests. -For reference on which configuration you can use on cdk in LocalStack in this scenario please refer to the following [documentation](https://github.com/localstack/aws-cdk-local?tab=readme-ov-file#configurations). +For reference on which configuration you can use on CDK in LocalStack in this scenario please refer to the following [documentation](https://github.com/localstack/aws-cdk-local?tab=readme-ov-file#configurations). ## Other resources From 0a943b990c0eab56b883ebd5039b9e35a9d03fb1 Mon Sep 17 00:00:00 2001 From: HarshCasper Date: Sat, 7 Jun 2025 10:12:23 -0400 Subject: [PATCH 6/7] doc improve --- .../user-guide/integrations/aws-cdk/index.md | 21 ++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/content/en/user-guide/integrations/aws-cdk/index.md b/content/en/user-guide/integrations/aws-cdk/index.md index f800c3f5c2..bc0c53caf3 100644 --- a/content/en/user-guide/integrations/aws-cdk/index.md +++ b/content/en/user-guide/integrations/aws-cdk/index.md @@ -96,17 +96,24 @@ By default, stacks with validated certificates may not be deployed using the `lo This originates from the way how CDK ensures the certificate is ready - it creates a single-file lambda function with a single dependency on `aws-sdk` which is usually preinstalled and available globally in lambda runtime. When this lambda is executed locally from the `/tmp` folder, the package can not be discovered by Node due to the way how Node package resolution works. -### Version support +`cdklocal` works with all installed versions of the Node.js `aws-cdk` package. +However, issues exist for `aws-cdk >= 2.177.0`. -`cdklocal` supports all installed versions of the node `aws-cdk` package, however some complications are present for `aws-cdk >= 2.177.0`. +For these versions: -For these CDK versions, we remove AWS configuration environment variables like `AWS_PROFILE` from the shell environment before invoking the `cdk` command, and explicitly set `AWS_ENDPOINT_URL` and `AWS_ENDPOINT_URL_S3` to target LocalStack. +* We unset AWS-related environment variables like `AWS_PROFILE` before calling `cdk`. +* We explicitly set `AWS_ENDPOINT_URL` and `AWS_ENDPOINT_URL_S3` to point to LocalStack. -1. We do this because other environment variables may lead to a conflicting set of configuration options, where the wrong region is used to target LocalStack, or `cdklocal` tries to deploy into upstream AWS by mistake. -If individual configuration variables are needed for the deploy process (e.g. `AWS_REGION`) these configuration variables can be propagated to the `cdk` command by configuring `AWS_ENVAR_ALLOWLIST`, for example: `AWS_ENVAR_ALLOWLIST=AWS_REGION,AWS_DEFAULT_REGION AWS_DEFAULT_REGION=eu-central-1 AWS_REGION=eu-central-1 cdklocal ...`. -2. If you are manually setting `AWS_ENDPOINT_URL`, the new value will continue to be read from the environment, however `AWS_ENDPOINT_URL_S3` _must_ also be set and should include a `.s3.` component to ensure we correctly detect S3 requests. +Some environment variables may cause conflicting config, such as wrong region or accidental deploys to real AWS. +To allow specific variables (e.g., `AWS_REGION`), use `AWS_ENVAR_ALLOWLIST`: -For reference on which configuration you can use on CDK in LocalStack in this scenario please refer to the following [documentation](https://github.com/localstack/aws-cdk-local?tab=readme-ov-file#configurations). +```bash +AWS_ENVAR_ALLOWLIST=AWS_REGION,AWS_DEFAULT_REGION AWS_DEFAULT_REGION=eu-central-1 AWS_REGION=eu-central-1 cdklocal ... +``` + +If you manually set `AWS_ENDPOINT_URL`, it will be used. +You must also set `AWS_ENDPOINT_URL_S3`, and it must include `.s3.` to correctly identify S3 API calls. +See full configuration details [on our configuration docs](https://github.com/localstack/aws-cdk-local?tab=readme-ov-file#configurations). ## Other resources From 1e9cd1a13e01fe37e3d0086c94910ba8db133881 Mon Sep 17 00:00:00 2001 From: HarshCasper Date: Sat, 7 Jun 2025 10:12:59 -0400 Subject: [PATCH 7/7] add heading --- content/en/user-guide/integrations/aws-cdk/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/en/user-guide/integrations/aws-cdk/index.md b/content/en/user-guide/integrations/aws-cdk/index.md index bc0c53caf3..e1e71c3f19 100644 --- a/content/en/user-guide/integrations/aws-cdk/index.md +++ b/content/en/user-guide/integrations/aws-cdk/index.md @@ -96,6 +96,8 @@ By default, stacks with validated certificates may not be deployed using the `lo This originates from the way how CDK ensures the certificate is ready - it creates a single-file lambda function with a single dependency on `aws-sdk` which is usually preinstalled and available globally in lambda runtime. When this lambda is executed locally from the `/tmp` folder, the package can not be discovered by Node due to the way how Node package resolution works. +## CDK Version Compatibility + `cdklocal` works with all installed versions of the Node.js `aws-cdk` package. However, issues exist for `aws-cdk >= 2.177.0`.