Kong · Schema
Upstream
The upstream object represents a virtual hostname and can be used to loadbalance incoming requests over multiple services (targets). So for example an upstream named `service.v1.xyz` for a Service object whose `host` is `service.v1.xyz`. Requests for this Service would be proxied to the targets defined within the upstream. An upstream also includes a [health checker][healthchecks], which is able to enable and disable targets based on their ability or inability to serve requests. The configuration for the health checker is stored in the upstream object, and applies to all of its targets.
API GatewayAI GatewayAI ConnectivityAgent GatewayEvent GatewayMCP RegistryService MeshLLMKafkaKonnectOpen Source
Properties
| Name | Type | Description |
|---|---|---|
| algorithm | string | Which load balancing algorithm to use. |
| client_certificate | object | If set, the certificate to be used as client certificate while TLS handshaking to the upstream server. |
| created_at | integer | Unix epoch when the resource was created. |
| hash_fallback | string | What to use as hashing input if the primary `hash_on` does not return a hash (eg. header is missing, or no Consumer identified). Not available if `hash_on` is set to `cookie`. |
| hash_fallback_header | string | The header name to take the value from as hash input. Only required when `hash_fallback` is set to `header`. |
| hash_fallback_query_arg | string | The name of the query string argument to take the value from as hash input. Only required when `hash_fallback` is set to `query_arg`. |
| hash_fallback_uri_capture | string | The name of the route URI capture to take the value from as hash input. Only required when `hash_fallback` is set to `uri_capture`. |
| hash_on | string | What to use as hashing input. Using `none` results in a weighted-round-robin scheme with no hashing. |
| hash_on_cookie | string | The cookie name to take the value from as hash input. Only required when `hash_on` or `hash_fallback` is set to `cookie`. If the specified cookie is not in the request, Kong will generate a value and |
| hash_on_cookie_path | string | The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`. |
| hash_on_header | string | The header name to take the value from as hash input. Only required when `hash_on` is set to `header`. |
| hash_on_query_arg | string | The name of the query string argument to take the value from as hash input. Only required when `hash_on` is set to `query_arg`. |
| hash_on_uri_capture | string | The name of the route URI capture to take the value from as hash input. Only required when `hash_on` is set to `uri_capture`. |
| healthchecks | object | The array of healthchecks. |
| host_header | string | The hostname to be used as `Host` header when proxying requests through Kong. |
| id | string | A string representing a UUID (universally unique identifier). |
| name | string | This is a hostname, which must be equal to the `host` of a Service. |
| slots | integer | The number of slots in the load balancer algorithm. If `algorithm` is set to `round-robin`, this setting determines the maximum number of slots. If `algorithm` is set to `consistent-hashing`, this set |
| sticky_sessions_cookie | string | The cookie name to keep sticky sessions. |
| sticky_sessions_cookie_path | string | A string representing a URL path, such as /path/to/resource. Must start with a forward slash (/) and must not contain empty segments (i.e., two consecutive forward slashes). |
| tags | array | An optional set of strings associated with the Upstream for grouping and filtering. |
| updated_at | integer | Unix epoch when the resource was last updated. |
| use_srv_name | boolean | If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream `Host`. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "#/components/schemas/Upstream",
"title": "Upstream",
"x-speakeasy-entity": "Upstream",
"description": "The upstream object represents a virtual hostname and can be used to loadbalance incoming requests over multiple services (targets). So for example an upstream named `service.v1.xyz` for a Service object whose `host` is `service.v1.xyz`. Requests for this Service would be proxied to the targets defined within the upstream. An upstream also includes a [health checker][healthchecks], which is able to enable and disable targets based on their ability or inability to serve requests. The configuration for the health checker is stored in the upstream object, and applies to all of its targets.",
"type": "object",
"properties": {
"algorithm": {
"description": "Which load balancing algorithm to use.",
"type": "string",
"default": "round-robin",
"enum": [
"consistent-hashing",
"latency",
"least-connections",
"round-robin",
"sticky-sessions"
],
"nullable": true
},
"client_certificate": {
"description": "If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.",
"type": "object",
"nullable": true,
"properties": {
"id": {
"type": "string"
}
},
"x-foreign": true
},
"created_at": {
"description": "Unix epoch when the resource was created.",
"type": "integer",
"nullable": true
},
"hash_fallback": {
"description": "What to use as hashing input if the primary `hash_on` does not return a hash (eg. header is missing, or no Consumer identified). Not available if `hash_on` is set to `cookie`.",
"type": "string",
"default": "none",
"enum": [
"consumer",
"cookie",
"header",
"ip",
"none",
"path",
"query_arg",
"uri_capture"
],
"nullable": true
},
"hash_fallback_header": {
"description": "The header name to take the value from as hash input. Only required when `hash_fallback` is set to `header`.",
"type": "string",
"nullable": true
},
"hash_fallback_query_arg": {
"description": "The name of the query string argument to take the value from as hash input. Only required when `hash_fallback` is set to `query_arg`.",
"type": "string",
"minLength": 1,
"nullable": true
},
"hash_fallback_uri_capture": {
"description": "The name of the route URI capture to take the value from as hash input. Only required when `hash_fallback` is set to `uri_capture`.",
"type": "string",
"minLength": 1,
"nullable": true
},
"hash_on": {
"description": "What to use as hashing input. Using `none` results in a weighted-round-robin scheme with no hashing.",
"type": "string",
"default": "none",
"enum": [
"consumer",
"cookie",
"header",
"ip",
"none",
"path",
"query_arg",
"uri_capture"
],
"nullable": true
},
"hash_on_cookie": {
"description": "The cookie name to take the value from as hash input. Only required when `hash_on` or `hash_fallback` is set to `cookie`. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response.",
"type": "string",
"nullable": true
},
"hash_on_cookie_path": {
"description": "The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`.",
"type": "string",
"default": "/",
"nullable": true
},
"hash_on_header": {
"description": "The header name to take the value from as hash input. Only required when `hash_on` is set to `header`.",
"type": "string",
"nullable": true
},
"hash_on_query_arg": {
"description": "The name of the query string argument to take the value from as hash input. Only required when `hash_on` is set to `query_arg`.",
"type": "string",
"minLength": 1,
"nullable": true
},
"hash_on_uri_capture": {
"description": "The name of the route URI capture to take the value from as hash input. Only required when `hash_on` is set to `uri_capture`.",
"type": "string",
"minLength": 1,
"nullable": true
},
"healthchecks": {
"description": "The array of healthchecks.",
"type": "object",
"default": {
"active": {
"concurrency": 10,
"healthy": {
"http_statuses": [
200,
302
],
"interval": 0,
"successes": 0
},
"http_path": "/",
"https_verify_certificate": true,
"timeout": 1,
"type": "http",
"unhealthy": {
"http_failures": 0,
"http_statuses": [
429,
404,
500,
501,
502,
503,
504,
505
],
"interval": 0,
"tcp_failures": 0,
"timeouts": 0
}
},
"passive": {
"healthy": {
"http_statuses": [
200,
201,
202,
203,
204,
205,
206,
207,
208,
226,
300,
301,
302,
303,
304,
305,
306,
307,
308
],
"successes": 0
},
"type": "http",
"unhealthy": {
"http_failures": 0,
"http_statuses": [
429,
500,
503
],
"tcp_failures": 0,
"timeouts": 0
}
}
},
"nullable": true,
"properties": {
"active": {
"type": "object",
"default": {
"concurrency": 10,
"healthy": {
"http_statuses": [
200,
302
],
"interval": 0,
"successes": 0
},
"http_path": "/",
"https_verify_certificate": true,
"timeout": 1,
"type": "http",
"unhealthy": {
"http_failures": 0,
"http_statuses": [
429,
404,
500,
501,
502,
503,
504,
505
],
"interval": 0,
"tcp_failures": 0,
"timeouts": 0
}
},
"properties": {
"concurrency": {
"type": "integer",
"default": 10,
"maximum": 2147483648,
"minimum": 1
},
"headers": {
"description": "A map of header names to arrays of header values.",
"type": "object",
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
}
},
"healthy": {
"type": "object",
"default": {
"http_statuses": [
200,
302
],
"interval": 0,
"successes": 0
},
"properties": {
"http_statuses": {
"type": "array",
"items": {
"maximum": 999,
"minimum": 100,
"type": "integer"
},
"default": [
200,
302
]
},
"interval": {
"type": "number",
"default": 0,
"maximum": 65535,
"minimum": 0
},
"successes": {
"type": "integer",
"default": 0,
"maximum": 255,
"minimum": 0
}
}
},
"http_path": {
"description": "A string representing a URL path, such as /path/to/resource. Must start with a forward slash (/) and must not contain empty segments (i.e., two consecutive forward slashes).",
"type": "string",
"default": "/"
},
"https_sni": {
"description": "A string representing an SNI (server name indication) value for TLS.",
"type": "string"
},
"https_verify_certificate": {
"type": "boolean",
"default": true
},
"timeout": {
"type": "number",
"default": 1,
"maximum": 65535,
"minimum": 0
},
"type": {
"type": "string",
"default": "http",
"enum": [
"grpc",
"grpcs",
"http",
"https",
"tcp"
]
},
"unhealthy": {
"type": "object",
"default": {
"http_failures": 0,
"http_statuses": [
429,
404,
500,
501,
502,
503,
504,
505
],
"interval": 0,
"tcp_failures": 0,
"timeouts": 0
},
"properties": {
"http_failures": {
"type": "integer",
"default": 0,
"maximum": 255,
"minimum": 0
},
"http_statuses": {
"type": "array",
"items": {
"maximum": 999,
"minimum": 100,
"type": "integer"
},
"default": [
429,
404,
500,
501,
502,
503,
504,
505
]
},
"interval": {
"type": "number",
"default": 0,
"maximum": 65535,
"minimum": 0
},
"tcp_failures": {
"type": "integer",
"default": 0,
"maximum": 255,
"minimum": 0
},
"timeouts": {
"type": "integer",
"default": 0,
"maximum": 255,
"minimum": 0
}
}
}
}
},
"passive": {
"type": "object",
"default": {
"healthy": {
"http_statuses": [
200,
201,
202,
203,
204,
205,
206,
207,
208,
226,
300,
301,
302,
303,
304,
305,
306,
307,
308
],
"successes": 0
},
"type": "http",
"unhealthy": {
"http_failures": 0,
"http_statuses": [
429,
500,
503
],
"tcp_failures": 0,
"timeouts": 0
}
},
"properties": {
"healthy": {
"type": "object",
"default": {
"http_statuses": [
200,
201,
202,
203,
204,
205,
206,
207,
208,
226,
300,
301,
302,
303,
304,
305,
306,
307,
308
],
"successes": 0
},
"properties": {
"http_statuses": {
"type": "array",
"items": {
"maximum": 999,
"minimum": 100,
"type": "integer"
},
"default": [
200,
201,
202,
203,
204,
205,
206,
207,
208,
226,
300,
301,
302,
303,
304,
305,
306,
307,
308
]
},
"successes": {
"type": "integer",
"default": 0,
"maximum": 255,
"minimum": 0
}
}
},
"type": {
"type": "string",
"default": "http",
"enum": [
"grpc",
"grpcs",
"http",
"https",
"tcp"
]
},
"unhealthy": {
"type": "object",
"default": {
"http_failures": 0,
"http_statuses": [
429,
500,
503
],
"tcp_failures": 0,
"timeouts": 0
},
"properties": {
"http_failures": {
"type": "integer",
"default": 0,
"maximum": 255,
"minimum": 0
},
"http_statuses": {
"type": "array",
"items": {
"maximum": 999,
"minimum": 100,
"type": "integer"
},
"default": [
429,
500,
503
]
},
"tcp_failures": {
"type": "integer",
"default": 0,
"maximum": 255,
"minimum": 0
},
"timeouts": {
"type": "integer",
"default": 0,
"maximum": 255,
"minimum": 0
}
}
}
}
},
"threshold": {
"type": "number",
"default": 0,
"maximum": 100,
"minimum": 0
}
}
},
"host_header": {
"description": "The hostname to be used as `Host` header when proxying requests through Kong.",
"type": "string",
"nullable": true
},
"id": {
"description": "A string representing a UUID (universally unique identifier).",
"type": "string",
"nullable": true
},
"name": {
"description": "This is a hostname, which must be equal to the `host` of a Service.",
"type": "string"
},
"slots": {
"description": "The number of slots in the load balancer algorithm. If `algorithm` is set to `round-robin`, this setting determines the maximum number of slots. If `algorithm` is set to `consistent-hashing`, this setting determines the actual number of slots in the algorithm. Accepts an integer in the range `10`-`65536`.",
"type": "integer",
"default": 10000,
"maximum": 65536,
"minimum": 10,
"nullable": true
},
"sticky_sessions_cookie": {
"description": "The cookie name to keep sticky sessions.",
"type": "string",
"nullable": true
},
"sticky_sessions_cookie_path": {
"description": "A string representing a URL path, such as /path/to/resource. Must start with a forward slash (/) and must not contain empty segments (i.e., two consecutive forward slashes).",
"type": "string",
"default": "/",
"nullable": true
},
"tags": {
"description": "An optional set of strings associated with the Upstream for grouping and filtering.",
"type": "array",
"items": {
"description": "A string representing a tag.",
"type": "string"
},
"nullable": true
},
"updated_at": {
"description": "Unix epoch when the resource was last updated.",
"type": "integer",
"nullable": true
},
"use_srv_name": {
"description": "If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream `Host`.",
"type": "boolean",
"default": false,
"nullable": true
}
},
"example": {
"algorithm": "round-robin",
"hash_fallback": "none",
"hash_on": "none",
"hash_on_cookie_path": "/",
"healthchecks": {
"active": {
"concurrency": 10,
"healthy": {
"http_statuses": [
200,
302
],
"interval": 0,
"successes": 0
},
"http_path": "/",
"https_verify_certificate": true,
"timeout": 1,
"type": "http",
"unhealthy": {
"http_failures": 0,
"http_statuses": [
429,
404,
500,
501,
502,
503,
504,
505
],
"interval": 0,
"tcp_failures": 0,
"timeouts": 0
}
},
"passive": {
"healthy": {
"http_statuses": [
200,
201,
202,
203,
204,
205,
206,
207,
208,
226,
300,
301,
302,
303,
304,
305,
306,
307,
308
],
"successes": 0
},
"type": "http",
"unhealthy": {
"http_failures": 0,
"http_statuses": [
429,
500,
503
],
"tcp_failures": 0,
"timeouts": 0
}
},
"threshold": 0
},
"id": "6eed5e9c-5398-4026-9a4c-d48f18a2431e",
"name": "api.example.internal",
"slots": 10000
},
"additionalProperties": false,
"required": [
"name"
]
}