2022-01-13 23:19:02 -08:00
# External Global (HTTP/S) Load Balancer Module
The module allows managing External Global HTTP/HTTPS Load Balancers (XGLB), integrating the global forwarding rule, the url-map, the backends (supporting buckets and groups), and optional health checks and SSL certificates (both managed and unmanaged). It's designed to be a simple match for the [`gcs` ](../gcs ) and the [`compute-vm` ](../compute-vm ) modules, which can be used to manage GCS buckets, instance templates and instance groups.
## Examples
### GCS Bucket Minimal Example
This is a minimal example, which creates a global HTTP load balancer, pointing the path `/` to an existing GCS bucket called `my_test_bucket` .
```hcl
2022-01-14 07:52:03 -08:00
module "glb" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/net-glb"
2022-01-14 07:52:03 -08:00
name = "glb-test"
2022-01-13 23:19:02 -08:00
project_id = var.project_id
backend_services_config = {
my-bucket-backend = {
bucket_config = {
bucket_name = "my_test_bucket"
options = null
}
group_config = null
enable_cdn = false
cdn_config = null
}
}
}
2022-01-28 11:15:35 -08:00
# tftest modules=1 resources=4
2022-01-13 23:19:02 -08:00
```
### Group Backend Service Minimal Example
A very similar coniguration also applies to GCE instance groups:
```hcl
2022-01-14 07:52:03 -08:00
module "glb" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/net-glb"
2022-01-14 07:52:03 -08:00
name = "glb-test"
2022-01-13 23:19:02 -08:00
project_id = var.project_id
backend_services_config = {
my-group-backend = {
bucket_config = null
enable_cdn = false
cdn_config = null
group_config = {
backends = [
{
group = "my_test_group"
options = null
}
],
health_checks = []
log_config = null
options = null
}
}
}
}
2022-01-28 11:15:35 -08:00
# tftest modules=1 resources=5
2022-01-13 23:19:02 -08:00
```
### Health Checks For Group Backend Services
Group backend services support health checks.
If no health checks are specified, a default HTTP health check is created and associated to each group backend service. The default health check configuration can be modified through the `health_checks_config_defaults` variable.
Alternatively, one or more health checks can be either contextually created or attached, if existing. If the id of the health checks specified is equal to one of the keys of the `health_checks_config` variable, the health check is contextually created; otherwise, the health check id is used as is, assuming an health check alredy exists.
For example, to contextually create a health check and attach it to the backend service:
```hcl
2022-01-14 07:52:03 -08:00
module "glb" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/net-glb"
2022-01-14 07:52:03 -08:00
name = "glb-test"
2022-01-13 23:19:02 -08:00
project_id = var.project_id
backend_services_config = {
my-group-backend = {
bucket_config = null
enable_cdn = false
cdn_config = null
group_config = {
backends = [
{
group = "my_test_group"
options = null
}
],
health_checks = ["hc_1"]
log_config = null
options = null
}
}
}
health_checks_config = {
hc_1 = {
type = "http"
logging = true
options = {
timeout_sec = 40
}
check = {
port_specification = "USE_SERVING_PORT"
}
}
}
}
2022-01-28 11:15:35 -08:00
# tftest modules=1 resources=5
2022-01-13 23:19:02 -08:00
```
2022-01-25 05:42:48 -08:00
### Serverless Backends
Serverless backends can also be used, as shown in the example below.
```hcl
module "glb" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/net-glb"
2022-01-25 05:42:48 -08:00
name = "glb-test"
project_id = var.project_id
# This is important as serverless backends require no HCs
health_checks_config_defaults = null
backend_services_config = {
my-serverless-backend = {
bucket_config = null
enable_cdn = false
cdn_config = null
group_config = {
backends = [
{
group = google_compute_region_network_endpoint_group.serverless-neg.id
options = null
}
],
health_checks = []
log_config = null
options = null
}
}
}
}
resource "google_compute_region_network_endpoint_group" "serverless-neg" {
name = "my-serverless-neg"
project = var.project_id
region = "europe-west1"
network_endpoint_type = "SERVERLESS"
cloud_run {
service = "my-cloud-run-service"
}
}
2022-09-12 04:53:54 -07:00
# tftest modules=1 resources=5
2022-01-25 05:42:48 -08:00
```
2022-01-13 23:19:02 -08:00
### Mixing Backends
Backends can be multiple, group and bucket backends can be mixed and group backends support multiple groups.
```hcl
2022-01-14 07:52:03 -08:00
module "glb" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/net-glb"
2022-01-14 07:52:03 -08:00
name = "glb-test"
2022-01-13 23:19:02 -08:00
project_id = var.project_id
backend_services_config = {
my-group-backend = {
bucket_config = null
enable_cdn = false
cdn_config = null
group_config = {
backends = [
{
group = "my_test_group"
options = null
}
],
health_checks = []
log_config = null
options = null
}
},
another-group-backend = {
bucket_config = null
enable_cdn = false
cdn_config = null
group_config = {
backends = [
{
group = "my_other_test_group"
options = null
}
],
health_checks = []
log_config = null
options = null
}
},
a-bucket-backend = {
bucket_config = {
bucket_name = "my_test_bucket"
options = null
}
group_config = null
enable_cdn = false
cdn_config = null
}
}
}
2022-01-28 11:15:35 -08:00
# tftest modules=1 resources=7
2022-01-13 23:19:02 -08:00
```
### Url-map
The url-map can be customized with lots of different configurations. This includes leveraging multiple backends in different parts of the configuration.
Given its complexity, it's left to the user passing the right data structure.
For simplicity, *if no configurations are given* the first backend service defined (in alphabetical order, with priority to bucket backend services, if any) is used as the *default_service* , thus answering to the root (*/*) path.
Backend services can be specified as needed in the url-map configuration, referencing the id used to declare them in the backend services map. If a corresponding backend service is found, their object id is automatically used; otherwise, it is assumed that the string passed is the id of an already existing backend and it is given to the provider as it was passed.
In this example, we're using one backend service as the default backend
```hcl
2022-01-14 07:52:03 -08:00
module "glb" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/net-glb"
2022-01-14 07:52:03 -08:00
name = "glb-test"
2022-01-13 23:19:02 -08:00
project_id = var.project_id
url_map_config = {
default_service = "my-group-backend"
default_route_action = null
default_url_redirect = null
tests = null
header_action = null
host_rules = []
path_matchers = [
{
name = "my-example-page"
path_rules = [
{
paths = ["/my-example-page"]
service = "another-group-backend"
}
]
}
]
}
backend_services_config = {
my-group-backend = {
bucket_config = null
enable_cdn = false
cdn_config = null
group_config = {
backends = [
{
group = "my_test_group"
options = null
}
],
health_checks = []
log_config = null
options = null
}
},
my-example-page = {
bucket_config = null
enable_cdn = false
cdn_config = null
group_config = {
backends = [
{
group = "my_other_test_group"
options = null
}
],
health_checks = []
log_config = null
options = null
}
}
}
}
2022-01-28 11:15:35 -08:00
# tftest modules=1 resources=6
2022-01-13 23:19:02 -08:00
```
### Reserve a static IP address
Optionally, a static IP address can be reserved:
```hcl
2022-01-14 07:52:03 -08:00
module "glb" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/net-glb"
2022-01-14 07:52:03 -08:00
name = "glb-test"
2022-01-13 23:19:02 -08:00
project_id = var.project_id
reserve_ip_address = true
backend_services_config = {
my-group-backend = {
bucket_config = null
enable_cdn = false
cdn_config = null
group_config = {
backends = [
{
group = "my_test_group"
options = null
}
],
health_checks = []
log_config = null
options = null
}
}
}
}
2022-01-28 11:15:35 -08:00
# tftest modules=1 resources=6
2022-01-13 23:19:02 -08:00
```
### HTTPS And SSL Certificates
HTTPS is disabled by default but it can be optionally enabled.
The module supports both managed and unmanaged certificates, and they can be either created contextually with other resources or attached, if already existing.
If no `ssl_certificates_config` variable is specified, a managed certificate for the domain *example.com* is automatically created.
```hcl
2022-01-14 07:52:03 -08:00
module "glb" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/net-glb"
2022-01-14 07:52:03 -08:00
name = "glb-test"
2022-01-13 23:19:02 -08:00
project_id = var.project_id
https = true
backend_services_config = {
my-group-backend = {
bucket_config = null
enable_cdn = false
cdn_config = null
group_config = {
backends = [
{
group = "my_test_group"
options = null
}
],
health_checks = []
log_config = null
options = null
}
}
}
}
2022-01-28 11:15:35 -08:00
# tftest modules=1 resources=6
2022-01-13 23:19:02 -08:00
```
Otherwise, SSL certificates can be explicitely defined. In this case, they'll need to be referenced from the `target_proxy_https_config.ssl_certificates` variable.
If the ids specified in the `target_proxy_https_config` variable are not found in the `ssl_certificates_config` map, they are used as is, assuming the ssl certificates already exist.
```hcl
2022-01-14 07:52:03 -08:00
module "glb" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/net-glb"
2022-01-14 07:52:03 -08:00
name = "glb-test"
2022-01-13 23:19:02 -08:00
project_id = var.project_id
https = true
ssl_certificates_config = {
my-domain = {
domains = [
"my-domain.com"
],
unmanaged_config = null
}
}
target_proxy_https_config = {
ssl_certificates = [
"my-domain",
"an-existing-cert"
]
}
backend_services_config = {
my-group-backend = {
bucket_config = null
enable_cdn = false
cdn_config = null
group_config = {
backends = [
{
group = "my_test_group"
options = null
}
]
health_checks = []
log_config = null
options = null
}
}
}
}
2022-01-28 11:15:35 -08:00
# tftest modules=1 resources=6
2022-01-13 23:19:02 -08:00
```
Using unamanged certificates is also possible. Here is an example:
```hcl
2022-01-14 07:52:03 -08:00
module "glb" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/net-glb"
2022-01-14 07:52:03 -08:00
name = "glb-test"
2022-01-13 23:19:02 -08:00
project_id = var.project_id
https = true
ssl_certificates_config = {
my-domain = {
domains = [
"my-domain.com"
],
unmanaged_config = {
tls_private_key = nonsensitive(tls_private_key.self_signed_key.private_key_pem)
tls_self_signed_cert = nonsensitive(tls_self_signed_cert.self_signed_cert.cert_pem)
}
}
}
target_proxy_https_config = {
ssl_certificates = [
"my-domain"
]
}
backend_services_config = {
my-group-backend = {
bucket_config = null
enable_cdn = false
cdn_config = null
group_config = {
backends = [
{
group = "my_test_group"
options = null
}
],
health_checks = []
log_config = null
options = null
}
}
}
}
resource "tls_private_key" "self_signed_key" {
algorithm = "RSA"
rsa_bits = 2048
}
resource "tls_self_signed_cert" "self_signed_cert" {
private_key_pem = tls_private_key.self_signed_key.private_key_pem
validity_period_hours = 12
early_renewal_hours = 3
dns_names = ["example.com"]
allowed_uses = [
"key_encipherment",
"digital_signature",
"server_auth"
]
subject {
common_name = "example.com"
organization = "My Test Org"
}
}
2022-09-12 04:53:54 -07:00
# tftest modules=1 resources=8
2022-01-13 23:19:02 -08:00
```
2022-08-27 13:58:11 -07:00
## Regional Load Balancing
You can also use regional load balancing by specifying a `region` parameter:
```hcl
module "glb" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/net-glb"
2022-08-27 13:58:11 -07:00
name = "glb-test"
project_id = var.project_id
region = var.region
backend_services_config = {
my-group-backend = {
bucket_config = null
enable_cdn = false
cdn_config = null
group_config = {
backends = [
{
group = "my_test_group"
options = null
}
],
health_checks = []
log_config = null
options = null
}
}
}
}
# tftest modules=1 resources=5
```
2022-01-13 23:19:02 -08:00
## Components And Files Mapping
An External Global Load Balancer is made of multiple components, that change depending on the configurations. Sometimes, it may be tricky to understand what they are, and how they relate to each other. Following, we provide a very brief overview to become more familiar with them.
2022-03-28 00:43:00 -07:00
- The global load balancer [forwarding rule ](global-forwarding-rule.tf ) binds a frontend public Virtual IP (VIP) to an HTTP(S) [target proxy ](target-proxy.tf ).
- If the target proxy is HTTPS, it requires one or more managed or unmanaged [SSL certificates ](ssl-certificates.tf ).
Target proxies leverage [url-maps ](url-map.tf ): set of L7 rules, which create a mapping between specific hostnames, URIs (and more) to one or more [backends services ](backend-services.tf ).
- [Backend services ](backend-services.tf ) can either link to a bucket or one or multiple groups, which can be GCE instance groups or NEGs. It is assumed in this module that buckets and groups are previously created through other modules, and passed in as input variables.
- Backend services support one or more [health checks ](health-checks.tf ), used to verify that the backend is indeed healthy, so that traffic can be forwarded to it. Health checks currently supported in this module are HTTP, HTTPS, HTTP2, SSL, TCP.
2022-01-29 01:41:30 -08:00
<!-- TFDOC OPTS files:1 -->
<!-- BEGIN TFDOC -->
## Files
| name | description | resources |
|---|---|---|
2022-02-03 23:27:39 -08:00
| [backend-services.tf ](./backend-services.tf ) | Bucket and group backend services. | < code > google_compute_backend_bucket</ code > · < code > google_compute_backend_service</ code > |
| [global-forwarding-rule.tf ](./global-forwarding-rule.tf ) | Global address and forwarding rule. | < code > google_compute_global_address</ code > · < code > google_compute_global_forwarding_rule</ code > |
2022-08-27 13:58:11 -07:00
| [health-checks.tf ](./health-checks.tf ) | Health checks. | < code > google_compute_health_check</ code > · < code > google_compute_region_health_check</ code > |
2022-01-29 01:41:30 -08:00
| [outputs.tf ](./outputs.tf ) | Module outputs. | |
2022-08-27 13:58:11 -07:00
| [regional-backend-services.tf ](./regional-backend-services.tf ) | Bucket and group backend services for regional load balancers. | < code > google_compute_region_backend_service</ code > |
| [regional-forwarding-rule.tf ](./regional-forwarding-rule.tf ) | Global address and forwarding rule. | < code > google_compute_address</ code > · < code > google_compute_forwarding_rule</ code > |
| [regional-url-map.tf ](./regional-url-map.tf ) | regional URL maps. | < code > google_compute_region_url_map</ code > |
2022-02-03 23:27:39 -08:00
| [ssl-certificates.tf ](./ssl-certificates.tf ) | SSL certificates. | < code > google_compute_managed_ssl_certificate</ code > · < code > google_compute_ssl_certificate</ code > |
2022-08-27 13:58:11 -07:00
| [target-proxy.tf ](./target-proxy.tf ) | HTTP and HTTPS target proxies. | < code > google_compute_region_target_http_proxy</ code > · < code > google_compute_region_target_https_proxy</ code > · < code > google_compute_target_http_proxy</ code > · < code > google_compute_target_https_proxy</ code > |
2022-02-03 23:27:39 -08:00
| [url-map.tf ](./url-map.tf ) | URL maps. | < code > google_compute_url_map</ code > |
2022-01-29 01:41:30 -08:00
| [variables.tf ](./variables.tf ) | Module variables. | |
| [versions.tf ](./versions.tf ) | Version pins. | |
## Variables
| name | description | type | required | default |
|---|---|:---:|:---:|:---:|
2022-11-18 08:48:16 -08:00
| [name ](variables.tf#L186 ) | Load balancer name. | < code > string</ code > | ✓ | |
| [project_id ](variables.tf#L191 ) | Project id. | < code > string</ code > | ✓ | |
| [backend_services_config ](variables.tf#L17 ) | The backends services configuration. | < code title = "map(object({ enable_cdn = bool cdn_config = object({ cache_mode = string client_ttl = number default_ttl = number max_ttl = number negative_caching = bool negative_caching_policy = map(number) serve_while_stale = bool signed_url_cache_max_age_sec = string }) bucket_config = object({ bucket_name = string options = object({ custom_response_headers = list(string) }) }) group_config = object({ backends = list(object({ group = string # IG or NEG FQDN address options = object({ balancing_mode = string # Can be UTILIZATION, RATE, CONNECTION capacity_scaler = number # Valid range is [0.0,1.0] max_connections = number max_connections_per_instance = number max_connections_per_endpoint = number max_rate = number max_rate_per_instance = number max_rate_per_endpoint = number max_utilization = number }) })) health_checks = list(string) log_config = object({ enable = bool sample_rate = number # must be in [0, 1] }) options = object({ affinity_cookie_ttl_sec = number custom_request_headers = list(string) custom_response_headers = list(string) connection_draining_timeout_sec = number load_balancing_scheme = string # only EXTERNAL (default) makes sense here locality_lb_policy = string port_name = string protocol = string security_policy = string session_affinity = string timeout_sec = number circuits_breakers = object({ max_requests_per_connection = number # Set to 1 to disable keep-alive max_connections = number # Defaults to 1024 max_pending_requests = number # Defaults to 1024 max_requests = number # Defaults to 1024 max_retries = number # Defaults to 3 }) consistent_hash = object({ http_header_name = string minimum_ring_size = string http_cookie = object({ name = string path = string ttl = object({ seconds = number nanos = number }) }) }) iap = object({ oauth2_client_id = string oauth2_client_secret = string oauth2_client_secret_sha256 = string }) }) }) }))" > map( object({…})) </ code > | | < code > {} </ code > |
| [forwarding_rule_config ](variables.tf#L112 ) | Regional forwarding rule configurations. | < code title = "object({ ip_protocol = string ip_version = string load_balancing_scheme = string port_range = string network_tier = string network = string })" > object({…}) </ code > | | < code title = "{ load_balancing_scheme = "EXTERNAL_MANAGED" ip_protocol = "TCP" ip_version = "IPV4" network_tier = "STANDARD" network = "default" port_range = null }" > {…} </ code > |
| [global_forwarding_rule_config ](variables.tf#L133 ) | Global forwarding rule configurations. | < code title = "object({ ip_protocol = string ip_version = string load_balancing_scheme = string port_range = string })" > object({…}) </ code > | | < code title = "{ load_balancing_scheme = "EXTERNAL" ip_protocol = "TCP" ip_version = "IPV4" port_range = null }" > {…} </ code > |
| [health_checks_config ](variables.tf#L151 ) | Custom health checks configuration. | < code title = "map(object({ type = string # http https tcp ssl http2 check = map(any) # actual health check block attributes options = map(number) # interval, thresholds, timeout logging = bool }))" > map( object({…})) </ code > | | < code > {} </ code > |
| [health_checks_config_defaults ](variables.tf#L162 ) | Auto-created health check default configuration. | < code title = "object({ type = string # http https tcp ssl http2 check = map(any) # actual health check block attributes options = map(number) # interval, thresholds, timeout logging = bool })" > object({…}) </ code > | | < code title = "{ type = "http" logging = false options = {} check = { port_specification = "USE_SERVING_PORT" } }" > {…} </ code > |
| [https ](variables.tf#L180 ) | Whether to enable HTTPS. | < code > bool</ code > | | < code > false</ code > |
| [region ](variables.tf#L196 ) | Create a regional load balancer in this region. | < code > string</ code > | | < code > null</ code > |
| [reserve_ip_address ](variables.tf#L202 ) | Whether to reserve a static global IP address. | < code > bool</ code > | | < code > false</ code > |
| [ssl_certificates_config ](variables.tf#L208 ) | The SSL certificate configuration. | < code title = "map(object({ domains = list(string) unmanaged_config = object({ tls_private_key = string tls_self_signed_cert = string }) }))" > map( object({…})) </ code > | | < code > {} </ code > |
| [ssl_certificates_config_defaults ](variables.tf#L221 ) | The SSL certificate default configuration. | < code title = "object({ domains = list(string) unmanaged_config = object({ tls_private_key = string tls_self_signed_cert = string }) })" > object({…}) </ code > | | < code title = "{ domains = ["example.com"], unmanaged_config = null }" > {…} </ code > |
| [target_proxy_https_config ](variables.tf#L237 ) | The HTTPS target proxy configuration. | < code title = "object({ ssl_certificates = list(string) })" > object({…}) </ code > | | < code > null</ code > |
| [url_map_config ](variables.tf#L245 ) | The url-map configuration. | < code title = "object({ default_service = string default_route_action = any default_url_redirect = map(any) header_action = any host_rules = list(any) path_matchers = list(any) tests = list(map(string)) })" > object({…}) </ code > | | < code > null</ code > |
2022-01-29 01:41:30 -08:00
## Outputs
| name | description | sensitive |
|---|---|:---:|
2022-11-18 08:48:16 -08:00
| [backend_services ](outputs.tf#L17 ) | Backend service resources. | |
| [forwarding_rule ](outputs.tf#L25 ) | The regional forwarding rule. | |
| [global_forwarding_rule ](outputs.tf#L30 ) | The global forwarding rule. | |
| [health_checks ](outputs.tf#L35 ) | Health-check resources. | |
| [ip_address ](outputs.tf#L40 ) | The reserved global IP address. | |
| [ip_address_self_link ](outputs.tf#L45 ) | The URI of the reserved global IP address. | |
| [ssl_certificates ](outputs.tf#L50 ) | The SSL certificate. | |
| [target_proxy ](outputs.tf#L59 ) | The target proxy. | |
| [url_map ](outputs.tf#L67 ) | The url-map. | |
2022-01-29 01:41:30 -08:00
<!-- END TFDOC -->
