terraform-google-https-ingress

A Terraform module for building HTTP/S load balancing ingresses with similar features to GKE ingress automation (but better).

Contents

• Simplest Example
• Features
• Best Example
• 2nd-Best Example
• Detailed Documentation
• Input Variables

Simplest Example

First, let's see how simple this module can be to use. This invocation of the module configures global HTTP and HTTPS load balancing to your Backend Service using a "Classic" load-balancer-authorized SSL certificate (including allocating an IP address, arranging for http:// requests to be redirected to https://, and creating a simple URL Map but not setting up DNS records for it).

module "my-ingress" {
  source            = (
    "github.com/TyeMcQueen/terraform-google-https-ingress" )
  name-prefix       = "my-svc-"
  hostnames         = [ "my-svc.my-product.example.com" ]
  create-lb-certs   = true
  backend-ref       = google_compute_backend_service.my-svc.id
}

You can get additional security and reliability benefits by using a certificate map from Cloud Certificate Manager (see examples below).

You need to create a Backend Service (or a custom URL Map). You may want to use one of these related Terraform modules to do that:

• backend-to-gke - Builds a Backend Service to route to NEGs created for a Kubernetes Workload deployed to 1 or more GKE clusters.
• ingress-to-gke - A wrapper that combines the backend-to-gke and http-ingress modules to make it very simple to build a full ingress to a GKE Workload (perhaps running in multiple regions).

The LB-authorized certificate will not become active until your hostname is set up in DNS to point to the allocated IP address (plus about 20 minutes to finish the automated authorization process).

Features

This module makes it easy to allocate GCP Global L7 (HTTP/S) Load Balancing to route to a GCP Backend Service or to a custom URL Map.

Very Simple

This module makes common use cases very simple to achieve.

More Complete

This module can set up everything needed for an ingress to your backend: allocate the IP address, set up DNS records for your hostname(s), create GCP-Managed SSL Certificates (3 different kinds), create a simple URL Map, and tie all of the load-balancing pieces of infrastructure together. Or you can easily tell it to use specific parts that you manage outside of the module for maximum flexibility.

Can Use A Certificate Map

You can use GCP's new Cloud Certificate Manager to create a certificate map which provides more reliability and security benefits and can auto-renew even wildcard certs. See the certificate-map-simple module for more about these benefits.

More Flexibility

This module supports full control over nearly every aspect of the creation of this infrastructure. You can do more advanced configurations like:

• Share a URL Map and/or an IP Address between multiple Backends
• Choose between Classic and Modern L7 LB schemes
• Use any advanced URL Map features
• Migrate traffic with no interruption of service

Best Example

This example provides the most benefits (including better reliability and security and simpler troubleshooting) and is still very simple but requires that your hostnames are part of a GCP-Managed DNS Zone that your Terraform workspace has write access to. It even creates the DNS records for your hostnames.

module "my-ingress" {
  source            = (
    "github.com/TyeMcQueen/terraform-google-http-ingress" )
  name-prefix       = "my-svc-"
  map-name          = "my-svc"
  hostnames         = [ "honeypot", "svc" ]
  exclude-honeypot  = true
  dns-zone-ref      = "my-zone"
  dns-add-hosts     = true
  backend-ref       = google_compute_backend_service.my-svc.id
}

By using a Cloud Certificate Manager certificate map you get additional benefits including a "honeypot" hostname, a certificate for which will be given to hackers that hit your load balancer IP address using HTTPS but with some random hostname. This prevents the hackers from trivially being able to discover the hostname to use for further scanning/attack attempts. And exclude-honeypot means requests that use the honeypot hostname will not even be routed to your Backend.

The certificate-map-simple module that this module uses fully documents these additional benefits.

Avoiding Nested Modules

The above example is the same as the following example where the use of the other module is made explicit. This approach is recommended by Terraform as a best practice for combining modules. But you can start with the simpler usage above and then move to this more verbose usage if and when the need arises.

module "my-cert-map" {
  source            = (
    "github.com/TyeMcQueen/terraform-google-certificate-map-simple" )
  name-prefix       = "my-svc-"
  map-name1         = "my-svc"
  hostnames1        = [ "honeypot", "svc" ]
  dns-zone-ref      = "my-zone"
}

module "my-ingress" {
  source            = (
    "github.com/TyeMcQueen/terraform-google-http-ingress" )
  name-prefix       = "my-svc-"
  hostnames         = [ "honeypot", "svc" ]
  exclude-honeypot  = true
  dns-zone-ref      = "my-zone"
  dns-add-hosts     = true
  backend-ref       = google_compute_backend_service.my-svc.id
  cert-map-ref      = module.my-cert-map[0].map-id1[0]
  # Above added in place of `map-name`
}

2nd-Best Example

If your Terraform workspace can't manage the DNS Zone for your hostname(s), then you can still get the "honeypot" benefit of using a certificate map by using "modern" LB-authorized certificates (by appending "|LB" to each hostname).

module "my-ingress" {
  source            = (
    "github.com/TyeMcQueen/terraform-google-http-ingress" )
  name-prefix       = "my-svc-"
  map-name          = "my-svc"
  hostnames         = [
    "honeypot.my-product.example.com|LB",
    "my-svc.my-product.example.com|LB",
  ]
  exclude-honeypot  = true
  backend-ref       = google_compute_backend_service.my-svc.id
}

This way you lose some minor resiliency benefits of using DNS-authorized certificates, but those may not be worth the added complexity of using DNS-authorized certs when the authorization can't be automated. Though, if you want to migrate traffic to this new configuration without any disruption, then you will need to use DNS-authorized certificates or temporarily use customer-managed certificates.

Detailed Documentation

This module is very flexible/powerful, supporting a lot of options that give you full control over your infrastructure. We encourage you to start with one of the simple examples (above) and customize that as needed. If you try to look at all of the possible options, it is easy to be overwhelmed.

Most aspects of the module are documented from multiple angles. When you are ready to customize, you should probably start with the Usage documentation. Depending on what angle you want to look from, you can also look at any of these lists:

• What infrastructure can be created
• Input variables.tf or the sorted list of links to the documentation for each input.
• Known limitations

The Usage documentation includes the following sections:

• Option Toggles
• Certificate Types
• Hostnames
• Major Options

outputs.tf simply lists all of the outputs from this module.

Limitations:

• Google Providers
• Error Handling
• Unused Resource Types

You should also be aware of types of changes that require special care as documented in the other module's limitations: Deletions.

Input Variables

• backend-ref
• bad-host-backend
• bad-host-code
• bad-host-host
• bad-host-path
• bad-host-redir
• cert-map-ref
• create-lb-certs
• description
• dns-add-hosts
• dns-ttl-secs
• dns-zone-ref
• exclude-honeypot
• hostnames
• http-redir-code
• ip-addr-ref
• ip-is-shared
• labels
• lb-cert-refs
• lb-scheme
• map-cert-ids
• map-name
• name-prefix
• project
• quic-override
• redirect-http
• url-map-ref