Automate Lambda function registration

This topic describes how to automate Lambda function registration using Consul’s Lambda registrator module for Terraform.

Introduction

You can deploy the Lambda registrator to your environment to automatically register and deregister Lambda functions with Consul based on the function’s tags. Refer to the AWS Lambda tags documentation to learn about tags.

The registrator also stores and periodically updates information required to make mTLS requests to upstream services in the AWS parameter store. This enables Lambda functions to invoke mesh services. Refer to Invoke Services from Lambda Functions for additional information.

The registrator runs as a Lambda function that is invoked by AWS EventBridge. Refer to the AWS EventBridge documentation for additional information.

EventBridge invokes the registrator using either AWS CloudTrail to synchronize with Consul in real-time or in scheduled intervals.

CloudTrail events typically synchronize updates, registration, and deregistration within one minute, but events may occasionally be delayed.

Scheduled events fully synchronize functions between Lambda and Consul to prevent entropy. By default, EventBridge triggers a full sync every five minutes.

The following diagram shows the flow of events from EventBridge into Consul:

Lambda Registrator Architecture

  1. EventBridge invokes the Lambda registrator based on CloudTrail Lambda events or a schedule.
  2. Lambda registrator determines how to reconcile Lambda’s control plane state with Consul state and ensures they are in sync by registering, updating, and deregistering Lambda services.

Requirements

Verify that your environment meets the requirements specified in Lambda Function Registration Requirements.

Configuration

The Lambda registrator stores data in the AWS Parameter Store. You can configure the type of data stored and how to store it.

Optional: Store the CA certificate in Parameter Store

When Lambda registrator makes a request to Consul’s HTTP API over HTTPS and the Consul API is signed by a custom CA, Lambda registrator uses the CA certificate stored in AWS Parameter Store to verify the authenticity of the Consul API. Refer to the Parameter Store documentation for additional information.

You can apply the following Terraform configuration to store Consul’s server CA in Parameter Store:

  1. resource "aws_ssm_parameter" "ca-cert" {
  2.   name        = "/lambda-registrator/ca-cert"
  3.   type        = "SecureString"
  4.   value       = <VALUE>
  5. }

Optional: Store the ACL token in Parameter Store

If Consul access control lists (ACLs) are enabled, Lambda registrator must present an ACL token stored in Parameter Store to access resources. You can use the Consul CLI, API, or the Terraform provider to facilitate the ACL workflow. The following procedure describes how to create and store a token from the command line:

  1. Create an ACL policy that includes the following rule:

    Automate Registration - 图2

    rules.hcl

    1.  service_prefix "" {
    2.      policy = "write"
    3.  }

  2. Run consul acl policy create to create the policy. The following example creates a policy called lambda-registrator-policy containing permissions specified in rules.hcl:

    1.  $ consul acl policy create -name "lambda-registrator-policy" -rules @rules.hcl

  3. Issue the consul acl token create command to create the token. The following example creates a token linked to the lambda-registrator-policy policy:

    1.  $ consul acl token create -policy-name "lambda-registrator-policy"

  4. Store the token in Parameter Store by applying the following Terraform:

    1. resource "aws_ssm_parameter" "acl-token" {
    2.     name        = "/lambda-registrator/acl-token"
    3.     type        = "SecureString"
    4.     value       = <VALUE>
    5.  }

Optional: Store extension data in Parameter Store

If you want to enable Lambda functions to invoke services in the mesh, then you must specify a non-empty string in the consul_extension_data_prefix configuration. The string represents a path in the AWS Parameter Store so that the registrator can store data necessary for making mTLS requests to upstream services and update the data periodically. If the path does not exist it will be created.

Lambda registrator encrypts and stores all data for Lambda functions in the AWS Parameter Store according to the Lambda registrator configuration options. The data is stored in the following directory as a SecureString type:

${consul_extension_data_prefix}/${<partition>}/${<namespace>}/${<service_name>}

The registrator also requires the following IAM permissions to access the parameter store:

  1. {
  2.     "Version": "2012-10-17",
  3.     "Statement": [
  4.         {
  5.             "Effect": "Allow",
  6.             "Action": ["ssm:PutParameter","ssm:DeleteParameter"],
  7.             "Resource": "arn:aws:ssm:us-east-2:123456789012:parameter/${var.consul_extension_data_prefix}/*"
  8.         },
  9.     ]
  10. }

Lambda Registrator configuration options

