From e73354b93890001bdf39913b46d315a046b48511 Mon Sep 17 00:00:00 2001 From: "ido.ziv" Date: Sat, 28 Oct 2023 11:47:52 -0400 Subject: [PATCH 1/2] Adding a pattern for common usage --- docs/patterns.md | 136 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 135 insertions(+), 1 deletion(-) diff --git a/docs/patterns.md b/docs/patterns.md index 2a20500..681ab5d 100644 --- a/docs/patterns.md +++ b/docs/patterns.md @@ -2,4 +2,138 @@ Various usage patterns are prescribed below. - +## Common Patterns +There are several common patterns to use with the alb for example: +1. Redirect http to https +2. Configuring Instance Target Group +3. Return a fixed response +4. Create several security groups for the load balancer +5. Create a hosted zone record for the load balancer. + +### Redirect http to https +In the example below we can see a listener with that has a rule to redirect the requests. +The nested blocks of `rules` define the different rules the listener will use. Notice this listener also redirects `http` to `https` before returning the response on the rule. +`ex-http-https-redirect` -> `rules` -> `ex-fixed-response` +```hcl +... + ex-http-https-redirect = { + port = 80 + protocol = "HTTP" + redirect = { + port = "443" + protocol = "HTTPS" + status_code = "HTTP_301" + } + + rules = { + ex-fixed-response = { + priority = 3 + actions = [{ + type = "fixed-response" + content_type = "text/plain" + status_code = 200 + message_body = "This is a fixed response" + }] + + conditions = [{ + http_header = { + http_header_name = "x-Gimme-Fixed-Response" + values = ["yes", "please", "right now"] + } + }] + } + + } + } +... +``` +### Configuring Instance Target Group +Each nested map defines a target group on the load balancer. +The map allows the user to create several targets each with a unique name and the order will remain. In this example `instance_1` and `instance_2` are the target groups. + +```hcl +target_groups = { + instance_1 = { + name_prefix = "h1" + backend_protocol = "HTTP" + backend_port = 80 + target_type = "instance" + deregistration_delay = 10 + load_balancing_cross_zone_enabled = false + } + instance_2 = { + name_prefix = "h2" + backend_protocol = "HTTP" + backend_port = 80 + target_type = "instance" + deregistration_delay = 10 + load_balancing_cross_zone_enabled = false + } + +} +``` +### Fixed Response +Each nested map defines a listener on the load balancer. +The nested map below creates a listener with a fixed response of 200. +`ex-fixed-response`->`fixed_response` + +```hcl +... +listeners ={ + ex-fixed-response = { + port = 82 + protocol = "HTTP" + fixed_response = { + content_type = "text/plain" + message_body = "Fixed message" + status_code = "200" + } + } +} +... +``` +### Security Groups +Each nested map defines a securtiy group rule. The rules will be created by the module on the same security group +notice we have in the example several nested maps: +* `security_group_ingress_rules`->`all_http` +* `security_group_ingress_rules`->`all_https` +```hcl +... +security_group_ingress_rules = { + all_http = { + from_port = 80 + to_port = 80 + ip_protocol = "tcp" + description = "HTTP web traffic" + cidr_ipv4 = "0.0.0.0/0" + } + all_https = { + from_port = 443 + to_port = 443 + ip_protocol = "tcp" + description = "HTTPS web traffic" + cidr_ipv4 = "0.0.0.0/0" + } + } +... +``` +### Hosted Zone +Each nested map defines a route53 record. +* `A` -> will be an A record and +* `AAAA` -> will be an AAAA record and +```hcl +... + route53_records = { + A = { + name = local.name + type = "A" + zone_id = data.aws_route53_zone.this.id + } + AAAA = { + name = local.name + type = "AAAA" + zone_id = data.aws_route53_zone.this.id + } + } +... +``` \ No newline at end of file From 2d7506f7432fe86e7cf0d0f71e15b6a1eedc22bc Mon Sep 17 00:00:00 2001 From: Bryant Biggs Date: Sat, 28 Oct 2023 17:51:45 -0400 Subject: [PATCH 2/2] fix: Update snippets and add Lambda target and non-attached target --- README.md | 2 + docs/patterns.md | 262 +++++++++++++++++++++++++++++------------------ 2 files changed, 165 insertions(+), 99 deletions(-) diff --git a/README.md b/README.md index 7e83fa4..a40d6c8 100644 --- a/README.md +++ b/README.md @@ -340,6 +340,8 @@ module "alb" { - [Complete Application Load Balancer](https://github.com/terraform-aws-modules/terraform-aws-alb/tree/master/examples/complete-alb) - [Complete Network Load Balancer](https://github.com/terraform-aws-modules/terraform-aws-alb/tree/master/examples/complete-nlb) +See [patterns.md](https://github.com/terraform-aws-modules/terraform-aws-alb/blob/master/docs/patterns.md) for additional configuration snippets for common usage patterns. + ## Requirements diff --git a/docs/patterns.md b/docs/patterns.md index 681ab5d..36820c7 100644 --- a/docs/patterns.md +++ b/docs/patterns.md @@ -2,20 +2,19 @@ Various usage patterns are prescribed below. -## Common Patterns -There are several common patterns to use with the alb for example: -1. Redirect http to https -2. Configuring Instance Target Group -3. Return a fixed response -4. Create several security groups for the load balancer -5. Create a hosted zone record for the load balancer. - -### Redirect http to https -In the example below we can see a listener with that has a rule to redirect the requests. -The nested blocks of `rules` define the different rules the listener will use. Notice this listener also redirects `http` to `https` before returning the response on the rule. -`ex-http-https-redirect` -> `rules` -> `ex-fixed-response` +## Listeners + +### Redirect HTTP to HTTPS + +The configuration snippet below creates a listener that automatically redirects HTTP/80 requests to HTTPS/443. + ```hcl -... +module "alb" { + source = "terraform-aws-modules/alb/aws" + + # Truncated for brevity ... + + listeners = { ex-http-https-redirect = { port = 80 protocol = "HTTP" @@ -24,116 +23,181 @@ The nested blocks of `rules` define the different rules the listener will use. N protocol = "HTTPS" status_code = "HTTP_301" } + } + } +} +``` + +### Fixed Response - rules = { - ex-fixed-response = { - priority = 3 - actions = [{ - type = "fixed-response" - content_type = "text/plain" - status_code = 200 - message_body = "This is a fixed response" - }] - - conditions = [{ - http_header = { - http_header_name = "x-Gimme-Fixed-Response" - values = ["yes", "please", "right now"] - } - }] - } +The configuration snippet below creates a listener with a fixed response of `200`. +```hcl +module "alb" { + source = "terraform-aws-modules/alb/aws" + + # Truncated for brevity ... + + listeners = { + ex-fixed-response = { + port = 80 + protocol = "HTTP" + fixed_response = { + content_type = "text/plain" + message_body = "Fixed message" + status_code = "200" } } -... + } +} ``` -### Configuring Instance Target Group -Each nested map defines a target group on the load balancer. -The map allows the user to create several targets each with a unique name and the order will remain. In this example `instance_1` and `instance_2` are the target groups. + +## Target Groups + +### Instance Target Group + +The configuration snippet below creates a target group that targets instances. An example listener is shown to demonstrate how a listener or listener rule can forward traffic to this target group using the target group key of `ex-instance` (this name can be any name that users wish to use). ```hcl -target_groups = { - instance_1 = { - name_prefix = "h1" - backend_protocol = "HTTP" - backend_port = 80 - target_type = "instance" - deregistration_delay = 10 - load_balancing_cross_zone_enabled = false +module "alb" { + source = "terraform-aws-modules/alb/aws" + + # Truncated for brevity ... + + listeners = { + ex-https = { + port = 443 + protocol = "HTTPS" + ssl_policy = "ELBSecurityPolicy-TLS13-1-2-Res-2021-06" + certificate_arn = module.acm.acm_certificate_arn + additional_certificate_arns = [module.wildcard_cert.acm_certificate_arn] + + forward = { + # The value of the `target_group_key` is the key used in the `target_groups` map below + target_group_key = "ex-instance" + } } - instance_2 = { - name_prefix = "h2" + } + + target_groups = { + # This key name is used by the listener/listener rules to know which target to forward traffic to + ex-instance = { + name_prefix = "h1" backend_protocol = "HTTP" backend_port = 80 target_type = "instance" deregistration_delay = 10 - load_balancing_cross_zone_enabled = false + load_balancing_cross_zone_enabled = true } - + } } ``` -### Fixed Response -Each nested map defines a listener on the load balancer. -The nested map below creates a listener with a fixed response of 200. -`ex-fixed-response`->`fixed_response` + +### Lambda Target Group + +The configuration snippet below creates two Lambda based target groups. It also demonstrates how users attach permissions to the Lambda function to allow ALB to invoke the function, or they can let ALB attach the necessary permissions to invoke the Lambda function. The listeners specified will split traffic between the two functions, with 60% of traffic going to the Lambda function with invocation permissions, and 40% of traffic going to the Lambda function without invocation permissions. ```hcl -... -listeners ={ - ex-fixed-response = { - port = 82 +module "alb" { + source = "terraform-aws-modules/alb/aws" + + # Truncated for brevity ... + + listeners = { + ex-http-weighted-target = { + port = 80 protocol = "HTTP" - fixed_response = { - content_type = "text/plain" - message_body = "Fixed message" - status_code = "200" + weighted_forward = { + target_groups = [ + { + target_group_key = "ex-lambda-with-trigger" + weight = 60 + }, + { + target_group_key = "ex-lambda-without-trigger" + weight = 40 + } + ] } } -} -... -``` -### Security Groups -Each nested map defines a securtiy group rule. The rules will be created by the module on the same security group -notice we have in the example several nested maps: -* `security_group_ingress_rules`->`all_http` -* `security_group_ingress_rules`->`all_https` -```hcl -... -security_group_ingress_rules = { - all_http = { - from_port = 80 - to_port = 80 - ip_protocol = "tcp" - description = "HTTP web traffic" - cidr_ipv4 = "0.0.0.0/0" + } + + target_groups = { + ex-lambda-with-trigger = { + name_prefix = "l1-" + target_type = "lambda" + lambda_multi_value_headers_enabled = true + target_id = module.lambda_with_allowed_triggers.lambda_function_arn } - all_https = { - from_port = 443 - to_port = 443 - ip_protocol = "tcp" - description = "HTTPS web traffic" - cidr_ipv4 = "0.0.0.0/0" + + ex-lambda-without-trigger = { + name_prefix = "l2-" + target_type = "lambda" + target_id = module.lambda_without_allowed_triggers.lambda_function_arn + attach_lambda_permission = true + } + } +} + +module "lambda_with_allowed_triggers" { + source = "terraform-aws-modules/lambda/aws" + version = "~> 6.0" + + # Truncated for brevity ... + + allowed_triggers = { + AllowExecutionFromELB = { + service = "elasticloadbalancing" + source_arn = module.alb.target_groups["ex-lambda-with-trigger"].arn } } -... +} + +module "lambda_without_allowed_triggers" { + source = "terraform-aws-modules/lambda/aws" + version = "~> 6.0" + + # Truncated for brevity ... + + # Allowed triggers will be managed by ALB module + allowed_triggers = {} +} ``` -### Hosted Zone -Each nested map defines a route53 record. -* `A` -> will be an A record and -* `AAAA` -> will be an AAAA record and + +### Target Group without Attachment + +The configuration snippet below creates a target group but it does not attach it to anything at this time. This is commonly used with Amazon ECS where ECS will attach the IPs of the ECS Tasks to the target group. + ```hcl -... - route53_records = { - A = { - name = local.name - type = "A" - zone_id = data.aws_route53_zone.this.id - } - AAAA = { - name = local.name - type = "AAAA" - zone_id = data.aws_route53_zone.this.id +module "alb" { + source = "terraform-aws-modules/alb/aws" + + # Truncated for brevity ... + + target_groups = { + ex-ip = { + backend_protocol = "HTTP" + backend_port = 80 + target_type = "ip" + deregistration_delay = 5 + load_balancing_cross_zone_enabled = true + + health_check = { + enabled = true + healthy_threshold = 5 + interval = 30 + matcher = "200" + path = "/" + port = "traffic-port" + protocol = "HTTP" + timeout = 5 + unhealthy_threshold = 2 + } + + # Theres nothing to attach here in this definition. Instead, + # ECS will attach the IPs of the tasks to this target group + create_attachment = false } } -... -``` \ No newline at end of file +} +```