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.
Virtual host:port matching and redirecting
GZIP of requests
CORS
Setting custom headers for downstream requests
SSL Config for incoming requests
{"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"}],"crl": {"filename": "/etc/proxy/tls/sidecar/ca.crl"},"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"}
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,"crl": 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.
Specifying the path to a trust_file
is optional. If a path is specified, it will be added to the UpstreamTlsContext for verifying a presented server certificate. Otherwise, the server certificate will not be verified.
If the Domain's Listener points to a service that is secured via TLS, the trust_file
will need to contain the root CA and any intermediate certificates to authenticate the sidecar as a client of the service. If you're unfamiliar with generating certificates, OpenSSL Certificate Authority is a great primer. The end result is that you have all trust certificates required by the service in a single file, the trust_file
.
Specifying a crl
(a PEM-encoded certificate revocation list) is also optional, and may be added by pointing to a path on disk to a CRL file from the crl.filename
field or by specifying CRLs directly through the crl.inline_string
field. More details on CRL configuration can be found in the Cluster SSL Configuration Guide.
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
A unique key used to identify this particular domain configuration. This key is used in proxy
, listener
, and route
objects.
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.
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.
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.
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.
Array of URL redirects
DEPRECATION: This field has been deprecated and will be removed in the next major version release.
This field has no effect.
A CORS policy to attach to this domain.
An array of additional hostnames that should be matched in this domain. E.g. name: "www.greymatter.io"
with aliases: ["greymatter.io", "localhost"]
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.
DEPRECATION: This field has been deprecated and will be removed in the next major version release. Use route.request_headers_to_add to expose custom headers at the route level instead.
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"}]
An API calculated checksum. Can be used to verify that the API contains the expected object before performing a write.