NameDescription
nameSpecifies the name of the Lambda function associated with the Lambda registrator. The name is also used to construct the Identity and Access Management (IAM) role and policy names used by the Lambda function.
sync_frequency_in_minutesSpecifies the interval in minutes that EventBridge uses to trigger a full synchronization. Default is 10.
timeoutThe maximum number of seconds Lambda registrator can run per invocation before timing out.
consul_http_addrSpecifies the address of the Consul API client.
consul_datacenterSpecifies the Consul datacenter to synchronize with AWS Lambda state data. By default, the Lambda registrator manages Lambda services for all Consul datacenters. When configured for a specific datacenter, Lambda registrator only manages Lambda services with a matching datacenter tag. Refer to Supported tags for additional information.
consul_extension_data_prefixSpecifies the path prefix in the AWS Parameter Store under which the registrator manages mTLS data. If Lambda functions call mesh services, the value must be set to a non-empty string starting with /.
consul_ca_cert_pathSpecifies the path to the CA certificate stored in the AWS Parameter Store. When Lambda registrator makes an HTTPS request to Consul’s API and the Consul API is signed by a custom CA, Lambda registrator uses this CA certificate to verify the authenticity of the Consul API. At startup, Lambda registrator pulls the CA certificate at this path from Parameter Store, writes the certificate to the filesystem and stores the path of that file in CONSUL_CACERT. Also refer to Optional: Store the CA Certificate in Parameter Store.
consul_http_token_pathSpecifies the path to the ACL token stored in AWS Parameter Store that Lambda registrator presents to access resources. This parameter is only required when ACLs are enabled for the Consul server. It is used to fetch an ACL token from Parameter Store and is stored in the CONSUL_HTTP_TOKEN environment variable. Also refer tp Optional: Store the ACL Token in Parameter Store.
node_nameThe Consul node name that Lambdas are registered to. Defaults to lambdas.
enterpriseEnterprise Determines if the Consul server at consul_http_addr is running open source Consul or Consul Enterprise.
partitionsEnterprise The partitions that Lambda registrator manages.

Deploy the Lambda registrator

  1. Create a Terraform configuration and specify the lambda-registrator module. In the following example, the Lambda registrator is deployed to https://consul.example.com:8501. Refer to the Lambda registrator module documentation for additional usage information:

    1. module "lambda-registrator" {
    2.    source  = "hashicorp/consul-lambda/consul-lambda-registrator"
    3.    version = "x.y.z"
    4.    name = "consul-lambda-registrator"
    5.    consul_http_addr = “https://aecfe39d629774e348a9844439f5e3c1-1471365273.us-east-1.elb.amazonaws.com:8501”
    6.    ca_cert_path = aws_ssm_parameter.ca-cert.name
    7.    http_token_path = aws_ssm_parameter.acl-token.name
    8.    consul_extension_data_prefix = “/lambda_extension_data”
    9. }

  2. Deploy Lambda registrator with terraform apply.

Register Lambda functions

Lambda registrator registers Lambda functions into Consul, regardless of how the functions are deployed. The following procedure describes how to register Lambda functions with the Lambda registrator using Terraform, but you can also deploy a Lambda function with CloudFormation, the AWS user interface, or Cloud Development Kit (CDK):

  1. Add the aws_lambda_function resource to your Terraform configuration and specify the name of the Lambda function.
  2. Add a tags block to the resource and specify the tags you want to use to register the function (refer to Supported tags).

In the following example, the example Lambda function is registered using the enabled, payload-passthrough, and invocation-mode tags:

  1. resource "aws_lambda_function" "example" {
  2.   …
  3.   function_name = "lambda"
  4.   tags = {
  5.     "serverless.consul.hashicorp.com/v1alpha1/lambda/enabled" = "true"
  6.     "serverless.consul.hashicorp.com/v1alpha1/lambda/payload-passthrough" = "true"
  7.     "serverless.consul.hashicorp.com/v1alpha1/lambda/invocation-mode" = "ASYNCHRONOUS"
  8.   }
  9. }

Supported tags

The following tags are supported. The path prefix for all tags is serverless.consul.hashicorp.com/v1alpha1/lambda. For example, specify the following tag to enable the Lambda registrator to sync the Lambda with Consul:

serverless.consul.hashicorp.com/v1alpha1/lambda/enabled.

TagDescription
<prefix-path>/enabledEnables the Lambda registrator to sync the Lambda with Consul.
<prefix-path>/payload-passthroughDetermines if the body Envoy receives is converted to JSON or directly passed to Lambda. This attribute is optional and defaults to false.
<prefix-path>/invocation-modeSpecifies the Lambda invocation mode Consul uses to invoke the Lambda. The default is SYNCHRONOUS, but ASYNCHRONOUS invocations are also supported.
<prefix-path>/datacenterSpecifies the Consul datacenter in which to register the service. The default is the datacenter configured for Lambda registrator.
<prefix-path>/namespace<EnterpriseAlert inline / >Specifies the Consul namespace the service is registered in. Default is default if enterprise is enabled.
<prefix-path>/partitionEnterprise Specifies the Consul partition the service is registered in. Defaults is default if enterprise is enabled.
<prefix-path>/aliasesSpecifies a +-separated string of Lambda aliases that are registered into Consul. For example, if set to dev+staging+prod, the dev, staging, and prod aliases of the Lambda function are registered into Consul.