AWS Step Functions Terraform module

Terraform module, which creates AWS Step Functions as well as required IAM role and IAM policies for Integrated Services.

This Terraform module is the part of serverless.tf framework, which aims to simplify all operations when working with the serverless in Terraform.

Features

• Creates AWS Step Function
• Conditional creation for many types of resources
• Support IAM policy attachments for Integrated Services (eg, Lambda, SQS, ECS, EKS, Batch, DynamoDB, etc) and various ways to create and attach additional policies

Usage

Step Function

module "step_function" {
  source = "terraform-aws-modules/step-functions/aws"

  name       = "my-step-function"
  definition = <<EOF
{
  "Comment": "A Hello World example of the Amazon States Language using Pass states",
  "StartAt": "Hello",
  "States": {
    "Hello": {
      "Type": "Pass",
      "Result": "Hello",
      "Next": "World"
    },
    "World": {
      "Type": "Pass",
      "Result": "World",
      "End": true
    }
  }
}
EOF

  service_integrations = {
    dynamodb = {
      dynamodb = ["arn:aws:dynamodb:eu-west-1:052212379155:table/Test"]
    }

    lambda = {
      lambda = ["arn:aws:lambda:eu-west-1:123456789012:function:test1", "arn:aws:lambda:eu-west-1:123456789012:function:test2"]
    }

    stepfunction_Sync = {
      stepfunction = ["arn:aws:states:eu-west-1:123456789012:stateMachine:test1"]
      stepfunction_Wildcard = ["arn:aws:states:eu-west-1:123456789012:stateMachine:test1"]

      # Set to true to use the default events (otherwise, set this to a list of ARNs; see the docs linked in locals.tf
      # for more information). Without events permissions, you will get an error similar to this:
      #   Error: AccessDeniedException: 'arn:aws:iam::xxxx:role/step-functions-role' is not authorized to
      #   create managed-rule
      events = true
    }
  }

  type = "STANDARD"

  tags = {
    Module = "my"
  }
}

Service integration policies

There are predefined policies for all available integrations (see aws_service_policies in locals.tf for values) which can be used as a key inside service_integrations argument.

Each key of aws_service_policies contains configuration for the IAM policy statements which will be combined with the values specified in service_integrations argument.

Example of service_integrations arguments:

module "step_function" {
  source = "terraform-aws-modules/step-functions/aws"

  # ... omitted
  service_integrations = {
    xray = {
      xray = true  # the value of default_resources key will be used when key value is `true`
    }

    sqs = {
      sqs = ["arn:aws:sqs:..."]  # sqs queue ARN is required because there is no default_resources key for such integration
    }

    # Special case to deny all actions for the step function (this will override all IAM policies allowed for the function)
    no_tasks = {
      deny_all = true
    }
  }
}

Additional IAM policies for Step Function

In addition to all supported AWS service integrations you may want to create and attach additional policies.

There are 5 supported ways to attach additional IAM policies to IAM role used by Step Function:

1. policy_json - JSON string or heredoc, when attach_policy_json = true.
2. policy_jsons - List of JSON strings or heredoc, when attach_policy_jsons = true and number_of_policy_jsons > 0.
3. policy - ARN of existing IAM policy, when attach_policy = true.
4. policies - List of ARNs of existing IAM policies, when attach_policies = true and number_of_policies > 0.
5. policy_statements - Map of maps to define IAM statements which will be generated as IAM policy. Requires attach_policy_statements = true. See examples/complete for more information.

Conditional creation

Sometimes you need to have a way to create resources conditionally, so the solution is to specify create arguments.

module "step_function" {
  source = "terraform-aws-modules/step-functions/aws"

  create      = false # to disable all resources
  create_role = false  # to control creation of the IAM role and policies required for Step Function

  # ... omitted
}

Examples

• Complete - Create Step Function and required IAM resources in various combinations with all supported features.

Requirements

Name	Version
terraform	>= 0.13.1
aws	>= 3.27

Providers

Name	Version
aws	>= 3.27

Modules

No modules.

Resources

Name	Type
aws_cloudwatch_log_group.sfn	resource
aws_iam_policy.additional_inline	resource
aws_iam_policy.additional_json	resource
aws_iam_policy.additional_jsons	resource
aws_iam_policy.logs	resource
aws_iam_policy.service	resource
aws_iam_policy_attachment.additional_inline	resource
aws_iam_policy_attachment.additional_json	resource
aws_iam_policy_attachment.additional_jsons	resource
aws_iam_policy_attachment.logs	resource
aws_iam_policy_attachment.service	resource
aws_iam_role.this	resource
aws_iam_role_policy_attachment.additional_many	resource
aws_iam_role_policy_attachment.additional_one	resource
aws_sfn_state_machine.this	resource
aws_caller_identity.current	data source
aws_cloudwatch_log_group.sfn	data source
aws_iam_policy_document.additional_inline	data source
aws_iam_policy_document.assume_role	data source
aws_iam_policy_document.logs	data source
aws_iam_policy_document.service	data source
aws_region.current	data source

