--- title: "get cluster" method: GET path: "/cluster/{clusterKey}" tags: ["Cluster"] --- # get cluster `GET /cluster/{clusterKey}` Get details for an existing cluster ## Path parameters - `clusterKey` string, required ## Response `200` a result containing a single cluster - ClusterResult - `result` Cluster - `zone_key` string, required - `name` string, required - `require_tls` boolean — If set, requests to this collection of hosts will be made via HTTPS. At this time neither certificate validation and certificate pinning are supported for proxy clients of this cluster. - `instances` Instance[] - `host` string - `port` integer - `metadata` Metadatum[] - `key` string - `value` string - `circuit_breakers` CircuitBreakers — Provides limits on various parameters to protect clusters against sudden surges in traffic. - `max_connections` integer — Maximum number of connections that will be established to all instances in a cluster within a proxy. If set to 0, no new connections will be created. If not specified, defaults to 1024. - `max_pending_requests` integer — Maximum number of requests that will be queued while waiting on a connection pool to a cluster within a proxy. If set to 0, no requests will be queued. If not specified, defaults to 1024. - `max_retries` integer — Maximum number of retries that can be outstanding to all instances in a cluster within a proxy. If set to 0, requests will not be retried. If not specified, defaults to 3. - `max_requests` integer — Maximum number of requests that can be outstanding to all instances in a cluster within a proxy. Only applicable to HTTP/2 traffic since HTTP/1.1 clusters are governed by the maximum connections circuit breaker. If set to 0, no requests will be made. If not specified, defaults to 1024. - `outlier_detection` OutlierDetection — A form of passive health checking that dynamically determines whether instances in a cluster are performing unlike others and preemptively removes them from a load balancing set. - `interval_msec` integer — The time interval between ejection analysis sweeps. This can result in both new ejections due to success rate outlier detection as well as hosts being returned to service. Defaults to 10s and must be greater than 0. - `base_ejection_time_msec` integer — The base time that a host is ejected for. The real time is equal to the base time multiplied by the number of times the host has been ejected. Defaults to 30s. Setting this to 0 means that no host will be ejected for longer than `interval_msec`. - `max_ejection_percent` integer — The maximum % of an upstream cluster that can be ejected due to outlier detection. Defaults to 10% but will always eject at least one host. - `consecutive_5xx` integer — The number of consecutive 5xx responses before a consecutive 5xx ejection occurs. Defaults to 5. Setting this to 0 effectively turns off the consecutive 5xx detector. - `enforcing_consecutive_5xx` integer — The % chance that a host will be actually ejected when an outlier status is detected through consecutive 5xx. This setting can be used to disable ejection or to ramp it up slowly. Defaults to 100. - `enforcing_success_rate` integer — The % chance that a host will be actually ejected when an outlier status is detected through success rate statistics. This setting can be used to disable ejection or to ramp it up slowly. Defaults to 100. - `success_rate_minimum_hosts` integer — The number of hosts in a cluster that must have enough request volume to detect success rate outliers. If the number of hosts is less than this setting, outlier detection via success rate statistics is not performed for any host in the cluster. Defaults to 5. Setting this to 0 effectively triggers the success rate detector regardless of the number of valid hosts during an interval (as determined by `success_rate_request_volume`). - `success_rate_request_volume` integer — The minimum number of total requests that must be collected in one interval (as defined by interval_msec) to include this host in success rate based outlier detection. If the volume is lower than this setting, outlier detection via success rate statistics is not performed for that host. Defaults to 100. Must be greater than 0. - `success_rate_stdev_factor` integer — This factor is used to determine the ejection threshold for success rate outlier ejection. The ejection threshold is the difference between the mean success rate, and the product of this factor and the standard deviation of the mean success rate: mean - (stdev * success_rate_stdev_factor). This factor is divided by a thousand to get a double. That is, if the desired factor is 1.9, the runtime value should be 1900. Defaults to 1900. Setting this to 0 effectively turns off the success rate detector. - `consecutive_gateway_failure` integer — The number of consecutive gateway failures (502, 503, 504 status or connection errors that are mapped to one of those status codes) before a consecutive gateway failure ejection occurs. Defaults to 5. Setting this to 0 effectively turns off the consecutive gateway failure detector. - `enforcing_consecutive_gateway_failure` integer — The % chance that a host will be actually ejected when an outlier status is detected through consecutive gateway failures. This setting can be used to disable ejection or to ramp it up slowly. Defaults to 0. - `health_checks` HealthCheck[] - `timeout_msec` integer, required — The time to wait for a health check response. If the timeout is reached without a response, the health check attempt will be considered a failure. This is a required field and must be greater than 0. - `interval_msec` integer, required — The interval between health checks. The first round of health checks will occur during startup before any traffic is routed to a cluster. This means that the \'no_traffic_interval_msec\' value will be used as the first interval of health checks. - `interval_jitter_msec` integer — An optional jitter amount that is added to each interval value calculated by the proxy. If not specified, defaults to 0. - `unhealthy_threshold` integer, required — The number of unhealthy health checks required before a host is marked unhealthy. Note that for *http* health checking, if a host responds with 503, this threshold is ignored and the host is considered unhealthy immediately. - `healthy_threshold` integer, required — The number of healthy health checks required before a host is marked healthy. Note that during startup, only a single successful health check is required to mark a host healthy. - `reuse_connection` boolean — Whether or not to reuse health check connections between health checks. Default is true. - `no_traffic_interval_msec` integer — Interval used when a cluster has never had traffic routed to it. It allows cluster information to be kept up to date, without sending a potentially large amount of active health checking traffic for no reason. Once a cluster has been used for traffic routing, The proxy will shift back to using the standard health check interval that is defined. Note that this interval takes precedence over any other. Defaults to 60s. - `unhealthy_interval_msec` integer — Interval used for hosts that are marked as unhealthy. As soon as the host is marked as healthy, The proxy will shift back to using the standard health check interval that is defined. This defaults to the same value as \'interval_msec\' if not specified. - `unhealthy_edge_interval_msec` integer — Interval used for the first health check right after a host is marked as unhealthy. For subsequent health checks, the proxy will shift back to using either \'unhealthy_interval_msec\' if present or the standard health check interval, \'interval_msec\'. - `healthy_edge_interval_msec` integer — Interval used for the first health check right after a host is marked as healthy. For subsequent health checks, the proxy will shift back to using the standard health check interval(\'interval_msec\') that is defined. Defaults to the same value as \'interval_msec\' if not specified. - `health_checker` object, required — Defines the type of health checker to use. Only a single health checker can be defined per HealthCheck. - `http_health_check` HTTPHealthCheck - `host` string — The value of the host header in the HTTP health check request. If left empty, the name of the cluster being health checked will be used. - `path` string — Specifies the HTTP path that will be requested during health checking. - `service_name` string — An optional service name parameter which is used to validate the identity of the health checked cluster. - `request_headers_to_add` Metadatum[] - `key` string - `value` string - `tcp_health_check` TCPHealthCheck - `send` string — Base64 encoded string representing an array of bytes to be sent in health check requests. Leaving this field empty implies a connect-only health check. - `receive` string[] — An array of base64 encoded strings, each representing array of bytes that is expected in health check responses. When checking the response, "fuzzy" matching is performed such that each binary block must be found, and in the order specified, but not necessarily contiguously. - `cluster_key` string, required - `checksum` string, required ## Other responses - `default` — Unexpected error --- [API](https://skmtc.net/turbinelabs/apis/turbine-labs-api.md) · [All operations](https://skmtc.net/turbinelabs/apis/turbine-labs-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/turbinelabs/turbine-labs-api/versions/47fce18aa12f/schema)