---
title: "Upstream"
url: "https://nov18-dev.movespot.fyi/apis/konnect-runtime-groups-configuration-0/versions/af18902c-58f1-49d7-8ec2-9987b4e0d1bd/schemas/Upstream"
---

> Full API specification: https://nov18-dev.movespot.fyi/apis/konnect-runtime-groups-configuration-0/versions/af18902c-58f1-49d7-8ec2-9987b4e0d1bd.md

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

## OpenAPI definition

```yaml
openapi: 3.0.0
info:
  title: Konnect Runtime Groups Configuration
  version: 0.0.1
servers:
  - url: https://us.api.konghq.com/v2
    description: United-States Production region
  - url: https://eu.api.konghq.com/v2
    description: Europe Production region
  - url: https://au.api.konghq.com/v2
    description: Australia Production region
  - url: https://me.api.konghq.com/v2
    description: Middle-East Production region
  - url: https://in.api.konghq.com/v2
    description: India Production region
  - url: https://sg.api.konghq.com/v2
    description: Singapore Production region
components:
  schemas:
    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
        client_certificate:
          description: If set, the certificate to be used as client certificate while TLS
            handshaking to the upstream server.
          type: object
          additionalProperties: false
          properties:
            id:
              type: string
        created_at:
          description: Unix epoch when the resource was created.
          type: integer
          example: 1422386534
        updated_at:
          description: Unix epoch when the resouce was updated.
          type: integer
          example: 1422386534
        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
        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
        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
        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
        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
        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
        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: /
        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
        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
        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
        healthchecks:
          type: object
          properties:
            active:
              type: object
              properties:
                concurrency:
                  type: integer
                  default: 10
                headers:
                  type: object
                healthy:
                  type: object
                  properties:
                    http_statuses:
                      type: array
                      items:
                        type: integer
                      default:
                        - 200
                        - 302
                    interval:
                      type: number
                      default: 0
                    successes:
                      type: integer
                      default: 0
                http_path:
                  type: string
                  default: /
                https_sni:
                  type: string
                https_verify_certificate:
                  type: boolean
                  default: true
                timeout:
                  type: number
                  default: 1
                type:
                  type: string
                  default: http
                unhealthy:
                  type: object
                  properties:
                    http_failures:
                      type: integer
                      default: 0
                    http_statuses:
                      type: array
                      items:
                        type: integer
                      default:
                        - 429
                        - 404
                        - 500
                        - 501
                        - 502
                        - 503
                        - 504
                        - 505
                    interval:
                      type: number
                      default: 0
                    tcp_failures:
                      type: integer
                      default: 0
                    timeouts:
                      type: integer
                      default: 0
            passive:
              type: object
              properties:
                healthy:
                  type: object
                  properties:
                    http_statuses:
                      type: array
                      items:
                        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
                type:
                  type: string
                  default: http
                unhealthy:
                  type: object
                  properties:
                    http_failures:
                      type: integer
                      default: 0
                    http_statuses:
                      type: array
                      items:
                        type: integer
                      default:
                        - 429
                        - 500
                        - 503
                    tcp_failures:
                      type: integer
                      default: 0
                    timeouts:
                      type: integer
                      default: 0
            threshold:
              type: number
              default: 0
        host_header:
          description: The hostname to be used as `Host` header when proxying requests
            through Kong.
          type: string
        id:
          type: string
        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
        tags:
          description: An optional set of strings associated with the Upstream for
            grouping and filtering.
          type: array
          items:
            type: string
        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
      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
```
