List all Upstreams

List all registered upstreams. You can filter the results by pagination size, offset, or tags like /upstreams?size=10&offset=0.

get

Query Parameters

sizeinteger

Number of resources to be returned.

Default:100

>= 1<= 1000

offsetstring

Offset from which to return the next set of resources. Use the value of the ‘offset’ field from the response of a list operation as input here to paginate through all the resources

tagsstring

A list of tags to filter the list of resources on. Multiple tags can be concatenated using ‘,’ to mean AND or using ‘/’ to mean OR.

Example:tag1,tag2

Path Parameters

runtimeGroupIdstringrequired

The ID of your runtime group. This variable is available in the Konnect manager

Example:9524ec7d-36d9-465d-a8c5-83a3c9390458

Response

200 application/json

A successful response listing Upstreams

dataarray[object]

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.

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}

Show Child Parameters
offsetstring

Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page

get/runtime-groups/{runtimeGroupId}/core-entities/upstreams
 
200 application/json

Create a new Upstream

Create a new Upstream

post

Path Parameters

runtimeGroupIdstringrequired

The ID of your runtime group. This variable is available in the Konnect manager

Example:9524ec7d-36d9-465d-a8c5-83a3c9390458

Body

application/json
namestringrequired

This is a hostname, which must be equal to the host of a service.

Example:my-upstream

algorithmstring

Which load balancing algorithm to use. Accepted values are: consistent-hashing, least-connections, round-robin. Default: round-robin.

Allowed values:consistent-hashingleast-connectionsround-robin

Default:round-robin

Example:round-robin

hash_onstring

What to use as hashing input. Using none results in a weighted-round-robin scheme with no hashing

Allowed values:noneconsumeripcookieuri_capturepathquery_arg

Default:none

hash_fallbackstring

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.

Allowed values:noneconsumeripcookieuri_capturepathquery_arg

Default:none

Example:none

hash_on_headerstring

The header name to take the value from as hash input. Only required when hash_on is set to header.

Example:none

hash_fallback_headerstring

The header name to take the value from as hash input. Only required when hash_fallback is set to header.

Default:none

Example:none

hash_on_cookiestring

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.

Example:none

hash_on_cookie_pathstring

The cookie path to set in the response headers. Only required when hash_on or hash_fallback is set to cookie. Default: /.

Default:/

Example:/

hash_on_query_argstring

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.

Example:hash_value

hash_fallback_query_argstring

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.

Example:hash_value

hash_on_uri_capturestring

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.

Example:hash_value

hash_fallback_uri_capturestring

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.

Example:hash_value

slotsinteger

The number of slots in the load balancer algorithm. If the algorithm is set to round-robin, this setting determines the maximum number of slots. If the 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.

Default:10000

>= 10<= 65536

Example:5000

healthchecksobject
Show Child Parameters
tagsarray[string]

An optional set of strings associated with the Upstream for grouping and filtering.

Example:["user-level","low-priority"]

host_headerstring

The hostname to be used as Host header when proxying requests through Kong.

client_certificateobject

If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.

Show Child Parameters

Response

application/json

Successfully created Upstream

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.

algorithmstring

Which load balancing algorithm to use.

Default:round-robin

client_certificateobject

If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.

* Additional properties are NOT allowed.
Show Child Parameters
created_atinteger

Unix epoch when the resource was created.

Example:1422386534

updated_atinteger

Unix epoch when the resouce was updated.

Example:1422386534

hash_fallbackstring

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.

Default:none

hash_fallback_headerstring

The header name to take the value from as hash input. Only required when hash_fallback is set to header.

hash_fallback_query_argstring

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_capturestring

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_onstring

What to use as hashing input. Using none results in a weighted-round-robin scheme with no hashing.

Default:none

hash_on_cookiestring

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.

hash_on_cookie_pathstring

The cookie path to set in the response headers. Only required when hash_on or hash_fallback is set to cookie.

Default:/

hash_on_headerstring

The header name to take the value from as hash input. Only required when hash_on is set to header.

hash_on_query_argstring

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_capturestring

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.

healthchecksobject
Show Child Parameters
host_headerstring

The hostname to be used as Host header when proxying requests through Kong.

idstring
namestring

This is a hostname, which must be equal to the host of a service.

slotsinteger

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.

Default:10000

tagsarray[string]

An optional set of strings associated with the Upstream for grouping and filtering.

use_srv_nameboolean

If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream Host.

Default:false

post/runtime-groups/{runtimeGroupId}/core-entities/upstreams

Body

