Final notes and changes

Author: Unit2795

README.md

@@ -1,8 +1,6 @@
 # LocalStack & Terraform REST API
 
-Develop rapidly for the cloud without the associated costs, slow feedback, and risk of actual deployments using LocalStack!
-
-This is a guide on how to set up [Terraform](https://developer.hashicorp.com/terraform) and [LocalStack](https://localstack.cloud/) for local, [hot-reloading](https://docs.localstack.cloud/user-guide/tools/lambda-tools/hot-reloading/) Node.js AWS Lambda and API Gateway development. You'll be able to query your REST API entirely locally. The features used in this guide require you to have [LocalStack Pro](https://localstack.cloud/pricing/). There is a trial membership available.
+This is an example that uses [Terraform](https://developer.hashicorp.com/terraform) and [LocalStack](https://localstack.cloud/) to spin up a local [hot-reloading](https://docs.localstack.cloud/user-guide/tools/lambda-tools/hot-reloading/) Node.js [AWS Lambda](https://aws.amazon.com/lambda/) and [API Gateway](https://aws.amazon.com/api-gateway/) development environment. The features used in this guide require you to have [LocalStack Pro](https://localstack.cloud/pricing/). There is a trial membership available. Develop rapidly for the cloud without the associated costs, slow feedback, and risk of actual deployments. LocalStack also works with Pulumi, AWS CloudFormation/CDK, SAM, and more.
 
 **In this guide we will:**
 
@@ -14,11 +12,25 @@ This is a guide on how to set up [Terraform](https://developer.hashicorp.com/ter
 
 3. [Query your local REST API](./docs/query-your-api.md)
 
-## Why do I need to have LocalStack Pro?
 
-Some functionality like UpdateIntegration for API Gateway is not currently available for the community edition of LocalStack. It's possible to force the recreation of the API Gateway integration and get around this, but Pro includes a lot of other handy features, such as the [Resource Browser](https://docs.localstack.cloud/user-guide/web-application/resource-browser/) which is a web interface for browsing your LocalStack AWS resources.
 
-# Final Questions
-1. What sort of workflows is this setup good for?
-2. What are some of the limitations of this setup?
-3. Is it better to run the lambda manually or through LocalStack?
+## Key Files/Directories
+
+- 📁 /cdktf
+  - Terraform CDK code used to create and manage AWS resources
+- 📁 /docs
+  - Markdown documentation about the project
+- 📁 /lambda
+  - Very simple lambda function that returns a JSON object `{ message: 'Hello World' }` and `200` http status code
+- 📄.env.example
+  - File that contains LocalStack Pro key, copy this to a `.env` file
+- 📄main.tf
+  - Primary Terraform HCL file used to create and manage AWS resources
+
+
+
+
+
+## Why do I need to have LocalStack Pro?
+
+Some functionality like [UpdateIntegration](https://docs.localstack.cloud/references/coverage/coverage_apigatewayv2/#updateintegration) for API Gateway is not currently available for the community edition of LocalStack. It's possible to force the recreation of the API Gateway integration and get around this, but Pro includes a lot of other handy features, such as the [Resource Browser](https://docs.localstack.cloud/user-guide/web-application/resource-browser/) which is a web interface for browsing your LocalStack AWS resources.

cdktf/src/localstack-config.ts

@@ -29,11 +29,18 @@ const endpoints =  [
 ];
 
 export const AWS_CONFIG = {
-	skipCredentialsValidation: true,
-	skipMetadataApiCheck: "true",
-	skipRequestingAccountId: true,
-	accessKey: "fakeKeyForLocalTesting",
-	secretKey: "fakeSecretForLocalTesting",
-	region: "us-east-1",
-	endpoints
+	local: {
+		skipCredentialsValidation: true,
+		skipMetadataApiCheck: "true",
+		skipRequestingAccountId: true,
+		accessKey: "fakeKeyForLocalTesting",
+		secretKey: "fakeSecretForLocalTesting",
+		region: "us-east-1",
+		endpoints
+	},
+	prod: {
+		accessKey: "realKeyForProduction",
+		secretKey: "realSecretForProduction",
+		region: "us-east-1"
+	}
 };

cdktf/src/main.ts

@@ -39,7 +39,7 @@ class LambdaAPIStack extends TerraformStack {
 
 		new ArchiveProvider(this, 'archive', {});
 
-		new AwsProvider(this, 'aws', AWS_CONFIG);
+		new AwsProvider(this, 'aws', STAGE === "local" ? AWS_CONFIG.local : AWS_CONFIG.prod);
 
 		const archiveFile = new DataArchiveFile(this, 'cdk_lambda_zip', {
 			type: 'zip',
@@ -66,9 +66,9 @@ class LambdaAPIStack extends TerraformStack {
 
 		const fun = new LambdaFunction(this, 'cdk_lambda', {
 			functionName: configValues.lambda.name,
-			s3Bucket: STAGE == "local" ? "hot-reload" : null,
-			s3Key: STAGE == "local" ? lambdaDirectory : null,
-			filename: STAGE == "local" ? null : archiveFile.outputPath,
+			s3Bucket: STAGE === "local" ? "hot-reload" : null,
+			s3Key: STAGE === "local" ? lambdaDirectory : null,
+			filename: STAGE === "local" ? null : archiveFile.outputPath,
 			sourceCodeHash: archiveFile.outputBase64Sha256,
 			handler: 'index.handler',
 			runtime: 'nodejs18.x',

docs/initial-setup.md

@@ -5,24 +5,24 @@ This setup will get you started with LocalStack and common functionality shared
 To set up the project you'll need to:
 
 1. Install Node and PNPM
-   1. NVM will let you easily manage the version of Node you are currently using (I used v20 as of writing this)
+   1. NVM will let you easily manage the version of Node you are currently using
       1. [Windows NVM](https://github.com/coreybutler/nvm-windows)
       2. [Linux/MacOS NVM](https://github.com/nvm-sh/nvm)
    2. [PNPM](https://pnpm.io/installation) is a package manager for Node, like NPM and Yarn. 
-      1. If you prefer NPM or Yarn, you could delete the pnpm-lock.yaml files, but this could break the project! 
+      1. If you prefer NPM or Yarn, you can delete the pnpm-lock.yaml files, but this could break the project! 
 2. [Install Docker](https://docs.docker.com/engine/install/)
    1. Localstack runs as a Docker container, so we need to [install Docker](https://docs.docker.com/engine/install/) first. Here's a handy GUI client for managing Docker containers, images, and volumes: [(Docker Desktop)](https://www.docker.com/products/docker-desktop).
 3. Install Python and pip
    1. Localstack is installed using Python's package manager, pip. You can download Python from [here](https://www.python.org/downloads/). Pip is included in Python 3.4 and above. But just in case here is pip (https://pypi.org/project/pip/) 
 4. [Install LocalStack CLI](https://docs.localstack.cloud/getting-started/installation/)
    1. `python -m pip install localstack`
 5. [Generate a LocalStack API key](https://app.localstack.cloud/account/apikeys)
-6. Copy `.env.example` to `.env` and replace the `LOCALSTACK_API_KEY` value with the key you generated in the LocalStack web interface.
+6. Copy `.env.example` file to a new file named `.env` and replace the `LOCALSTACK_API_KEY` value with the key you generated in the LocalStack web interface.
 7. Install root project dependencies with PNPM
    1. Run `pnpm install` in the project root
    2. This installs the dotenv-cli which we use to read your LocalStack API token from the .env file. This is used to ensure you download and activate LocalStack Pro.
 8. Start the LocalStack Pro Docker container
    1. Run `pnpm run start:localstack` in the project root
-   2. This convenience function reads you LocalStack API token and passes it to the LocalStack CLI  command `localstack start -d`
+   2. This convenience function reads your LocalStack API token and passes it to the LocalStack CLI command `localstack start -d`
       1. The `-d` flag starts LocalStack detached, so you can close your terminal without stopping the Docker container.
 9. You are now ready to configure your IaC provider, return to the project root [README](../README.md) and select your desired IaC provider.

docs/query-your-api.md

@@ -1,6 +1,6 @@
 # Query Your REST API Endpoint
-1. Assemble an HTTP request using the API Gateway ID you noted earlier
-2. Syntax: `http://<API Gateway ID>.execute-api.localhost.localstack.cloud:4566/<stageId>/<path>`
+1. Assemble an HTTP request using the API Gateway ID you noted earlier in the IAC setup step ([Terraform HCL](./iac/terraform-hcl.md) OR [Terraform CDK](./iac/terraform-cdk.md))
+2. Endpoint Syntax: `http://<API Gateway ID>.execute-api.localhost.localstack.cloud:4566/<stageId>/<path>`
 3. Example Endpoint: `http://1ltvwqpuju.execute-api.localhost.localstack.cloud:4566/local/test`
 4. Example cURL:
 

main.tf

@@ -1,16 +1,23 @@
+// One option for differentiating environments is to use a variable
 variable "STAGE" {
   type    = string
   default = "local"
 }
 
-// Set our AWS region
 provider "aws" {
+  // Set our AWS region
   region = "us-east-1"
-  skip_credentials_validation = true
-  skip_metadata_api_check     = true
-  skip_requesting_account_id  = true
-  access_key = "fakeKeyForLocalTesting"
-  secretKey = "fakeSecretForLocalTesting"
+
+  // Skip AWS credentials validation if we're running locally
+  skip_credentials_validation = var.STAGE == "local"
+  skip_metadata_api_check     = var.STAGE == "local"
+  skip_requesting_account_id  = var.STAGE == "local"
+
+  // You can use these fake keys for local AWS testing
+  access_key = var.STAGE == "local" ? "fakeKeyForLocalTesting" : "realKeyForProduction"
+  secretKey = var.STAGE == "local" ? "fakeSecretForLocalTesting" : "realSecretForProduction"
+
+  // Configure LocalStack as our AWS endpoints if we're running locally
   endpoints {
     apigateway       = var.STAGE == "local" ? "http://localhost:4566" : null
     cloudformation   = var.STAGE == "local" ? "http://localhost:4566" : null
@@ -32,9 +39,13 @@ data "archive_file" "lambda_zip" {
 // Create the lambda function resource with our build ZIP file
 resource "aws_lambda_function" "lambda" {
   function_name = "myTestLambda"
+  // This 'hot-reload' bucket name is used by LocalStack to mount our lambda code
   s3_bucket     = var.STAGE == "local" ? "hot-reload" : null
+  // This directory needs to be the location of the lambda code on your local machine
   s3_key        = var.STAGE == "local" ? "${path.cwd}/lambda" : null
+  // This is the name of the zip file we created above, this is only used in production
   filename      = var.STAGE == "local" ? null : data.archive_file.lambda_zip.output_path
+  // Used to determine if code has changed and the lambda needs to be redeployed
   source_code_hash = data.archive_file.lambda_zip.output_base64sha256
   handler       = "index.handler"
   runtime       = "nodejs18.x"