gateway Stanza

The gateway stanza allows configuration of Consul Connect Gateways. Nomad will automatically create the necessary Gateway Configuration Entry as well as inject an Envoy proxy task into the Nomad job to serve as the Gateway.

The gateway configuration is valid within the context of a connect stanza. Additional information about Gateway configurations can be found in Consul's Connect Gateways documentation.

service {
  connect {
    gateway {
      # ...
    }
  }
}

gateway Parameters

Exactly one of ingress or terminating must be configured.

• proxy (proxy: nil) - Configuration of the Envoy proxy that will be injected into the task group.
• ingress (ingress: nil) - Configuration Entry of type ingress-gateway that will be associated with the service.
• terminating (terminating: nil) - Configuration Entry of type terminating-gateway that will be associated with the service.

proxy Parameters

• connect_timeout (string: "5s") - The amount of time to allow when making upstream connections before timing out. Defaults to 5 seconds. If the upstream service has the configuration option connect_timeout_ms set for the service-resolver, that timeout value will take precedence over this gateway proxy option.
• envoy_gateway_bind_tagged_addresses (bool: false) - Indicates that the gateway services tagged addresses should be bound to listeners in addition to the default listener address.
• envoy_gateway_bind_addresses (map<string|address>: nil) - A map of additional addresses to be bound. The keys to this map are the same of the listeners to be created and the values are a map with two keys - address and port, that combined make the address to bind the listener to. These are bound in addition to the default address. If bridge networking is in use, this map is automatically populated with additional listeners enabling the Envoy proxy to work from inside the network namespace.

envoy_gateway_bind_addresses "<service>" {
  address = "0.0.0.0"
  port    = <port>
}

• envoy_gateway_no_default_bind (bool: false) - Prevents binding to the default address of the gateway service. This should be used with one of the other options to configure the gateway's bind addresses. If bridge networking is in use, this value will default to true since the Envoy proxy does not need to bind to the service address from inside the network namespace.
• envoy_dns_discovery_type (string: optional) - Determintes how Envoy will resolve hostnames. Defaults to LOGICAL_DNS. Must be one of STRICT_DNS or LOGICAL_DNS. Details for each type are available in the Envoy Documentation. This option applies to terminating gateways that route to services addressed by a hostname.
• config (map: nil) - Escape hatch for Advanced Configuration of Envoy.

address Parameters

• address (string: required) - The address to bind to when combined with port.
• port (int: required) - The port to listen to.

ingress Parameters

• tls (tls: nil) - TLS configuration for this gateway.
• listener (array<listener> : required) - One or more listeners that the ingress gateway should setup, uniquely identified by their port number.

tls Parameters

• enabled (bool: false) - Set this configuration to enable TLS for every listener on the gateway. If TLS is enabled, then each host defined in the host field will be added as a DNSSAN to the gateway's x509 certificate.

listener Parameters

• port (int: required) - The port that the listener should receive traffic on.

• protocol (string: "tcp") - The protocol associated with the listener. Either tcp or http.

  Note: If using http, preconfiguring a service-default in Consul to set the Protocol of the service to http is recommended.

• service (array<service>: required) - One or more services to be exposed via this listener. For tcp listeners, only a single service is allowed.

service Parameters

• name (string: required) - The name of the service that should be exposed through this listener. This can be either a service registered in the catalog, or a service defined by other config entries, or a service that is going to be configured by Nomad. If the wildcard specifier * is provided, then ALL services will be exposed through this listener. This is not supported for a listener with protocol tcp.

• hosts (array<string>: nil) - A list of hosts that specify what requests will match this service. This cannot be used with a tcp listener, and cannot be specified alongside a wildcard (*) service name. If not specified, the default domain <service-name>.ingress.* will be used to match services. Requests must send the correct host to be routed to the defined service.

  The wildcard specifier * can be used by itself to match all traffic coming to the ingress gateway, if TLS is not enabled. This allows a user to route all traffic to a single service without specifying a host, allowing simpler tests and demos. Otherwise, the wildcard specifier can be used as part of the host to match multiple hosts, but only in the leftmost DNS label. This ensures that all defined hosts are valid DNS records. For example, *.example.com is valid while example.* and *-suffix.example.com are not.

  Note: If a well-known port is not used, i.e. a port other than 80 (http) or 443 (https), then the port must be appended to the host to correctly match traffic. This is defined in the HTTP/1.1 RFC. If TLS is enabled, then the host without the port must be added to the hosts field as well. TLS verification only matches against the hostname of the incoming connection, and does not take into account the port.

terminating Parameters

• service (array<linked-service>: required) - One or more services to be linked with the gateway. The gateway will proxy traffic to these services. These linked services must be registered with Consul for the gateway to discover their addresses. They must also be registered in the same Consul datacenter as the terminating gateway.

service Parameters

• name (string: required) - The name of the service to link with the gateway. If the wildcard specifier * is provided, then ALL services within the Consul namespace wil lbe linked with the gateway.

• ca_file (string: <optional>) - A file path to a PEM-encoded certificate authority. The file must be accessible by the gateway task. The certificate authority is used to verify the authenticity of the service linked with the gateway. It can be provided along with a cert_file and key_file for mutual TLS authentication, or on its own for one-way TLS authentication. If none is provided the gateway will not encrypt traffic to the destination.

• cert_file (string: <optional>) - A file path to a PEM-encoded certificate. The file must be accessible by the gateway task. The certificate is provided to servers to verify the gateway's authenticity. It must be provided if a key_file is provided.

• key_file (string: <optional>) - A file path to a PEM-encoded private key. The file must be accessible by the gateway task. The key is used with the certificate to verify the gateway's authenticity. It must be provided if a cert_file is provided.

