397 lines
19 KiB
Markdown
397 lines
19 KiB
Markdown
# Internal Passthrough Network Load Balancer Module
|
|
|
|
This module allows managing a GCE Internal Load Balancer and integrates the forwarding rule, regional backend, and optional health check resources. It's designed to be a simple match for the [`compute-vm`](../compute-vm) module, which can be used to manage instance templates and instance groups.
|
|
|
|
<!-- BEGIN TOC -->
|
|
- [Examples](#examples)
|
|
- [Referencing existing MIGs](#referencing-existing-migs)
|
|
- [Externally managed instances](#externally-managed-instances)
|
|
- [Passing multiple protocols through the load balancers](#passing-multiple-protocols-through-the-load-balancers)
|
|
- [Mutiple forwarding rules](#mutiple-forwarding-rules)
|
|
- [Dual stack (IPv4 and IPv6)](#dual-stack-ipv4-and-ipv6)
|
|
- [PSC service attachments](#psc-service-attachments)
|
|
- [End to end example](#end-to-end-example)
|
|
- [Issues](#issues)
|
|
- [Variables](#variables)
|
|
- [Outputs](#outputs)
|
|
<!-- END TOC -->
|
|
|
|
## Examples
|
|
|
|
### Referencing existing MIGs
|
|
|
|
This example shows how to reference existing Managed Infrastructure Groups (MIGs).
|
|
|
|
```hcl
|
|
module "instance_template" {
|
|
source = "./fabric/modules/compute-vm"
|
|
project_id = var.project_id
|
|
zone = "europe-west1-b"
|
|
name = "vm-test"
|
|
create_template = true
|
|
service_account = {
|
|
auto_create = true
|
|
}
|
|
network_interfaces = [
|
|
{
|
|
network = var.vpc.self_link
|
|
subnetwork = var.subnet.self_link
|
|
}
|
|
]
|
|
tags = [
|
|
"http-server"
|
|
]
|
|
}
|
|
|
|
module "mig" {
|
|
source = "./fabric/modules/compute-mig"
|
|
project_id = var.project_id
|
|
location = "europe-west1"
|
|
name = "mig-test"
|
|
target_size = 1
|
|
instance_template = module.instance_template.template.self_link
|
|
}
|
|
|
|
module "ilb" {
|
|
source = "./fabric/modules/net-lb-int"
|
|
project_id = var.project_id
|
|
region = "europe-west1"
|
|
name = "ilb-test"
|
|
service_label = "ilb-test"
|
|
vpc_config = {
|
|
network = var.vpc.self_link
|
|
subnetwork = var.subnet.self_link
|
|
}
|
|
backends = [{
|
|
group = module.mig.group_manager.instance_group
|
|
}]
|
|
health_check_config = {
|
|
http = {
|
|
port = 80
|
|
}
|
|
}
|
|
}
|
|
# tftest modules=3 resources=6
|
|
```
|
|
|
|
### Externally managed instances
|
|
|
|
This examples shows how to create an ILB by combining externally managed instances (in a custom module or even outside of the current root module) in an unmanaged group. When using internally managed groups, remember to run `terraform apply` each time group instances change.
|
|
|
|
```hcl
|
|
module "ilb" {
|
|
source = "./fabric/modules/net-lb-int"
|
|
project_id = var.project_id
|
|
region = "europe-west1"
|
|
name = "ilb-test"
|
|
service_label = "ilb-test"
|
|
vpc_config = {
|
|
network = var.vpc.self_link
|
|
subnetwork = var.subnet.self_link
|
|
}
|
|
group_configs = {
|
|
my-group = {
|
|
zone = "europe-west1-b"
|
|
instances = [
|
|
"instance-1-self-link",
|
|
"instance-2-self-link"
|
|
]
|
|
}
|
|
}
|
|
backends = [{
|
|
group = module.ilb.groups.my-group.self_link
|
|
}]
|
|
health_check_config = {
|
|
http = {
|
|
port = 80
|
|
}
|
|
}
|
|
}
|
|
# tftest modules=1 resources=4
|
|
```
|
|
|
|
### Passing multiple protocols through the load balancers
|
|
|
|
The example shows how to send multiple protocols through the same internal network passthrough load balancer.
|
|
|
|
```hcl
|
|
module "ilb" {
|
|
source = "./fabric/modules/net-lb-int"
|
|
project_id = var.project_id
|
|
region = "europe-west1"
|
|
name = "ilb-test"
|
|
service_label = "ilb-test"
|
|
vpc_config = {
|
|
network = var.vpc.self_link
|
|
subnetwork = var.subnet.self_link
|
|
}
|
|
forwarding_rules_config = {
|
|
"" = {
|
|
protocol = "L3_DEFAULT"
|
|
}
|
|
}
|
|
group_configs = {
|
|
my-group = {
|
|
zone = "europe-west1-b"
|
|
instances = [
|
|
"instance-1-self-link",
|
|
"instance-2-self-link"
|
|
]
|
|
}
|
|
}
|
|
backends = [{
|
|
group = module.ilb.groups.my-group.self_link
|
|
}]
|
|
}
|
|
# tftest modules=1 resources=4
|
|
```
|
|
|
|
### Mutiple forwarding rules
|
|
|
|
You can add more forwarding rules to your load balancer and override some forwarding rules defaults, including the global access policy, the IP protocol, the IP version and ports.
|
|
|
|
The example adds two forwarding rules:
|
|
|
|
- the first one, called `ilb-test-vip-one` exposes an IPv4 address, it listens on all ports, and allows connections from any region.
|
|
- the second one, called `ilb-test-vip-two` exposes an IPv4 address, it listens on port 80 and allows connections from the same region only.
|
|
|
|
```hcl
|
|
module "ilb" {
|
|
source = "./fabric/modules/net-lb-int"
|
|
project_id = var.project_id
|
|
region = "europe-west1"
|
|
name = "ilb-test"
|
|
service_label = "ilb-test"
|
|
vpc_config = {
|
|
network = var.vpc.self_link
|
|
subnetwork = var.subnet.self_link
|
|
}
|
|
forwarding_rules_config = {
|
|
vip-one = {}
|
|
vip-two = {
|
|
global_access = false
|
|
ports = [80]
|
|
}
|
|
}
|
|
group_configs = {
|
|
my-group = {
|
|
zone = "europe-west1-b"
|
|
instances = [
|
|
"instance-1-self-link",
|
|
"instance-2-self-link"
|
|
]
|
|
}
|
|
}
|
|
backends = [{
|
|
group = module.ilb.groups.my-group.self_link
|
|
}]
|
|
}
|
|
# tftest modules=1 resources=5
|
|
```
|
|
|
|
### Dual stack (IPv4 and IPv6)
|
|
|
|
Your load balancer can use a combination of either or both IPv4 and IPv6 forwarding rules.
|
|
In this example we set the load balancer to work as dual stack, meaning it exposes both an IPv4 and an IPv6 address.
|
|
|
|
```hcl
|
|
module "ilb" {
|
|
source = "./fabric/modules/net-lb-int"
|
|
project_id = var.project_id
|
|
region = "europe-west1"
|
|
name = "ilb-test"
|
|
service_label = "ilb-test"
|
|
vpc_config = {
|
|
network = var.vpc.self_link
|
|
subnetwork = var.subnet.self_link
|
|
}
|
|
forwarding_rules_config = {
|
|
ipv4 = {
|
|
version = "IPV4"
|
|
}
|
|
ipv6 = {
|
|
version = "IPV6"
|
|
}
|
|
}
|
|
group_configs = {
|
|
my-group = {
|
|
zone = "europe-west1-b"
|
|
instances = [
|
|
"instance-1-self-link",
|
|
"instance-2-self-link"
|
|
]
|
|
}
|
|
}
|
|
backends = [{
|
|
group = module.ilb.groups.my-group.self_link
|
|
}]
|
|
}
|
|
# tftest modules=1 resources=5
|
|
```
|
|
|
|
### PSC service attachments
|
|
|
|
The optional `service_attachments` variable allows [publishing Private Service Connect services](https://cloud.google.com/vpc/docs/configure-private-service-connect-producer) by configuring up to one service attachment for each of the forwarding rules.
|
|
|
|
```hcl
|
|
module "ilb" {
|
|
source = "./fabric/modules/net-lb-int"
|
|
project_id = var.project_id
|
|
region = "europe-west1"
|
|
name = "ilb-test"
|
|
service_label = "ilb-test"
|
|
vpc_config = {
|
|
network = var.vpc.self_link
|
|
subnetwork = var.subnet.self_link
|
|
}
|
|
forwarding_rules_config = {
|
|
vip-one = {}
|
|
vip-two = {
|
|
global_access = false
|
|
ports = [80]
|
|
}
|
|
}
|
|
group_configs = {
|
|
my-group = {
|
|
zone = "europe-west1-b"
|
|
instances = [
|
|
"instance-1-self-link",
|
|
"instance-2-self-link"
|
|
]
|
|
}
|
|
}
|
|
backends = [{
|
|
group = module.ilb.groups.my-group.self_link
|
|
}]
|
|
service_attachments = {
|
|
vip-one = {
|
|
nat_subnets = [var.subnet_psc_1.self_link]
|
|
automatic_connection = true
|
|
}
|
|
vip-two = {
|
|
nat_subnets = [var.subnet_psc_2.self_link]
|
|
automatic_connection = true
|
|
}
|
|
}
|
|
}
|
|
# tftest modules=1 resources=7
|
|
```
|
|
|
|
### End to end example
|
|
|
|
This example spins up a simple HTTP server and combines four modules:
|
|
|
|
- [`nginx`](../cloud-config-container/nginx) from the `cloud-config-container` collection, to manage instance configuration
|
|
- [`compute-vm`](../compute-vm) to manage the instance template and unmanaged instance group
|
|
- this module to create an Internal Load Balancer in front of the managed instance group
|
|
|
|
Note that the example uses the GCE default service account. You might want to create an ad-hoc service account by combining the [`iam-service-account`](../iam-service-account) module, or by having the GCE VM module create one for you. In both cases, remember to set at least logging write permissions for the service account, or the container on the instances won't be able to start.
|
|
|
|
```hcl
|
|
module "cos-nginx" {
|
|
source = "./fabric/modules/cloud-config-container/nginx"
|
|
}
|
|
|
|
module "instance-group" {
|
|
source = "./fabric/modules/compute-vm"
|
|
for_each = toset(["b", "c"])
|
|
project_id = var.project_id
|
|
zone = "${var.region}-${each.key}"
|
|
name = "ilb-test-${each.key}"
|
|
network_interfaces = [{
|
|
network = var.vpc.self_link
|
|
subnetwork = var.subnet.self_link
|
|
nat = false
|
|
addresses = null
|
|
}]
|
|
boot_disk = {
|
|
initialize_params = {
|
|
image = "projects/cos-cloud/global/images/family/cos-stable"
|
|
type = "pd-ssd"
|
|
size = 10
|
|
}
|
|
}
|
|
tags = ["http-server", "ssh"]
|
|
metadata = {
|
|
user-data = module.cos-nginx.cloud_config
|
|
}
|
|
group = { named_ports = {} }
|
|
}
|
|
|
|
module "ilb" {
|
|
source = "./fabric/modules/net-lb-int"
|
|
project_id = var.project_id
|
|
region = var.region
|
|
name = "ilb-test"
|
|
service_label = "ilb-test"
|
|
vpc_config = {
|
|
network = var.vpc.self_link
|
|
subnetwork = var.subnet.self_link
|
|
}
|
|
forwarding_rules_config = {
|
|
"" = {
|
|
ports = [80]
|
|
}
|
|
}
|
|
backends = [
|
|
for z, mod in module.instance-group : {
|
|
group = mod.group.self_link
|
|
}
|
|
]
|
|
health_check_config = {
|
|
http = {
|
|
port = 80
|
|
}
|
|
}
|
|
}
|
|
# tftest modules=3 resources=7 e2e
|
|
```
|
|
|
|
## Issues
|
|
|
|
There are some corner cases where Terraform raises a cycle error on apply, for example when using the entire ILB module as a value in `for_each` counts used to create static routes in the VPC module. These are easily fixed by using forwarding rule ids instead of modules as values in the `for_each` loop.
|
|
|
|
<!--
|
|
One other issue is a `Provider produced inconsistent final plan` error which is sometimes raised when switching template version. This seems to be related to this [open provider issue](https://github.com/terraform-providers/terraform-provider-google/issues/3937), but it's relatively harmless since the resource is updated, and subsequent applies raise no errors.
|
|
-->
|
|
|
|
<!-- BEGIN TFDOC -->
|
|
## Variables
|
|
|
|
| name | description | type | required | default |
|
|
|---|---|:---:|:---:|:---:|
|
|
| [name](variables.tf#L184) | Name used for all resources. | <code>string</code> | ✓ | |
|
|
| [project_id](variables.tf#L189) | Project id where resources will be created. | <code>string</code> | ✓ | |
|
|
| [region](variables.tf#L200) | GCP region. | <code>string</code> | ✓ | |
|
|
| [vpc_config](variables.tf#L226) | VPC-level configuration. | <code title="object({ network = string subnetwork = string })">object({…})</code> | ✓ | |
|
|
| [backend_service_config](variables.tf#L17) | Backend service level configuration. | <code title="object({ connection_draining_timeout_sec = optional(number) connection_tracking = optional(object({ idle_timeout_sec = optional(number) persist_conn_on_unhealthy = optional(string) track_per_session = optional(bool) })) enable_subsetting = optional(bool) failover_config = optional(object({ disable_conn_drain = optional(bool) drop_traffic_if_unhealthy = optional(bool) ratio = optional(number) })) log_sample_rate = optional(number) protocol = optional(string, "UNSPECIFIED") session_affinity = optional(string) timeout_sec = optional(number) })">object({…})</code> | | <code>{}</code> |
|
|
| [backends](variables.tf#L51) | Load balancer backends. | <code title="list(object({ group = string description = optional(string, "Terraform managed.") failover = optional(bool, false) }))">list(object({…}))</code> | | <code>[]</code> |
|
|
| [description](variables.tf#L62) | Optional description used for resources. | <code>string</code> | | <code>"Terraform managed."</code> |
|
|
| [forwarding_rules_config](variables.tf#L68) | The optional forwarding rules configuration. | <code title="map(object({ address = optional(string) description = optional(string) global_access = optional(bool, true) ip_version = optional(string) ports = optional(list(string), null) protocol = optional(string, "TCP") }))">map(object({…}))</code> | | <code title="{ "" = {} }">{…}</code> |
|
|
| [group_configs](variables.tf#L83) | Optional unmanaged groups to create. Can be referenced in backends via outputs. | <code title="map(object({ zone = string description = optional(string, "Terraform managed.") instances = optional(list(string)) named_ports = optional(map(number), {}) }))">map(object({…}))</code> | | <code>{}</code> |
|
|
| [health_check](variables.tf#L95) | Name of existing health check to use, disables auto-created health check. | <code>string</code> | | <code>null</code> |
|
|
| [health_check_config](variables.tf#L101) | Optional auto-created health check configuration, use the output self-link to set it in the auto healing policy. Refer to examples for usage. | <code title="object({ check_interval_sec = optional(number) description = optional(string, "Terraform managed.") enable_logging = optional(bool, false) healthy_threshold = optional(number) timeout_sec = optional(number) unhealthy_threshold = optional(number) grpc = optional(object({ port = optional(number) port_name = optional(string) port_specification = optional(string) # USE_FIXED_PORT USE_NAMED_PORT USE_SERVING_PORT service_name = optional(string) })) http = optional(object({ host = optional(string) port = optional(number) port_name = optional(string) port_specification = optional(string) # USE_FIXED_PORT USE_NAMED_PORT USE_SERVING_PORT proxy_header = optional(string) request_path = optional(string) response = optional(string) })) http2 = optional(object({ host = optional(string) port = optional(number) port_name = optional(string) port_specification = optional(string) # USE_FIXED_PORT USE_NAMED_PORT USE_SERVING_PORT proxy_header = optional(string) request_path = optional(string) response = optional(string) })) https = optional(object({ host = optional(string) port = optional(number) port_name = optional(string) port_specification = optional(string) # USE_FIXED_PORT USE_NAMED_PORT USE_SERVING_PORT proxy_header = optional(string) request_path = optional(string) response = optional(string) })) tcp = optional(object({ port = optional(number) port_name = optional(string) port_specification = optional(string) # USE_FIXED_PORT USE_NAMED_PORT USE_SERVING_PORT proxy_header = optional(string) request = optional(string) response = optional(string) })) ssl = optional(object({ port = optional(number) port_name = optional(string) port_specification = optional(string) # USE_FIXED_PORT USE_NAMED_PORT USE_SERVING_PORT proxy_header = optional(string) request = optional(string) response = optional(string) })) })">object({…})</code> | | <code title="{ tcp = { port_specification = "USE_SERVING_PORT" } }">{…}</code> |
|
|
| [labels](variables.tf#L178) | Labels set on resources. | <code>map(string)</code> | | <code>{}</code> |
|
|
| [protocol](variables.tf#L194) | Forwarding rule protocol used, defaults to TCP. | <code>string</code> | | <code>"TCP"</code> |
|
|
| [service_attachments](variables.tf#L205) | PSC service attachments, keyed by forwarding rule. | <code title="map(object({ nat_subnets = list(string) automatic_connection = optional(bool, false) consumer_accept_lists = optional(map(string), {}) consumer_reject_lists = optional(list(string)) description = optional(string) domain_name = optional(string) enable_proxy_protocol = optional(bool, false) reconcile_connections = optional(bool) }))">map(object({…}))</code> | | <code>null</code> |
|
|
| [service_label](variables.tf#L220) | Optional prefix of the fully qualified forwarding rule name. | <code>string</code> | | <code>null</code> |
|
|
|
|
## Outputs
|
|
|
|
| name | description | sensitive |
|
|
|---|---|:---:|
|
|
| [backend_service](outputs.tf#L17) | Backend resource. | |
|
|
| [backend_service_id](outputs.tf#L22) | Backend id. | |
|
|
| [backend_service_self_link](outputs.tf#L27) | Backend self link. | |
|
|
| [forwarding_rule_addresses](outputs.tf#L32) | Forwarding rule address. | |
|
|
| [forwarding_rule_self_links](outputs.tf#L40) | Forwarding rule self links. | |
|
|
| [forwarding_rules](outputs.tf#L48) | Forwarding rule resources. | |
|
|
| [group_self_links](outputs.tf#L56) | Optional unmanaged instance group self links. | |
|
|
| [groups](outputs.tf#L63) | Optional unmanaged instance group resources. | |
|
|
| [health_check](outputs.tf#L68) | Auto-created health-check resource. | |
|
|
| [health_check_id](outputs.tf#L73) | Auto-created health-check id. | |
|
|
| [health_check_self_link](outputs.tf#L78) | Auto-created health-check self link. | |
|
|
| [id](outputs.tf#L83) | Fully qualified forwarding rule ids. | |
|
|
| [service_attachment_ids](outputs.tf#L91) | Service attachment ids. | |
|
|
<!-- END TFDOC -->
|