Create Or Update Upstream
PUT {{gateway}}/upstreams/:upstreamNameOrId
Create Or Update Upstream konghq
Inserts (or replaces) the Upstream under the requested resource with the definition specified in the body. The Upstream will be identified via the name or id attribute.
When the name or id attribute has the structure of a UUID, the Upstream being inserted/replaced will be identified by its id. Otherwise it will be identified by its name.
When creating a new Upstream without specifying id (neither in the URL nor in the body), then it will be auto-generated.
Notice that specifying a name in the URL and a different one in the request body is not allowed.
| Attributes | Mandatory | Type | Description |
|---|---|---|---|
| upstream name or id | required | path | The unique identifier or the name of the Upstream to create or update. |
Request Body
| Attributes | Mandatory | Type | Description |
|---|---|---|---|
| name | required | body | This is a hostname, which must be equal to the host of a Service. |
| algorithm | optional | body | Which load balancing algorithm to use. Accepted values are: "consistent-hashing", "least-connections", "round-robin". Defaults to "round-robin". |
| hash_on | optional | body | What to use as hashing input. Using none results in a weighted-round-robin scheme with no hashing. Accepted values are: "none", "consumer", "ip", "header", "cookie". Defaults to "none". |
| hash_fallback | optional | body | 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. Accepted values are: "none", "consumer", "ip", "header", "cookie". Defaults to "none". |
| hash_on_header | semi-optional | body | The header name to take the value from as hash input. Only required when hash_on is set to header. |
| hash_fallback_header | semi-optional | body | The header name to take the value from as hash input. Only required when hash_fallback is set to header. |
| hash_on_cookie | semi-optional | body | 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_path | semi-optional | body | The cookie path to set in the response headers. Only required when hash_on or hash_fallback is set to cookie. Defaults to "/". |
| slots | optional | body | The number of slots in the loadbalancer algorithm (10-65536). Defaults to 10000. |
| healthchecks.active.https_verify_certificate | optional | body | Whether to check the validity of the SSL certificate of the remote host when performing active health checks using HTTPS. Defaults to true. |
| healthchecks.active.unhealthy.http_statuses | optional | body | An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks. Defaults to [429, 404, 500, 501, 502, 503, 504, 505]. With form-encoded, the notation is http_statuses[]=429&http_statuses[]=404. With JSON, use an Array. |
| healthchecks.active.unhealthy.tcp_failures | optional | body | Number of TCP failures in active probes to consider a target unhealthy. Defaults to 0. |
| healthchecks.active.unhealthy.timeouts | optional | body | Number of timeouts in active probes to consider a target unhealthy. Defaults to 0. |
| healthchecks.active.unhealthy.http_failures | optional | body | Number of HTTP failures in active probes (as defined by healthchecks.active.unhealthy.http_statuses) to consider a target unhealthy. Defaults to 0. |
| healthchecks.active.unhealthy.interval | optional | body | Interval between active health checks for unhealthy targets (in seconds). A value of zero indicates that active probes for unhealthy targets should not be performed. Defaults to 0. |
| healthchecks.active.http_path | optional | body | Path to use in GET HTTP request to run as a probe on active health checks. Defaults to "/". |
| healthchecks.active.timeout | optional | body | Socket timeout for active health checks (in seconds). Defaults to 1. |
| healthchecks.active.healthy.http_statuses | optional | body | An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks. Defaults to [200, 302]. With form-encoded, the notation is http_statuses[]=200&http_statuses[]=302. With JSON, use an Array. |
| healthchecks.active.healthy.interval | optional | body | Interval between active health checks for healthy targets (in seconds). A value of zero indicates that active probes for healthy targets should not be performed. Defaults to 0. |
| healthchecks.active.healthy.successes | optional | body | Number of successes in active probes (as defined by healthchecks.active.healthy.http_statuses) to consider a target healthy. Defaults to 0. |
| healthchecks.active.https_sni | optional | body | The hostname to use as an SNI (Server Name Identification) when performing active health checks using HTTPS. This is particularly useful when Targets are configured using IPs, so that the target host’s certificate can be verified with the proper SNI. |
| healthchecks.active.concurrency | optional | body | Number of targets to check concurrently in active health checks. Defaults to 10. |
| healthchecks.active.type | optional | body | Whether to perform active health checks using HTTP or HTTPS, or just attempt a TCP connection. Accepted values are: "tcp", "http", "https", "grpc", "grpcs". Defaults to "http". |
| healthchecks.passive.unhealthy.http_failures | optional | body | Number of HTTP failures in proxied traffic (as defined by healthchecks.passive.unhealthy.http_statuses) to consider a target unhealthy, as observed by passive health checks. Defaults to 0. |
| healthchecks.passive.unhealthy.http_statuses | optional | body | An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks. Defaults to [429, 500, 503]. With form-encoded, the notation is http_statuses[]=429&http_statuses[]=500. With JSON, use an Array. |
| healthchecks.passive.unhealthy.tcp_failures | optional | body | Number of TCP failures in proxied traffic to consider a target unhealthy, as observed by passive health checks. Defaults to 0. |
| healthchecks.passive.unhealthy.timeouts | optional | body | Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks. Defaults to 0. |
| healthchecks.passive.type | optional | body | Whether to perform passive health checks interpreting HTTP/HTTPS statuses, or just check for TCP connection success. In passive checks, http and https options are equivalent. Accepted values are: "tcp", "http", "https", "grpc", "grpcs". Defaults to "http". |
| healthchecks.passive.healthy.successes | optional | body | Number of successes in proxied traffic (as defined by healthchecks.passive.healthy.http_statuses) to consider a target healthy, as observed by passive health checks. Defaults to 0. |
| healthchecks.passive.healthy.http_statuses | optional | body | An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks. Defaults to [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]. With form-encoded, the notation is http_statuses[]=200&http_statuses[]=201. With JSON, use an Array. |
| healthchecks.threshold | optional | body | The minimum percentage of the upstream’s targets’ weight that must be available for the whole upstream to be considered healthy. Defaults to 0. |
| tags | optional | body | An optional set of strings associated with the Upstream, for grouping and filtering. |
| host_header | optional | body | The hostname to be used as Host header when proxying requests through Kong. |
Request Body
{"hash_on"=>"none", "algorithm"=>"round-robin", "name"=>"my-upstream", "tags"=>["user-level", "low-priority"], "hash_fallback_header"=>nil, "hash_fallback"=>"none", "hash_on_cookie"=>nil, "host_header"=>"example.com", "hash_on_cookie_path"=>"/", "healthchecks"=>{"threshold"=>0, "active"=>{"unhealthy"=>{"http_statuses"=>[429, 404, 500, 501, 502, 503, 504, 505], "tcp_failures"=>0, "timeouts"=>0, "http_failures"=>0, "interval"=>0}, "type"=>"http", "http_path"=>"/", "timeout"=>1, "healthy"=>{"successes"=>0, "interval"=>0, "http_statuses"=>[200, 302]}, "https_sni"=>"example.com", "https_verify_certificate"=>true, "concurrency"=>10}, "passive"=>{"unhealthy"=>{"http_failures"=>0, "http_statuses"=>[429, 500, 503], "tcp_failures"=>0, "timeouts"=>0}, "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"}}, "hash_on_header"=>nil, "slots"=>10000}
HEADERS
| Key | Datatype | Required | Description |
|---|---|---|---|
Content-Type | string |