GitHub - uatec/teleform: Local development for AWS Lambda's and Terraform

3 min read Original article ↗

Teleform

Develop Locally. Deploy Globally. Debug Effortlessly.

Teleform is a Terraform-native tool designed to revolutionise the way you develop and debug AWS Lambda functions. By providing a transparent wrapper around the AWS Lambda resource in Terraform, Teleform enables you to run and debug Lambda functions directly on your local machine while interacting with live AWS infrastructure.

Key Features

  • Transparent Proxy: Intercept Lambda invocation requests and route them to your local environment with a simple Terraform flag.
  • Local Debugging: Code and debug Lambda functions locally, without the need for constant redeployment.
  • Ngrok Integration: Securely connect your AWS environment to your local machine using ngrok for real-time, cloud-connected debugging.
  • Terraform-Native: Works seamlessly within your existing Terraform workflow without additional complexity or setup.

Table of Contents

Installation

To get started with Teleform, you'll need to add the tool to your existing Terraform configuration.

npm install @uatec/teleform-cli

Usage

Step 1: Wrap Your Lambda in Teleform

Modify your existing Terraform AWS Lambda resource to use Teleform as a wrapper.

module "my_function" {
  source       = "git::ssh://git@github.com/uatec/teleform.git//packages/terraform"
  name         = "my-lambda"
  handler      = "index.handler"
  runtime      = "nodejs20.x"
  role         = aws_iam_role.lambda_exec.arn
  environment {
    variables = {
      foo = "bar"
    }
  }
}

Step 2: Deploy your code to was the normal way

The teleform terraform module will deploy your aws_lambda_function with no modifications, suitable for deployment in to production.

Step 3: Start the Local Lambda Invocation Server

Once your lambda function is deployed, begin your development experience using terraform

This will re-deploy your terraform, but replace your lambda functions with a proxy which will route the request to your local machine.

Step 4: Debug Locally

Now, any invocation of your Lambda function in AWS will be routed through to your local machine, allowing you to step through and debug your code in real time.

How It Works

  1. Proxy Deployment: Teleform deploys a proxy Lambda that intercepts invocation requests, forwarding them to your local machine via ngrok.
  2. Ngrok Tunnel: Ngrok creates a secure tunnel between AWS and your local environment.
  3. Local Invocation: The Lambda invocation is handled locally, where your function is executed from your file system for debugging.

Examples

A working example project can be found in examples/simple.

Contributing

We welcome contributions to improve Teleform! If you find a bug or have a feature request, feel free to open an issue or submit a pull request.

Steps to Contribute:

  1. Fork this repository.
  2. Create a new feature branch (git checkout -b feature/my-feature).
  3. Make your changes.
  4. Commit your changes (git commit -m "Add new feature").
  5. Push to the branch (git push origin feature/my-feature).
  6. Open a pull request.

License

Teleform is licensed under the MIT License. See the LICENSE file for more information.

Roadmap

Phase 0 - something that works

  • intercepter terraform
  • invocation forwarder
  • local server
  • total set up script
  • wire up env vars
  • wire up other parameters
  • resolve path to function from terraform aws_lambda_function parameters, not from the function name
  • git commit
  • ngrok client
  • CI/CD

Phase 1 - Something that people can use

  • client component discovery
  • remove any hardcoded paths
  • align module API with aws_lambda_function
  • secure public endpoint
    • cli
    • localserver
    • terraform
    • invocation forwarder
  • clean up processes (local server)

Phase 😕

  • teleform devex - cache-bust the debug_lambda?
  • enter vpc
  • local-server error handling