cluster

Search…
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​
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
Load balancing policy and its configurations
Example Object
1
{
2
    "zone_key": "default-zone",
3
    "cluster_key": "catalog-service",
4
    "name": "service",
5
    "instances": [
6
        {
7
            "host": "localhost",
8
            "port": 8080
9
        }
10
    ],
11
    "circuit_breakers": {
12
      "max_connections": 500,
13
      "max_requests": 500
14
    },
15
    "outlier_detection": null,
16
    "health_checks": [],
17
    "lb_policy": "",
18
    "http2_protocol_options": {},
19
    "secret": {
20
        "secret_key": "",
21
        "secret_name": "",
22
        "secret_validation_name": "",
23
        "subject_alt_name": "",
24
        "ecdh_curves": null,
25
        "set_current_client_cert_details": {
26
            "uri": false
27
        },
28
        "checksum": ""
29
    }
30
}
Copied!
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 its configuration. The Cluster SSL Config Object appears as follows:
1
"ssl_config": {
2
  "cipher_filter": "",
3
  "protocols": [],
4
  "cert_key_pairs": null,
5
  "trust_file": "",
6
  "crl": null,
7
  "sni": null
8
}
Copied!
The Cluster SSL Configuration is used to populate an 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 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.
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:
1
"secret" : {
2
  "secret_key": "secret-{{.service.serviceName}}-secret",
3
  "secret_name": "spiffe://{{ .Values.global.spire.trustDomain }}/{{.service.serviceName}}/mTLS",
4
  "secret_validation_name": "spiffe://{{ .Values.global.spire.trustDomain }}",
5
  "ecdh_curves": [
6
    "X25519:P-256:P-521:P-384"
7
  ]
8
}
Copied!
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. The secret_key specifies the name of the secret to fetch. secret_name should be the SPIFFE Id of your certificate. secret_validation_name will set the validation context for the sds secret config.
Envoy Reference
​Envoy Cluster Reference​
Fields
cluster_key
A unique key used to identify this particular cluster configuration. This key is used in routes or 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 from service discovery or wether they will be manually inserted.
To use service discovery, the name field should match the announced XDS_CLUSTER of another service running in the mesh. If no match is found, from the service not yet being online or a incorrect spelling, the instance array will remain empty. If a match is found, then the discovered instances will be populated in the array. More information can be found in the service discovery pages.
To specify instances manually, with no service discovery, the name field must be set to a value that does not match an announced service. If a match is found, the manually inserted instances will be overridden.
require_tls
If true, this cluster will only accept HTTPS connections. In this case, one of the secret or ssl_config 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 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 field.
circuit_breakers
Default and high priority circuit breakers​
outlier_detection
​outlier detection​
health_checks
Array of health checks.
lb_policy
Defaults to least_request, supported options are: round_robin, least_request, ring_hash, random, maglev, and cluster_provided. Both the least_request and ring_hash options require additional configuration in the least_request_lb_config field and ring_hash_lb_config field respectively.
​Envoy Load Balancing Policy.
http2_protocol_options
Options for configuring HTTP/2. Setting this field indicates that the cluster supports HTTP/2, and must be set in order to upgrade connections to HTTP/2.
​Envoy HTTP/2 Options.
ring_hash_lb_config
Specific configuration for the RingHash load balancing policy. Must be set if the lb_policy field is set to ring_hash.
​Envoy RingHash Load Balancing Policy​
original_dst_lb_config
This is a special purpose load balancer that can only be used with an original destination cluster. No other load balancing policy can be used with original destination clusters.
​Envoy Original Destination Load Balancing Policy​
least_request_lb_config
Specific configuration for the LeastRequest load balancing policy. Must be set if the lb_policy field is set to least_request.
​Envoy LeastRequest Load Balancing Policy​
common_lb_config
Common configuration for all load balancer implementations.
​Envoy Common Load Balancer Configuration​
checksum
An API calculated checksum. Can be used to verify that the API contains the expected object before performing a write.