# cluster

## Summary

A `cluster` handles final routing of each request to its intended target. Each `cluster` can have 0 or more instances defined, which are simply the host:port pairs of the targets. Instances within a cluster can be statically configured when the object is created, or dynamically loaded through the [service discovery mechanisms](https://github.com/DecipherNow/gm-gitbook-sync/tree/b88085226e88844739eb923e6a3b5b82bf4294b6/usage/fabric/api/discovery/README.md)

### Features

* Static or dynamic instances
* Circuit breakers
* Health Checks
* Outlier Detection
* Outgoing SSL configuration
  * Directly via SSL certs on disk
  * Through SPIFFE/SPIRE and Envoy SDS

### Example Object

```javascript
{
    "zone_key": "default-zone",
    "cluster_key": "catalog-service",
    "name": "service",
    "instances": [
        {
            "host": "localhost",
            "port": 8080
        }
    ],
    "circuit_breakers": {
      "max_connections": 500,
      "max_requests": 500
    },
    "outlier_detection": null,
    "health_checks": [],
    "lb_policy": "",
    "secret": {
        "secret_key": "",
        "secret_name": "",
        "secret_validation_name": "",
        "subject_alt_name": "",
        "ecdh_curves": null,
        "set_current_client_cert_details": {
            "uri": false
        },
        "checksum": ""
    }
}
```

### TLS Configuration

To require TLS on the `cluster` object, an additional field, `require_tls` must be set to true.

There is also an optional `ssl_config` field, which can be set to specify it's configuration. The Cluster SSL Config Object appears as follows:

```javascript
"ssl_config": {
  "cipher_filter": "",
  "protocols": [],
  "cert_key_pairs": null,
  "trust_file": "",
  "sni": null
}
```

The Cluster SSL Configuration is used to populate an [UpstreamTlsContext](https://www.envoyproxy.io/docs/envoy/v1.13.0/api-v3/extensions/transport_sockets/tls/v3/cert.proto.html#extensions-transport-sockets-tls-v3-upstreamtlscontext) for the Envoy Cluster.

The `sni` field for a `cluster` accepts a string that the Envoy cluster uses to specify Server Name Indication when creating TLS backend connections.

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 set a specified cipher list for TLS. This populates Envoys `cipher_suites` field.

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 Cluster connects to a service that's 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`.

### Secret Configuration for SPIFFE/SPIRE

To configure the service to use SPIFFE/SPIRE on its egress, you must set a `secret` on the cluster. In the same form as above, `require_tls` **must** be set to true. Note that if both an `ssl_config` and a `secret` are set on a cluster, the secret will override the ssl configuration. An example secret object is as follows:

```javascript
"secret" : {
  "secret_key": "secret-{{.service.serviceName}}-secret",
  "secret_name": "spiffe://{{ .Values.global.spire.trustDomain }}/{{.service.serviceName}}/mTLS",
  "secret_validation_name": "spiffe://{{ .Values.global.spire.trustDomain }}",
  "ecdh_curves": [
    "X25519:P-256:P-521:P-384"
  ]
}
```

This object will configure Envoy to use Secret Discovery Service to fetch SPIFFE certificates from the configured path specified as an environment variable `SPIRE_PATH` in `gm-proxy`. For information on how Envoy's SDS works, see the [docs](https://www.envoyproxy.io/docs/envoy/v1.13.1/configuration/security/secret.html). The `secret_key` specifies the name of the secret to fetch. `secret_name` should be the [SPIFFE Id](https://github.com/spiffe/spiffe/blob/master/standards/SPIFFE-ID.md#2-spiffe-identity) of your certificate. `secret_validation_name` will set the validation context for the sds secret config.

### Envoy Reference

* [Envoy Cluster Reference](https://www.envoyproxy.io/docs/envoy/v1.13.1/api-v3/config/cluster/v3/cluster.proto)

### Fields

#### `cluster_key`

A unique key used to identify this particular cluster configuration. This key is used in [routes](https://greymatter.gitbook.io/grey-matter-documentation/usage/fabric/api/route) or [shared\_rules](https://greymatter.gitbook.io/grey-matter-documentation/usage/fabric/api/shared_rules) to handle routing of traffic to an endpoint.

#### `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 the service that this cluster is addressing. This field has different behavior depending on whether this cluster will be pulling [instances](#instances) from service discovery or wether they will be manually inserted.

When [instances](#instances) are manually inserted, this field has no affect. When they will instead be auto-populated, this field must match the announced service name from [service discovery](#../discovery/README.md).

#### `require_tls`

If `true`, this cluster will only accept HTTPS connections. In this case, one of the [secret](#secret) or [ssl\_config](#sslconfig) fields should be set. If `false`, this cluster will only accept plaintext HTTP connections.

#### `secret`

Configure SSL certificate configuration through Envoy's SDS (Secret Discovery Service)

#### `ssl_config`

[Cluster SSL configuration](https://greymatter.gitbook.io/grey-matter-documentation/usage/fabric/api/cluster/cluster-ssl-config) for this cluster.

#### `instances`

An array of instances that this cluster will use to route requests. Can be either manually inserted, or automatically populated from service discovery.

The order of how instances will handle requests is governed by the [lb\_policy](#lbpolicy) field.

#### `circuit_breakers`

Default and high priority [circuit breakers](https://greymatter.gitbook.io/grey-matter-documentation/usage/fabric/api/cluster/circuit-breakers)

#### `outlier_detection`

[outlier detection](https://greymatter.gitbook.io/grey-matter-documentation/usage/fabric/api/cluster/outlier-detection)

#### `health_checks`

Array of [health checks](https://greymatter.gitbook.io/grey-matter-documentation/usage/fabric/api/cluster/health-check).

#### `lb_policy`

[Envoy Load Balancing Policy](https://www.envoyproxy.io/docs/envoy/v1.13.1/api-v3/config/cluster/v3/cluster.proto.html?highlight=lb_policy#envoy-v3-api-enum-config-cluster-v3-cluster-lbpolicy).

Defaults to `least_request`, supported options are: `round_robin`, `least_request`, `ring_hash`, `random`, `maglev`, and `cluster_provided`.

#### `checksum`

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