# 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.

**NOTE**The domain port should, in most cases, match the `port` of the [`listener`](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/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

```javascript
{
  "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"
}
```

### 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:

```javascript
"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](https://www.envoyproxy.io/docs/envoy/v1.15.0/api-v3/extensions/transport_sockets/tls/v3/tls.proto#extensions-transport-sockets-tls-v3-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](https://jamielinux.com/docs/openssl-certificate-authority/introduction.html) 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](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/cluster/cluster-ssl-config#crl).

### Redirects

This field can be used to configure redirect routes for the domain. See [Redirect](https://greymatter.gitbook.io/grey-matter-documentation/1.3/usage/traffic_control/routing) 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](https://www.envoyproxy.io/docs/envoy/v1.15.0/api-v3/config/route/v3/route_components.proto#config-route-v3-virtualhost)

### 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](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/route). Is used in conjunction with the [port](#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](#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](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/domain/listener-ssl-config) for this cluster. Setting the SSL Config at the `domain` level set this same config on all [listeners](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/listener) that are directly linked to this domain.

#### `redirects`

Array of URL [redirects](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/domain/redirect)

#### `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](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/domain/cors_config) 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](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/listener) or [ssl\_config](#sslconfig) fields should be set. If `false`, attached listeners will only accept plaintext HTTP connections.

#### `custom_headers`

> DEPRECATION: This field has been deprecated and will be removed in the next major version release. Use [route.request\_headers\_to\_add](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/shared_rules#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.

```javascript
"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.