domain

Summary

Each domain controls requests for a specific host:port. This permits different handling of requests to domains like localhost:8080 or catalog:8080 if desired. If uniform handling is required, wildcards are understood to apply to all domains. A domain set to match *:8080 will match both of the above domains.

NOTEThe domain port should, in most cases, match the port of the listener exposed on the proxy. If they do not match, users will need to supply HOST: header keywords to all requests to match the virtual domain.

Features

• Virtual host:port matching and redirecting

• GZIP of requests

• CORS

• Setting custom headers for downstream requests

• SSL Config for incoming requests

Example Object

{
  "domain_key": "catalog",
  "zone_key": "default",
  "name": "*",
  "port": 9080,
  "ssl_config": {
    "cipher_filter": "",
    "protocols": [
      "TLSv1.1",
      "TLSv1.2"
    ],
    "cert_key_pairs": [
      {
        "certificate_path": "/etc/proxy/tls/sidecar/server.crt",
        "key_path": "/etc/proxy/tls/sidecar/server.key"
      }
    ],
    "require_client_certs": true,
    "trust_file": "/etc/proxy/tls/sidecar/ca.crt",
    "sni": null
  },
  "redirects": null,
  "gzip_enabled": false,
  "cors_config": null,
  "aliases": null,
  "force_https": true,
  "custom_headers": null,
  "checksum": "b633fd4b535932fc1da31fbb7c6d4c39517871d112e9bce2d5ffe004e6d09735"
}

TLS Configuration

NOTE Do not set an ssl_config on any domain object whose service you want to use SPIFFE/SPIRE. If a domain ssl_config is set, it will override the secret set on the corresponding listener and the mesh configuration will be wrong.

The domain object has an optional ssl_config field, which can be used to set up TLS and specify it's configuration. The Domain SSL Config Object appears as follows:

"ssl_config": {
  "cipher_filter": "",
  "protocols": [],
  "cert_key_pairs": null,
  "require_client_certs": false,
  "trust_file": "",
  "sni": null
}

The Domain SSL Configuration is used to populate a DownstreamTlsContext for the Envoy Listener.

The sni field for a domain accepts a list of strings and configures the Envoy Listener to detect the requested Server Name Indication.

To specify a minimum and maximum TLS protocol version, set the protocols field to one of the following: "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3". If one protocol is specified, it will be set as both the minimum and maximum protocol versions in Envoy. If more than one protocol version is specified in the list, the lowest will set the minimum TLS protocol version and the highest will set the maximum TLS protocol version. If this field is left empty, Envoy will choose the default TLS version.

The cipher_filter field takes a colon : delimited string to populate the cipher_suites cipher list in envoy for TLS.

redirects

This field can be used to configure redirect routes for the domain. See Redirect for details.

Fields:

• name

  • the name of the redirect

• from

  • regex value that the incoming request :path will be regex matched to

• to

  • the new URL that an incoming request matching from will route to

  • if set to "$host", will redirect to the name of the domain

• redirect_type

  • determines the response code of the redirect

  • must be one of: "permanent" (for a 301 code), "temporary" (for a 307 code)

• header_constraints

  • a list of header constraint objects

  • each header constraint has the following fields:

    • name

      • the header key to be compared to the incoming requests headers

      • will be compared without case sensitivity

    • value

      • must be a valid regex

      • the value to be compared to the value of the incoming request header with matching name

    • case_sensitive

      • boolean indicating whether the value will be compared to the value of the header with matching name with case sensitivity

    • invert

      • boolean value

Envoy Reference

• Envoy Virtual Host Reference

Fields

domain_key

A unique key used to identify this particular domain configuration. This key is used in proxy, listener, and route objects.

zone_key

The zone in which this object will live. It will only be able to be referenced by objects or sent to Sidecars that live in the same zone.

name

The name of this virtual domain, e.g. localhost, www.greymatter.io, or catalog.svc.local. Only requests coming in to the named host will be matched and handled by attached routes. Is used in conjunction with the port field.

This field can be set to a wildcard (*) which will match against all hostnames.

port

Set the specific port of the virtual host to match. Is used in conjunction with the name field.

E.g. port: 8080 and name: * will setup a virtual domain matching any request made to port 8080 regardless of the host.

ssl_config

Listener SSL configuration for this cluster. Setting the SSL Config at the domain level set this same config on all listeners that are directly linked to this domain.

redirects

Array of URL redirects

gzip_enabled

DEPRECATION: This field has been deprecated and will be removed in the next major version release.

This field has no effect.

cors_config

A CORS policy to attach to this domain.

aliases

An array of additional hostnames that should be matched in this domain. E.g. name: "www.greymatter.io" with aliases: ["greymatter.io", "localhost"]

force_https

If true, listeners attached to this domain will only accept HTTPS connections. In this case, one of the secret or ssl_config fields should be set. If false, attached listeners will only accept plaintext HTTP connections.

custom_headers

An array of header key, value pairs to set on all requests that pass through this domain.

E.g.

"custom_headers" : [
  {
    "key": "x-forwarded-proto",
    "value": "https"
  }
]

checksum

An API calculated checksum. Can be used to verify that the API contains the expected object before performing a write.