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

Example Object

{
    "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:

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

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

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

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

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

Envoy Load Balancing Policy.

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.