{ "name": "my-upstream", "algorithm": "round-robin", "hash_on": "none", "hash_fallback": "none", "hash_on_cookie_path": "/", "slots": 10000, "healthchecks": { "passive": { "type": "http", "healthy": { "http_statuses": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "successes": 0 }, "unhealthy": { "http_statuses": [ 429, 500, 503 ], "timeouts": 0, "http_failures": 0, "tcp_failures": 0 } }, "active": { "https_verify_certificate": true, "healthy": { "http_statuses": [ 200, 302 ], "successes": 0, "interval": 0 }, "unhealthy": { "http_failures": 0, "http_statuses": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "timeouts": 0, "tcp_failures": 0, "interval": 0 }, "type": "http", "concurrency": 10, "headers": { "type": "object", "properties": { "x-my-header": { "description": "The value(s) of the x-my-header header.", "type": "array", "items": { "type": "string" } }, "x-another-header": { "description": "The value(s) of the x-another-header header.", "type": "array", "items": { "type": "string" } } } }, "timeout": 1, "http_path": "/", "https_sni": "example.com" }, "threshold": 0 }, "tags": [ "user-level", "low-priority" ], "host_header": "example.com", "client_certificate": { "id": "ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6" }, "use_srv_name": false }
 
application/json

Delete an Upstream

Delete an Upstream

delete

Path Parameters

upstream_idstringrequired

The unique identifier of the Upstream associated to the Certificate to be retrieved.

Example:7fca84d6-7d37-4a74-a7b0-93e576089a41

runtimeGroupIdstringrequired

The ID of your runtime group. This variable is available in the Konnect manager

Example:9524ec7d-36d9-465d-a8c5-83a3c9390458

Response

204

Successfully deleted Upstream or the resource didn’t exist

delete/runtime-groups/{runtimeGroupId}/core-entities/upstreams/{upstream_id}
 
204

Get an Upstream

Get an Upstream using ID or name.

get

Query Parameters

offsetstring

Offset from which to return the next set of resources. Use the value of the ‘offset’ field from the response of a list operation as input here to paginate through all the resources

sizeinteger

Number of resources to be returned.

Default:100

>= 1<= 1000

tagsstring

A list of tags to filter the list of resources on. Multiple tags can be concatenated using ‘,’ to mean AND or using ‘/’ to mean OR.

Example:tag1,tag2

Path Parameters

upstream_idstringrequired

The unique identifier of the Upstream associated to the Certificate to be retrieved.

Example:7fca84d6-7d37-4a74-a7b0-93e576089a41

runtimeGroupIdstringrequired

The ID of your runtime group. This variable is available in the Konnect manager

Example:9524ec7d-36d9-465d-a8c5-83a3c9390458

Response

application/json

Successfully fetched Upstream

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.

algorithmstring

Which load balancing algorithm to use.

Default:round-robin

client_certificateobject

If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.

* Additional properties are NOT allowed.
Show Child Parameters
created_atinteger

Unix epoch when the resource was created.

Example:1422386534

updated_atinteger

Unix epoch when the resouce was updated.

Example:1422386534

hash_fallbackstring

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.

Default:none

hash_fallback_headerstring

The header name to take the value from as hash input. Only required when hash_fallback is set to header.

hash_fallback_query_argstring

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_capturestring

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_onstring

What to use as hashing input. Using none results in a weighted-round-robin scheme with no hashing.

Default:none

hash_on_cookiestring

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.

hash_on_cookie_pathstring

The cookie path to set in the response headers. Only required when hash_on or hash_fallback is set to cookie.

Default:/

hash_on_headerstring

The header name to take the value from as hash input. Only required when hash_on is set to header.

hash_on_query_argstring

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_capturestring

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.

healthchecksobject
Show Child Parameters
host_headerstring

The hostname to be used as Host header when proxying requests through Kong.

idstring
namestring

This is a hostname, which must be equal to the host of a service.

slotsinteger

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.

Default:10000

tagsarray[string]

An optional set of strings associated with the Upstream for grouping and filtering.

use_srv_nameboolean

If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream Host.

Default:false

get/runtime-groups/{runtimeGroupId}/core-entities/upstreams/{upstream_id}
 
application/json

Update an Upstream

Create or Update Upstream using ID or name.

put

Path Parameters

upstream_idstringrequired

The unique identifier of the Upstream associated to the Certificate to be retrieved.

Example:7fca84d6-7d37-4a74-a7b0-93e576089a41

runtimeGroupIdstringrequired

The ID of your runtime group. This variable is available in the Konnect manager

Example:9524ec7d-36d9-465d-a8c5-83a3c9390458

Body

