Terraform AWS Postman Test Lambda

Terraform module that creates a generic lambda function that runs newman tests against a postman collection.

This lambda function is intended for use with CodeDeploy's lifecycle hooks. This lambda function will attempt to run the newman CLI to run your Postman collection as a test. This lambda function will tell CodeDeploy if the tests pass or fail.

New to Terraform Modules at BYU?

Usage

module "postman_test_lambda" {
  source = "github.com/byu-oit/terraform-aws-postman-test-lambda?ref=v5.0.3"
  app_name = "simple-example"
  postman_collections = [
    {
      collection = "terraform-aws-postman-test-lambda-example.postman_collection.json"
      environment = "terraform-aws-postman-test-lambda-env.postman_environment.json"
    }
  ]
  role_permissions_boundary_arn = data.aws_ssm_parameter.role_permissions_boundary_arn.value
}

You can specify multiple collections and environments to run in the lambda function. The function will run the collections in order.

You can run collections/environments from local json files or using the Postman API.

Note: When using the Postman API: the postman collections/environments must be viewable by the postman account tied to the API key you provide.

DON'T hard code your postman API key, treat it like all other secrets.

Then add your lambda function_name to the CodeDeploy lifecycle hook you want the postman tests to run on. For instance, if you're using the fargate-api module:

# ... postman-test-lambda module

module "fargate_api" {
  source = "github.com/byu-oit/terraform-aws-fargate-api?ref=" # latest version
  # .. all other variables
  codedeploy_lifecycle_hooks = {
    BeforeInstall         = null
    AfterInstall          = null
    AfterAllowTestTraffic = module.postman_test_lambda.lambda_function.function_name
    BeforeAllowTraffic    = null
    AfterAllowTraffic     = null
  }
}

Or if you're using the lambda-api module:

# ... postman-test-lambda module

module "lambda_api" {
  source = "github.com/byu-oit/terraform-aws-lambda-api?ref=" # latest version
  # .. all other variables
  codedeploy_lifecycle_hooks = {
    BeforeAllowTraffic = module.postman_test_lambda.lambda_function.function_name
    AfterAllowTraffic  = null
  }
}

Using the Postman API

If you don't want to export your postman collections/environments into json files in order to run tests you can use the Postman API. Using the Postman API allows you to keep your postman collections/environments in Postman and not have to worry about keeping json files up to date.

In order to use the Postman API to retrieve the collections/environments you will need to provide the postman_api_key. You can generate an API key from a Postman account. PLEASE DON'T hardcode the api key into your github repo.

Provide the collection and environment IDs instead of the name of each. You can find the ID on the v8 Postman Client by selecting your collection/environment and clicking on the info icon.

module "postman_test_lambda" {
  source = "github.com/byu-oit/terraform-aws-postman-test-lambda?ref=v5.0.3"
  app_name = "from-postman-api-example"
  postman_collections = [
    {
      collection  = "1117094-d4bd5a5f-c37c-4fe9-8723-3c3e8b1e2015" # terraform-aws-postman-test-lambda-example collection from postman TF Modules and HW Examples workspace
      environment = "1117094-95627910-aeb0-4aed-b959-7e2034e2f6ce" # terraform-aws-postman-test-lambda-env environment from postman TF Modules and HW Examples workspace
    }
  ]
  postman_api_key               = var.postman_api_key
  role_permissions_boundary_arn = data.aws_ssm_parameter.role_permissions_boundary_arn.value
}

Requirements

• Terraform version 1.3.0 or greater
• Terraform AWS Provider version 4.0.0 or greater
• Postman JSON collections/environments files (optional) if you want export them to JSON files and include them in your project repo
• Postman API (optional) if you want to download Postman collections/environments from Postman instead of providing the json files in your repo

Inputs

Name	Type	Description	Default
alb_wait_time	number	The number of seconds the Lambda function should wait for the new ALB target group to initialize before running tests. If you increase this, you may also need to increase timeout.	10
app_name	string	Application name to prefix your postman test lambda function's name
postman_collections	list(object)	List of postman collections and environments. See postman_collection
postman_api_key	string	Postman API key to download collections/environments from Postman API (must be provided if you provide any postman IDs in postman_collection variable)	null
role_permissions_boundary_arn	string	ARN of the IAM Role permissions boundary to place on each IAM role created
log_retention_in_days	number	CloudWatch log group and S3 log bucket retention in days	7
tags	map(string)	A map of AWS Tags to attach to each resource created	{}
timeout	number	The max number of seconds the lambda will run for without stopping.	30
memory_size	number	The size of the memory of the lambda	128
vpc_id	string	The id of the VPC the lambda will be behind if VPC configuration is desired. (must be provided with lambda_vpc_subnet_ids)	null
vpc_subnet_ids	list(string)	A list of subnet ids the lambda will be put in if VPC configuration is desired. (must be provided with vpc_id)	[]
test_env_var_overrides	map(string)	Values to set or override in the Postman test environment.	{}

postman_collection

Object defining the collection and environment to run.

• collection - (Required) path to local collection json file or Postman collection ID
• environment - (Optional) path to local environment json file or Postman environment ID (can be set to null if you don't want an environment on your postman collection)

Outputs

Name	Type	Description
lambda_function	object	Created lambda function that runs newman to test the postman_collection
lambda_iam_role	object	Created IAM role for the lambda_function
postman_files_bucket	object	Created S3 Bucket where local postman files are uploaded
cloudwatch_log_group	object	Created CloudWatch Log Group for the postman lambda logs
lambda_security_group	object	Created security group for the lambda's VPC configuration.

Contributing

To contribute to this terraform module make a feature branch and create a Pull Request to the master branch.

This terraform module bakes in the lambda function code in the committed function.zip file.

If you change the index.js file then you'll need to run npm run package and commit the function.zip file.