ACLs3

Add-Ons4

API4

API Documentation4

API Implementation3

API Product Documentation4

API Product Version Specification4

API Product Versions4

API Products4

API Publication3

API Specification4

API Version4

API-keys3

App Auth Strategies4

Application Registrations4

Applications4

Assets4

Audit Logs7

Auth Server4

Auth Server Claims4

Auth Server Clients8

Auth Server Scopes4

Auth Settings9

Basic-auth credentials3

CA Certificates4

Catalog Services4

Centrally Managed Consumers4

Centrally Managed Keys3

Certificates4

Cloned Plugins4

CMEK3

Config Store Secrets4

Config Stores4

Consumer Groups6

Consumers4

Control Plane Groups2

Control Planes6

Custom Domains3

Custom Plugin Schemas4

CustomPlugins4

Data-Plane Group Configurations2

DCR Providers4

DP Certificates4

Event Gateway Backend Clusters4

Event Gateway DataPlane Certificates4

Event Gateway Listener Policies8

Event Gateway Listeners4

Event Gateway Schema Registries4

Event Gateway Static Keys3

Event Gateway TLS Trust Bundles4

Event Gateway Virtual Cluster Consume Policies20

Event Gateway Virtual Cluster Policies4

Event Gateway Virtual Cluster Produce Policies16

Event Gateway Virtual Clusters4

Event Gateways4

GraphQL Cost Decorations1

HMAC-auth credentials3

Integration Instance Auth Config3

Integration Instance Auth Credentials3

Integration Instances4

JWTs3

Keys4

KeySets4

Mesh5

MTLS-auth credentials3

Networks5

Pages4

Partials4

Personal Access Tokens2

Platform IPs1

Plugins449

Portal Appearance2

Portal Audit Logs3

Portal Auth Settings9

Portal Custom Domains4

Portal Customization2

Portal Developers4

Portal Product Versions3

Portal Team Roles2

Portal Teams4

Portals10

Portals IP Allow List4

Private DNS3

Provider Accounts1

Realms4

Roles6

Routes8

Serverless Cloud Gateways3

Services4

Snippets4

SNIs4

System Accounts5

System Accounts - Access Tokens4

System Accounts - Roles3

System Accounts - Team Membership2

Targets3

Team Membership2

Teams5

Transit Gateways4

Upstreams4

Vaults4

patchReset Auth Settings

Upstreams

Create a new Upstream

post/v2/control-planes/{controlPlaneId}/core-entities/upstreams

Request body

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.

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.

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 request

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

Response

Successfully created Upstream