application/json
namestringrequired

This is a hostname, which must be equal to the host of a service.

Example:my-upstream

algorithmstring

Which load balancing algorithm to use. Accepted values are: consistent-hashing, least-connections, round-robin. Default: round-robin.

Allowed values:consistent-hashingleast-connectionsround-robin

Default:round-robin

Example:round-robin

hash_onstring

What to use as hashing input. Using none results in a weighted-round-robin scheme with no hashing

Allowed values:noneconsumeripcookieuri_capturepathquery_arg

Default:none

hash_fallbackstring

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.

Allowed values:noneconsumeripcookieuri_capturepathquery_arg

Default:none

Example:none

hash_on_headerstring

The header name to take the value from as hash input. Only required when hash_on is set to header.

Example:none

hash_fallback_headerstring

The header name to take the value from as hash input. Only required when hash_fallback is set to header.

Default:none

Example:none

hash_on_cookiestring

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.

Example:none

hash_on_cookie_pathstring

The cookie path to set in the response headers. Only required when hash_on or hash_fallback is set to cookie. Default: /.

Default:/

Example:/

hash_on_query_argstring

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.

Example:hash_value

hash_fallback_query_argstring

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.

Example:hash_value

hash_on_uri_capturestring

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.

Example:hash_value

hash_fallback_uri_capturestring

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.

Example:hash_value

slotsinteger

The number of slots in the load balancer algorithm. If the algorithm is set to round-robin, this setting determines the maximum number of slots. If the 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.

Default:10000

>= 10<= 65536

Example:5000

healthchecksobject
Show Child Parameters
tagsarray[string]

An optional set of strings associated with the Upstream for grouping and filtering.

Example:["user-level","low-priority"]

host_headerstring

The hostname to be used as Host header when proxying requests through Kong.

client_certificateobject

If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.

Show Child Parameters

Response

application/json

Successfully upserted Upstream

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.

algorithmstring

Which load balancing algorithm to use.

Default:round-robin

client_certificateobject

If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.

* Additional properties are NOT allowed.
Show Child Parameters
created_atinteger

Unix epoch when the resource was created.

Example:1422386534

updated_atinteger

Unix epoch when the resouce was updated.

Example:1422386534

hash_fallbackstring

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.

Default:none

hash_fallback_headerstring

The header name to take the value from as hash input. Only required when hash_fallback is set to header.

hash_fallback_query_argstring

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_capturestring

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_onstring

What to use as hashing input. Using none results in a weighted-round-robin scheme with no hashing.

Default:none

hash_on_cookiestring

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.

hash_on_cookie_pathstring

The cookie path to set in the response headers. Only required when hash_on or hash_fallback is set to cookie.

Default:/

hash_on_headerstring

The header name to take the value from as hash input. Only required when hash_on is set to header.

hash_on_query_argstring

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_capturestring

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.

healthchecksobject
Show Child Parameters
host_headerstring

The hostname to be used as Host header when proxying requests through Kong.

idstring
namestring

This is a hostname, which must be equal to the host of a service.

slotsinteger

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.

Default:10000

tagsarray[string]

An optional set of strings associated with the Upstream for grouping and filtering.

use_srv_nameboolean

If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream Host.

Default:false

put/runtime-groups/{runtimeGroupId}/core-entities/upstreams/{upstream_id}

Body

{ "name": "my-upstream", "algorithm": "round-robin", "hash_on": "none", "hash_fallback": "none", "hash_on_cookie_path": "/", "slots": 10000, "healthchecks": { "passive": { "type": "http", "healthy": { "http_statuses": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "successes": 0 }, "unhealthy": { "http_statuses": [ 429, 500, 503 ], "timeouts": 0, "http_failures": 0, "tcp_failures": 0 } }, "active": { "https_verify_certificate": true, "healthy": { "http_statuses": [ 200, 302 ], "successes": 0, "interval": 0 }, "unhealthy": { "http_failures": 0, "http_statuses": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "timeouts": 0, "tcp_failures": 0, "interval": 0 }, "type": "http", "concurrency": 10, "headers": { "type": "object", "properties": { "x-my-header": { "description": "The value(s) of the x-my-header header.", "type": "array", "items": { "type": "string" } }, "x-another-header": { "description": "The value(s) of the x-another-header header.", "type": "array", "items": { "type": "string" } } } }, "timeout": 1, "http_path": "/", "https_sni": "example.com" }, "threshold": 0 }, "tags": [ "user-level", "low-priority" ], "host_header": "example.com", "client_certificate": { "id": "ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6" }, "use_srv_name": false }
 
application/json