• sni (string: <optional>) - An optional hostname or domain name to specify during the TLS handshake.

Gateway with host networking

Nomad supports running gateways using host networking. A static port must be allocated for use by the Envoy admin interface and assigned to the proxy service definition.

Specify Envoy image

The Docker image used for Connect gateway tasks defaults to the official Envoy Docker image, envoyproxy/envoy:v${NOMAD_envoy_version}, where ${NOMAD_envoy_version} is resolved automatically by a query to Consul. The image to use can be configured by setting meta.connect.gateway_image in the Nomad job. Custom images can still make use of the envoy version interpolation, e.g.

meta.connect.gateway_image = custom/envoy-${NOMAD_envoy_version}:latest

Custom gateway task

The task created for the gateway can be configured manually using the sidecar_task stanza.

connect {
  gateway {
    # ...
  }
 
  sidecar_task {
    # see /docs/job-specification/sidecar_task for more details
  }
}

Examples

ingress gateway

job "ingress-demo" {

  datacenters = ["dc1"]

  # This group will have a task providing the ingress gateway automatically
  # created by Nomad. The ingress gateway is based on the Envoy proxy being
  # managed by the docker driver.
  group "ingress-group" {

    network {
      mode = "bridge"

      # This example will enable plain HTTP traffic to access the uuid-api connect
      # native example service on port 8080.
      port "inbound" {
        static = 8080
        to     = 8080
      }
    }

    service {
      name = "my-ingress-service"
      port = "8080"

      connect {
        gateway {

          # Consul gateway [envoy] proxy options.
          proxy {
            # The following options are automatically set by Nomad if not
            # explicitly configured when using bridge networking.
            #
            # envoy_gateway_no_default_bind = true
            # envoy_gateway_bind_addresses "uuid-api" {
            #   address = "0.0.0.0"
            #   port    = <associated listener.port>
            # }
            #
            # Additional options are documented at
            # https://www.nomadproject.io/docs/job-specification/gateway#proxy-parameters
          }

          # Consul Ingress Gateway Configuration Entry.
          ingress {
            # Nomad will automatically manage the Configuration Entry in Consul
            # given the parameters in the ingress block.
            #
            # Additional options are documented at
            # https://www.nomadproject.io/docs/job-specification/gateway#ingress-parameters
            listener {
              port     = 8080
              protocol = "tcp"
              service {
                name = "uuid-api"
              }
            }
          }
        }
      }
    }
  }

  # The UUID generator from the connect-native demo is used as an example service.
  # The ingress gateway above makes access to the service possible over normal HTTP.
  # For example,
  #
  # $ curl $(dig +short @127.0.0.1 -p 8600 uuid-api.ingress.dc1.consul. ANY):8080
  group "generator" {
    network {
      mode = "host"
      port "api" {}
    }

    service {
      name = "uuid-api"
      port = "api"

      connect {
        native = true
      }
    }

    task "generate" {
      driver = "docker"

      config {
        image        = "hashicorpnomad/uuid-api:v5"
        network_mode = "host"
      }

      env {
        BIND = "0.0.0.0"
        PORT = "${NOMAD_PORT_api}"
      }
    }
  }
}

terminating gateway

job "countdash-terminating" {

  datacenters = ["dc1"]

  # This group provides the service that exists outside of the Consul Connect
  # service mesh. It is using host networking and listening to a statically
  # allocated port.
  group "api" {
    network {
      mode = "host"
      port "port" {
        static = "9001"
      }
    }

    # This example will enable services in the service mesh to make requests
    # to this service which is not in the service mesh by making requests
    # through the terminating gateway.
    service {
      name = "count-api"
      port = "port"
    }

    task "api" {
      driver = "docker"

      config {
        image        = "hashicorpnomad/counter-api:v3"
        network_mode = "host"
      }
    }
  }

  group "gateway" {
    network {
      mode = "bridge"
    }

    service {
      name = "api-gateway"

      connect {
        gateway {
          # Consul gateway [envoy] proxy options.
          proxy {
            # The following options are automatically set by Nomad if not explicitly
            # configured with using bridge networking.
            #
            # envoy_gateway_no_default_bind = true
            # envoy_gateway_bind_addresses "default" {
            #   address = "0.0.0.0"
            #   port    = <generated listener port>
            # }
            # Additional options are documented at
            # https://www.nomadproject.io/docs/job-specification/gateway#proxy-parameters
          }

          # Consul Terminating Gateway Configuration Entry.
          terminating {
            # Nomad will automatically manage the Configuration Entry in Consul
            # given the parameters in the terminating block.
            #
            # Additional options are documented at
            # https://www.nomadproject.io/docs/job-specification/gateway#terminating-parameters
            service {
              name = "count-api"
            }
          }
        }
      }
    }
  }

  # The dashboard service is in the service mesh, making use of bridge network
  # mode and connect.sidecar_service. When running, the dashboard should be
  # available from a web browser at localhost:9002.
  group "dashboard" {
    network {
      mode = "bridge"

      port "http" {
        static = 9002
        to     = 9002
      }
    }

    service {
      name = "count-dashboard"
      port = "9002"

      connect {
        sidecar_service {
          proxy {
            upstreams {
              # By configuring an upstream destination to the linked service of
              # the terminating gateway, the dashboard is able to make requests
              # through the gateway to the count-api service.
              destination_name = "count-api"
              local_bind_port  = 8080
            }
          }
        }
      }
    }

    task "dashboard" {
      driver = "docker"

      env {
        COUNTING_SERVICE_URL = "http://${NOMAD_UPSTREAM_ADDR_count_api}"
      }

      config {
        image = "hashicorpnomad/counter-dashboard:v3"
      }
    }
  }
}