AWS Lambda Terraform module

Terraform module to create AWS Lambda and accompanying resources for an efficient and secure development of Lambda functions like:

• inline declaration of triggers for DynamodDb, EventBridge (CloudWatch Events), Kinesis, SNS or SQS including all required permissions
• IAM role with permissions following the principle of least privilege
• CloudWatch Logs and Lambda Insights configuration
• blue/green deployments with AWS CodePipeline and CodeDeploy

Features

• IAM role with permissions following the principle of least privilege
• inline declaration of Event Source Mappings for DynamoDb, Kinesis and SQS triggers including required permissions (see examples).
• inline declaration of SNS Topic Subscriptions including required Lambda permissions (see example)
• inline declaration of CloudWatch Event Rules including required Lambda permissions (see example)
• IAM permissions for read access to parameters from AWS Systems Manager Parameter Store
• CloudWatch Log group configuration including retention time and subscription filters with required permissions to stream logs to other Lambda functions (e.g. forwarding logs to Elasticsearch)
• Lambda@Edge support fulfilling requirements for CloudFront triggers. Functions need to be deployed to US East (N. Virginia) region (us-east-1)
• configuration for Amazon CloudWatch Lambda Insights including required permissions and Lambda Layer, see details
• add-on module for controlled blue/green deployments using AWS CodePipeline and CodeDeploy including all required permissions (see examples). Optionally ignore terraform state changes resulting from those deployments (using ignore_external_function_updates).

How do I use this module?

The module can be used for all runtimes supported by AWS Lambda.

Deployment packages can be specified either directly as a local file (using the filename argument), indirectly via Amazon S3 (using the s3_bucket, s3_key and s3_object_versions arguments) or using container images (using image_uri and package_type arguments), see documentation for details.

basic

see example for other configuration options

provider "aws" {
  region = "eu-west-1"
}

module "lambda" {
  source           = "moritzzimmer/lambda/aws"

  filename         = "my-package.zip"
  function_name    = "my-function"
  handler          = "my-handler"
  runtime          = "go1.x"
  source_code_hash = filebase64sha256("${path.module}/my-package.zip")
}

using container images

see example for details

module "lambda" {
  source        = "moritzzimmer/lambda/aws"

  function_name = "my-function"
  image_uri     = "111111111111.dkr.ecr.eu-west-1.amazonaws.com/my-image"
  package_type  = "Image"
}

with Amazon EventBridge (CloudWatch Events) rules

CloudWatch Event Rules to trigger your Lambda function by EventBridge patterns or on a regular, scheduled basis can be declared inline. The module will create the required Lambda permissions automatically.

see example for details

module "lambda" {
  // see above

  cloudwatch_event_rules = {
    scheduled = {
      schedule_expression = "rate(1 minute)"

      // optionally overwrite arguments like 'description'
      // from https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_event_rule
      description = "Triggered by CloudTrail"

      // optionally overwrite `cloudwatch_event_target_arn` in case an alias should be used for the event rule
      cloudwatch_event_target_arn = aws_lambda_alias.example.arn

      // optionally add `cloudwatch_event_target_input` for event input
      cloudwatch_event_target_input = jsonencode({"key": "value"})
    }

    pattern = {
      event_pattern = <<PATTERN
      {
        "detail-type": [
          "AWS Console Sign In via CloudTrail"
        ]
      }
      PATTERN
    }
  }
}

with event source mappings

Event Source Mappings to trigger your Lambda function by DynamoDb, Kinesis and SQS can be declared inline. The module will add the required read-only IAM permissions depending on the event source type to the function role automatically (including support for dedicated-throughput consumers using enhanced fan-out).

Permissions to send discarded batches to SNS or SQS will be added automatically, if destination_arn_on_failure is configured.

see examples for details

DynamoDb

module "lambda" {
  // see above

  event_source_mappings = {
    table_1 = {
      event_source_arn  = aws_dynamodb_table.table_1.stream_arn

      // optionally overwrite arguments like 'batch_size'
      // from https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lambda_event_source_mapping
      batch_size        = 50
      starting_position = "LATEST"

      // optionally configure a SNS or SQS destination for discarded batches, required IAM
      // permissions will be added automatically by this module,
      // see https://docs.aws.amazon.com/lambda/latest/dg/invocation-eventsourcemapping.html
      destination_arn_on_failure = aws_sqs_queue.errors.arn

      // optionally overwrite function_name in case an alias should be used in the
      // event source mapping, see https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html
      function_name = aws_lambda_alias.example.arn

      // Lambda event filtering, see https://docs.aws.amazon.com/lambda/latest/dg/invocation-eventfiltering.html
      filter_criteria = [
        {
          pattern = jsonencode({
            data : {
              Key1 : ["Value1"]
            }
          })
        },
        {
          pattern = jsonencode({
            data : {
              Key2 : [{ "anything-but" : ["Value2"] }]
            }
          })
        }
      ]
    }

    table_2 = {
      event_source_arn = aws_dynamodb_table.table_2.stream_arn
    }
  }
}

