AWS Load Balancer Controller and Terraform ALB Module for aws_lb

The AWS ecosystem for Kubernetes load balancing spans two closely related surfaces: the AWS Load Balancer Controller that reconciles Kubernetes Service, Ingress and Gateway resources into Elastic Load Balancers, and the Terraform AWS ALB module that provisions Application and Network Load Balancer resources with declarative configuration. Both converge on the awslb resource and its supporting listener, target group and security group constructs, and both expose configuration through annotations and module variables that must be understood together to operate awslb safely in production.

The AWS Load Balancer Controller is a controller to help manage Elastic Load Balancers for a Kubernetes cluster. It satisfies Kubernetes Ingress resources by provisioning Application Load Balancers. It satisfies Kubernetes Service resources by provisioning Network Load Balancers. It satisfies Kubernetes Gateway resources by provisioning Network Load Balancers and Application Load Balancers. This project was formerly known as "AWS ALB Ingress Controller", we rebranded it to be "AWS Load Balancer Controller".

The Terraform module which creates Application and Network Load Balancer resources on AWS provides a Terraform wrapper around the aws_lb resource and related AWS resources. When you're using ALB Listener rules, make sure that every rule's actions block ends in a forward, redirect, or fixed-response action so that every rule will resolve to some sort of an HTTP response.

AWS Load Balancer Controller Overview

AWS Load Balancer Controller is a controller to help manage Elastic Load Balancers for a Kubernetes cluster.

The controller's primary reconciliation targets are:

• Kubernetes Ingress resources by provisioning Application Load Balancers
• Kubernetes Service resources by provisioning Network Load Balancers
• Kubernetes Gateway resources by provisioning Network Load Balancers and Application Load Balancers

This project was formerly known as "AWS ALB Ingress Controller", we rebranded it to be "AWS Load Balancer Controller".

Origin and governance

AWS ALB Ingress Controller was originated by Ticketmaster and CoreOS as part of Ticketmaster's move to AWS and CoreOS Tectonic. Learn more about Ticketmaster's Kubernetes initiative from Justin Dean's video at Tectonic Summit.

AWS ALB Ingress Controller was donated to Kubernetes SIG-AWS to allow AWS, CoreOS, Ticketmaster and other SIG-AWS contributors to officially maintain the project. SIG-AWS reached this consensus on June 1, 2018.

The controller is open for contributions. We welcome contributions! For non-trivial changes (new features, API changes, refactors), please open an issue or discussion before submitting a PR so the maintainers can provide early feedback. See CONTRIBUTING.md for full details.

Terraform AWS ALB Module Overview

The module referenced in the reference material is terraform-aws-modules/alb/aws. Terraform module which creates Application and Network Load Balancer resources on AWS.

Version constraints captured in the reference material:

The module creates the following resources as documented:

Module Configuration Example

A representative module invocation is shown in the reference facts:

hcl module "alb" { source = "terraform-aws-modules/alb/aws" name = "my-alb" vpc_id = "vpc-abcde012" subnets = ["subnet-abcde012", "subnet-bcde012a"] 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" } } security_group_egress_rules = { all = { ip_protocol = "-1" cidr_ipv4 = "10.0.0.0/16" } } access_logs = { bucket = "my-alb-logs" } listeners = { ex-http-https-redirect = { port = 80 protocol = "HTTP" redirect = { port = "443" protocol = "HTTPS" status_code = "HTTP_301" } } ex-https = { port = 443 protocol = "HTTPS" certificate_arn = "arn:aws:iam::123456789012:server-certificate/test_cert-123456789012" forward = { target_group_key = "ex-instance" } } } target_groups = { ex-instance = { name_prefix = "h1" protocol = "HTTP" port = 80 target_type = "instance" target_id = "i-0f6d38a07d50d080f" } } tags = { Environment = "Development" Project = "Example" } }

A second partial example shows the same listener pattern with an ex-cognito listener on port 444 with protocol HTTPS and certificate_arn.

The module documentation notes: When you're using ALB Listener rules, make sure that every rule's actions block ends in a forward, redirect, or fixed-response action so that every rule will resolve to some sort of an HTTP response.

Module Input Variables

The reference facts list the following input variables with partial descriptions.

The module also documents:

• Only valid for Load Balancers of type application. Default: 60
• • preserve client IP is disabled by default for IP targets - preserve client IP is enabled by default for instance targets

Kubernetes Service Annotations for AWS Load Balancer Controller

• boolean: "true"
• integer: "42"
• stringList: "s1,s2,s3"
• stringMap: "k1=v1,k2=v2"
• json: "{ \"key\": \"value\" }"
• boolean:

• service.beta.kubernetes.io/load-balancer-source-ranges: 10.0.0.0/24
• service.beta.kubernetes.io/aws-load-balancer-scheme specifies whether the NLB will be internet-facing or internal. Valid values are internal, internet-facing. If not specified, default is internal.
  
  Example service.beta.kubernetes.io/aws-load-balancer-scheme: "internet-facing"
• service.beta.kubernetes.io/aws-load-balancer-internal specifies whether the NLB will be internet-facing or internal. deprecation note This annotation is deprecated starting v2.2.0 release in favor of the new aws-load-balancer-scheme annotation. It will will be supported, but in case of ties, the aws-load-balancer-scheme gets precedence.
  
  Example service.beta.kubernetes.io/aws-load-balancer-internal: "true"

Annotation Encoding and Legacy Compatibility

Integration Patterns Between Terraform Module and Controller

• Use the Terraform module for statically provisioned, infrastructure owned Application Load Balancers and Network Load Balancers with explicit listeners, target groups, security groups, access logs and WAF association.
• Use the AWS Load Balancer Controller for dynamically provisioned load balancers driven by Kubernetes workloads, with configuration expressed through service annotations and Ingress/Gateway manifests.

Operational Notes

• The Terraform module supports loadbalancertype values application, gateway, or network with default application.
• Security group ingress rules can be defined per port and protocol as shown in the example with allhttp and allhttps.
• Security group egress rules can be defined with ipprotocol "-1" and cidripv4 range.
• Access logging is configured via accesslogs bucket.
• Listener redirect actions must terminate in forward, redirect, or fixed-response to resolve to an HTTP response.
• Target group configuration includes nameprefix, protocol, port, targettype and targetid as demonstrated.

Conclusion

Sources

1. kubernetes-sigs/aws-load-balancer-controller
2. terraform-aws-modules/terraform-aws-alb
3. kubernetes-sigs/aws-load-balancer-controller annotations guide