Upstreams

Get an Upstream

Changed on

Get an Upstream using ID or name.

get/v2/control-planes/{controlPlaneId}/core-entities/upstreams/{UpstreamId}

Request

  • Base URL: https://global.api.konghq.com
  • URL: https://global.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/upstreams/{UpstreamId}
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer
    • HTTP bearer
    • HTTP bearer

Response

Successfully fetched Upstream

algorithm'consistent-hashing' | 'latency' | 'least-connections' | 'round-robin' | 'sticky-sessions' nullable

Which load balancing algorithm to use.

created_atinteger nullable

Unix epoch when the resource was created.

hash_fallback'consumer' | 'cookie' | 'header' | 'ip' | 'none' | 'path' | 'query_arg' | 'uri_capture' nullable

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_headerstring nullable

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

hash_fallback_query_argstring nullable

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 nullable

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'consumer' | 'cookie' | 'header' | 'ip' | 'none' | 'path' | 'query_arg' | 'uri_capture' nullable

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

hash_on_cookiestring nullable

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 nullable

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

hash_on_headerstring nullable

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

hash_on_query_argstring nullable

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 nullable

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.

host_headerstring nullable

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

idstring nullable

A string representing a UUID (universally unique identifier).

namestring required

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

slotsinteger nullable

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.

sticky_sessions_cookiestring nullable

The cookie name to keep sticky sessions.

sticky_sessions_cookie_pathstring nullable

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

tagsstring[] nullable

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

updated_atinteger nullable

Unix epoch when the resource was last updated.

use_srv_nameboolean nullable

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

Example response

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

Changes

  • 8ab3ec3ed301Revision changes
    • info

      the response's property default value {"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}} was added for the status

    • info

      the response's property default value {"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}}} was added for the status

    • info

      the response's property default value {"http_statuses":[200,201,202,203,204,205,206,207,208,226,300,301,302,303,304,305,306,307,308],"successes":0} was added for the status

    • info

      the response's property default value {"http_statuses":[200,302],"interval":0,"successes":0} was added for the status

    • info

      the response's property default value {"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}} was added for the status

    • info

      the response's property default value {"http_failures":0,"http_statuses":[429,404,500,501,502,503,504,505],"interval":0,"tcp_failures":0,"timeouts":0} was added for the status

    • info

      the response's property default value {"http_failures":0,"http_statuses":[429,500,503],"tcp_failures":0,"timeouts":0} was added for the status

  • 3c0154b2053aRevision changes
    • breaking

      the response property / became nullable for the status

    • breaking

      the response property // became nullable for the status

    • breaking

      the response property // became nullable for the status

    • breaking

      the response property // became nullable for the status

    • breaking

      the response property // became nullable for the status

    • breaking

      the response property / became nullable for the status

    • breaking

      the response property // became nullable for the status

    • breaking

      the response property // became nullable for the status

    • info

      the response's property default value round-robin was added for the status

    • info

      the response's property default value 10 was added for the status

    • info

      the response's property default value none was added for the status

    • info

      the response's property default value none was added for the status

    • info

      the response's property default value / was added for the status

    • info

      the response's property default value 0 was added for the status

    • info

      the response's property default value 0 was added for the status

    • info

      the response's property default value / was added for the status

    • info

      the response's property default value 200 201 202 203 204 205 206 207 208 226 300 301 302 303 304 305 306 307 308 was added for the status

    • info

      the response's property default value 200 302 was added for the status

    • info

      the response's property default value 429 404 500 501 502 503 504 505 was added for the status

    • info

      the response's property default value 429 500 503 was added for the status

    • info

      the response's property default value true was added for the status

    • info

      the response's property default value 0 was added for the status

    • info

      the response's property default value 0 was added for the status

    • info

      the response's property default value 10000 was added for the status

    • info

      the response's property default value / was added for the status

    • info

      the response's property default value 0 was added for the status

    • info

      the response's property default value 0 was added for the status

    • info

      the response's property default value 0 was added for the status

    • info

      the response's property default value 0 was added for the status

    • info

      the response's property default value 0 was added for the status

    • info

      the response's property default value 1 was added for the status

    • info

      the response's property default value 0 was added for the status

    • info

      the response's property default value 0 was added for the status

    • info

      the response's property default value http was added for the status

    • info

      the response's property default value http was added for the status

    • info

      the response's property default value false was added for the status