Kinesis

resource "aws_kinesis_stream_consumer" "this" {
  name       = module.lambda.function_name
  stream_arn = aws_kinesis_stream.stream_2.arn
}

module "lambda" {
  // see above

  event_source_mappings = {
    stream_1 = {
      // To use a dedicated-throughput consumer with enhanced fan-out, specify the consumer's ARN instead of the stream's ARN, see https://docs.aws.amazon.com/lambda/latest/dg/with-kinesis.html#services-kinesis-configure
      event_source_arn = aws_kinesis_stream_consumer.this.arn
    }
  }
}

with SNS subscriptions

SNS Topic Subscriptions to trigger your Lambda function by SNS can de declared inline. The module will create the required Lambda permissions automatically.

see example for details

module "lambda" {
  // see above

  sns_subscriptions = {
    topic_1 = {
      topic_arn = aws_sns_topic.topic_1.arn

      // optionally overwrite `endpoint` in case an alias should be used for the SNS subscription
      endpoint  = aws_lambda_alias.example.arn
    }

    topic_2 = {
      topic_arn = aws_sns_topic.topic_2.arn
    }
  }
}

with access to AWS Systems Manager Parameter Store

Required IAM permissions to get parameter(s) from AWS Systems Manager Parameter Store (by path or name) can added to the Lambda role:

module "lambda" {
  // see above

  ssm = {
      parameter_names = [aws_ssm_parameter.string.name, aws_ssm_parameter.secure_string.name]
  }
}

with CloudWatch Logs configuration

The module will create a CloudWatch Log Group for your Lambda function. It's retention period and CloudWatch Logs subscription filters to stream logs to other Lambda functions (e.g. to forward logs to Amazon OpenSearch Service) can be declared inline.

The module will create the required Lambda permissions automatically. Sending logs to CloudWatch can be disabled with cloudwatch_logs_enabled = false

see example for details

module "lambda" {
  // see above

  // disable CloudWatch logs
  // cloudwatch_logs_enabled = false

  cloudwatch_logs_retention_in_days = 14

  cloudwatch_log_subscription_filters = {
    lambda_1 = {
      //see https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_log_subscription_filter for available arguments
      destination_arn = module.destination_1.arn
    }

    lambda_2 = {
      destination_arn = module.destination_2.arn
    }
  }
}

with CloudWatch Lambda Insights

Amazon CloudWatch Lambda Insights can be enabled for zip and image function deployment packages of all runtimes supporting Lambda extensions.

This module will add the required IAM permissions to the function role automatically for both package types. In case of a zip deployment package, the region and architecture specific layer version needs to specified in layers.

module "lambda" {
  // see above

  cloudwatch_lambda_insights_enabled = true

  // see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-extension-versions.html
  layers = "arn:aws:lambda:eu-west-1:580247275435:layer:LambdaInsightsExtension:16"
}

For image deployment packages, the Lambda Insights extension needs to be added to the container image:

FROM public.ecr.aws/lambda/nodejs:12

RUN curl -O https://lambda-insights-extension.s3-ap-northeast-1.amazonaws.com/amazon_linux/lambda-insights-extension.rpm && \
    rpm -U lambda-insights-extension.rpm && \
    rm -f lambda-insights-extension.rpm

COPY index.js /var/task/

Deployments

Controlled, blue/green deployments of Lambda functions with (automatic) rollbacks and traffic shifting can be implemented using Lambda aliases and AWS CodeDeploy.

The deployment submodule can be used to create the required AWS CodePipeline, CodeBuild and CodeDeploy resources and permissions to execute secure deployments of S3 or containerized Lambda functions in your AWS account, see examples for details.

Examples

• complete
• container-image
• deployment
• with-cloudwatch-event-rules
• with-cloudwatch-logs-subscription
• with-event-source-mappings
• with-sns-subscriptions

Bootstrap new projects

In case you are using go for developing your Lambda functions, you can also use func to bootstrap your project and get started quickly.

How do I contribute to this module?

Contributions are very welcome! Check out the Contribution Guidelines for instructions.

How is this module versioned?

This Module follows the principles of Semantic Versioning. You can find each new release in the releases page.

During initial development, the major version will be 0 (e.g., 0.x.y), which indicates the code does not yet have a stable API. Once we hit 1.0.0, we will make every effort to maintain a backwards compatible API and use the MAJOR, MINOR, and PATCH versions on each release to indicate any incompatibilities.

History

Implementation of this module started at Spring Media/Welt. Users of spring-media/lambda/aws should migrate to this module as a drop-in replacement to benefit from new features and bugfixes.

Requirements

Providers

Modules

No modules.

Resources

Inputs

object({
    variables = map(string)
  })

object({
    parameter_names = list(string)
  })

object({
    security_group_ids = list(string)
    subnet_ids         = list(string)
  })

Outputs