Skip to content

Latest commit

 

History

History
133 lines (105 loc) · 9.49 KB

README.md

File metadata and controls

133 lines (105 loc) · 9.49 KB
Raw

sudoblark.terraform.module.aws.event_bridge_rule

Terraform module to create N event bridge rules with targets and custom IAM policies. - repo managed by sudoblark.terraform.github

Developer documentation

The below documentation is intended to assist a developer with interacting with the Terraform module in order to add, remove or update functionality.

Pre-requisites

  • terraform_docs
brew install terraform_docs
  • tfenv
git clone https://github.com/tfutils/tfenv.git ~/.tfenv
echo 'export PATH="$HOME/.tfenv/bin:$PATH"' >> ~/.bash_profile
  • Virtual environment with pre-commit installed
python3 -m venv venv
source venv/bin/activate
pip install pre-commit

Pre-commit hooks

This repository utilises pre-commit in order to ensure a base level of quality on every commit. The hooks may be installed as follows:

source venv/bin/activate
pip install pre-commit
pre-commit install
pre-commit run --all-files

Module documentation

The below documentation is intended to assist users in utilising the module, the main thing to note is the data structure section which outlines the interface by which users are expected to interact with the module itself, and the examples section which has examples of how to utilise the module.

Requirements

Name Version
terraform ~> 1.5.0
aws >= 5.61.0

Providers

Name Version
aws 5.67.0

Modules

Name Source Version
rule ./modules/rule n/a
target ./modules/target n/a

Resources

Name Type
aws_iam_policy.invoke_policy resource
aws_iam_role.invoke_role resource
aws_iam_role_policy_attachment.invoke_role_policy resource
aws_lambda_permission.allow_lambda_execution_from_event_bridge resource
aws_iam_policy_document.allow_event_bridge_assume data source
aws_iam_policy_document.event_bridge_target_policy data source

Inputs

Name Description Type Default Required
application_name Name of the application utilising resource. string n/a yes
environment Which environment this is being instantiated in. string n/a yes
raw_event_bridge_rules Data structure
---------------
A list of dictionaries, where each dictionary has the following attributes:

REQUIRED
---------
- suffix : Friendly name for the rule in Event Bridge
- description : A friendly description of what the Event Bridge rule does
- targets : A list of dictionaries with the following attributes, defining what target this event triggers:
-- name : A friendly name for the target, if lambda this should be the lambda name
-- arn : The ARN of the resource being targeted
MUTUALLY EXCLUSIVE TARGETS INPUTS:
-- input : OPTIONAL JSON string of input to pass to target, defaults to null
-- input_path : OPTIONAL value of the JSONPath that is used for extracting part of the matched event when passing it to the target, defaults to null.
-- input_transformer : OPTIONAL parameters used when you are providing a custom input to a target based on certain event data, defaults to null.

One of the following, but not both:
- schedule : The scheduling expression. For example, cron(0 20 * * ? *) or rate(5 minutes)
- pattern : Pattern for the event to match on, should be jsonencoded dictionary

OPTIONAL
---------
By default we deploy event bridge rules as disabled, and ignore state on apply, such that
enabling/disabling event bridge rules is always a manual affair rather than doing via Terraform. But via the below
optional values this may be changed on a per-rule basis.

- state : By default DISABLED, can set to ENABLED or ENABLED_WITH_ALL_CLOUDTRAIL_MANAGEMENT_EVENTS
- ignore_state : By default true, can set to false.


IAM role Statement and Role Suffix to be used for this target when the rule is triggered.
Required if ecs_target is used or target in arn is EC2 instance, Kinesis data stream, Step Functions state machine,
or Event Bus in different account or region.
- iam_role_suffix : IAM role suffix for the event bridge Role having permission to invoke target AWS Service
- iam_policy_statements : A list of dictionaries where each dictionary is an IAM statement defining Event Bridge permissions
-- conditions : An OPTIONAL list of dictionaries, which each defines:
--- test : Test condition for limiting the action
--- variable : Value to test
--- values : A list of strings, denoting what to test for		 
list(
    object({
      suffix      = string,
      description = string,
      targets = optional(list(
        object({
          name       = string,
          arn        = string,
          input      = optional(string, null)
          input_path = optional(string, null)
          input_transformer = optional(object({
            input_template = string,
            input_paths    = optional(map(any), null)
          }), null)
      })), null),
      schedule        = optional(string, null),
      pattern         = optional(string, null),
      iam_role_suffix = optional(string, ""),
      iam_policy_statements = optional(list(
        object({
          sid       = string,
          actions   = list(string),
          resources = list(string),
          conditions = optional(list(
            object({
              test : string,
              variable : string,
              values = list(string)
            })
          ), [])
      })), []),
      state        = optional(string, "DISABLED"),
      ignore_state = optional(bool, true)
    })
  )
 n/a yes

Outputs

No outputs.

Data structure

Data structure
---------------
A list of dictionaries, where each dictionary has the following attributes:

REQUIRED
---------
- suffix                : Friendly name for the rule in Event Bridge
- description           : A friendly description of what the Event Bridge rule does
- targets               : A list of dictionaries with the following attributes, defining what target this event triggers:
-- name                 : A friendly name for the target, if lambda this should be the lambda name
-- arn                  : The ARN of the resource being targeted
MUTUALLY EXCLUSIVE TARGETS INPUTS:
-- input                : OPTIONAL JSON string of input to pass to target, defaults to null
-- input_path           : OPTIONAL value of the JSONPath that is used for extracting part of the matched event when passing it to the target, defaults to null.
-- input_transformer    : OPTIONAL parameters used when you are providing a custom input to a target based on certain event data, defaults to null.

One of the following, but not both:
- schedule              : The scheduling expression. For example, cron(0 20 * * ? *) or rate(5 minutes)
- pattern               : Pattern for the event to match on, should be jsonencoded dictionary

OPTIONAL
---------
By default we deploy event bridge rules as disabled, and ignore state on apply, such that
enabling/disabling event bridge rules is always a manual affair rather than doing via Terraform. But via the below
optional values this may be changed on a per-rule basis.

- state                 : By default DISABLED, can set to ENABLED or ENABLED_WITH_ALL_CLOUDTRAIL_MANAGEMENT_EVENTS
- ignore_state          : By default true, can set to false.


IAM role  Statement and Role Suffix to be used for this target when the rule is triggered.
Required if ecs_target is used or target in arn is EC2 instance, Kinesis data stream, Step Functions state machine,
or Event Bus in different account or region.
- iam_role_suffix       : IAM role suffix for the event bridge Role having permission to invoke target AWS Service
- iam_policy_statements : A list of dictionaries where each dictionary is an IAM statement defining Event Bridge permissions
-- conditions    : An OPTIONAL list of dictionaries, which each defines:
--- test         : Test condition for limiting the action
--- variable     : Value to test
--- values       : A list of strings, denoting what to test for

Examples

See examples folder for an example setup.