Inputs

Name	Description	Type	Default	Required
attach_cloudwatch_logs_policy	Controls whether CloudWatch Logs policy should be added to IAM role for Lambda Function	bool	true	no
attach_policies	Controls whether list of policies should be added to IAM role	bool	false	no
attach_policies_for_integrations	Whether to attach AWS Service policies to IAM role	bool	true	no
attach_policy	Controls whether policy should be added to IAM role	bool	false	no
attach_policy_json	Controls whether policy_json should be added to IAM role	bool	false	no
attach_policy_jsons	Controls whether policy_jsons should be added to IAM role	bool	false	no
attach_policy_statements	Controls whether policy_statements should be added to IAM role	bool	false	no
aws_region_assume_role	Name of AWS regions where IAM role can be assumed by the Step Function	string	""	no
cloudwatch_log_group_kms_key_id	The ARN of the KMS Key to use when encrypting log data.	string	null	no
cloudwatch_log_group_name	Name of Cloudwatch Logs group name to use.	string	null	no
cloudwatch_log_group_retention_in_days	Specifies the number of days you want to retain log events in the specified log group. Possible values are: 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, and 3653.	number	null	no
cloudwatch_log_group_tags	A map of tags to assign to the resource.	map(string)	{}	no
create	Whether to create Step Function resource	bool	true	no
create_role	Whether to create IAM role for the Step Function	bool	true	no
definition	The Amazon States Language definition of the Step Function	string	""	no
logging_configuration	Defines what execution history events are logged and where they are logged	map(string)	{}	no
name	The name of the Step Function	string	""	no
number_of_policies	Number of policies to attach to IAM role	number	0	no
number_of_policy_jsons	Number of policies JSON to attach to IAM role	number	0	no
policies	List of policy statements ARN to attach to IAM role	list(string)	[]	no
policy	An additional policy document ARN to attach to IAM role	string	null	no
policy_json	An additional policy document as JSON to attach to IAM role	string	null	no
policy_jsons	List of additional policy documents as JSON to attach to IAM role	list(string)	[]	no
policy_statements	Map of dynamic policy statements to attach to IAM role	any	{}	no
role_arn	The Amazon Resource Name (ARN) of the IAM role to use for this Step Function	string	""	no
role_description	Description of IAM role to use for Step Function	string	null	no
role_force_detach_policies	Specifies to force detaching any policies the IAM role has before destroying it.	bool	true	no
role_name	Name of IAM role to use for Step Function	string	null	no
role_path	Path of IAM role to use for Step Function	string	null	no
role_permissions_boundary	The ARN of the policy that is used to set the permissions boundary for the IAM role used by Step Function	string	null	no
role_tags	A map of tags to assign to IAM role	map(string)	{}	no
service_integrations	Map of AWS service integrations to allow in IAM role policy	any	{}	no
tags	Maps of tags to assign to the Step Function	map(string)	{}	no
trusted_entities	Step Function additional trusted entities for assuming roles (trust relationship)	list(string)	[]	no
type	Determines whether a Standard or Express state machine is created. The default is STANDARD. Valid Values: STANDARD | EXPRESS	string	"STANDARD"	no
use_existing_cloudwatch_log_group	Whether to use an existing CloudWatch log group or create new	bool	false	no
use_existing_role	Whether to use an existing IAM role for this Step Function	bool	false	no

Outputs

Name	Description
cloudwatch_log_group_arn	The ARN of the CloudWatch log group created for the Step Function
cloudwatch_log_group_name	The name of the CloudWatch log group created for the Step Function
role_arn	The ARN of the IAM role created for the Step Function
role_name	The name of the IAM role created for the Step Function
state_machine_arn	The ARN of the Step Function
state_machine_creation_date	The date the Step Function was created
state_machine_id	The ARN of the Step Function
state_machine_status	The current status of the Step Function

Authors

Module managed by Anton Babenko. Check out serverless.tf to learn more about doing serverless with Terraform.

Please reach out to Betajob if you are looking for commercial support for your Terraform, AWS, or serverless project.

License

Apache 2 Licensed. See LICENSE for full details.