← Gateway Entities

Upstreams

Uses: Kong Gateway decK KIC Terraform

What is an upstream?

An upstream refers to the service applications sitting behind Kong Gateway, to which client requests are forwarded. In Kong Gateway, an upstream represents a virtual hostname and can be used to health check, circuit break, and load balance incoming requests over multiple target backend services.

Use cases for upstreams

The following are examples of common use cases for upstreams:

Schema

Set up a Upstream

The following creates a new upstream called api.example.internal:

_format_version: '3.0'
upstreams:
  - name: api.example.internal
    tags:
    - user-level
    - low-priority
    algorithm: round-robin

To create a upstream, call the Admin API’s /upstreams endpoint.

curl -X POST http://localhost:8001/upstreams/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "api.example.internal",
      "tags": [
        "user-level",
        "low-priority"
      ],
      "algorithm": "round-robin"
    }
    '

Upstreams are automatically generated by Kong Ingress Controller based on the Kubernetes API server state.

Upstream behaviuour can be customized in KIC using the KongUpstreamPolicy resource:

apiVersion: configuration.konghq.com/v1beta1
kind: KongUpstreamPolicy
metadata:
    name: sample-customization
    konghq.com/tags: user-level, low-priority
spec:
    algorithm: round-robin

To use the upstream configuration, it needs to be associated with a Service:

kubectl patch service my-sample-service -p '{"metadata":{"annotations":{"konghq.com/upstream-policy":"sample-customization"}}}'

Prerequisite: Configure your Personal Access Token

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

resource "konnect_gateway_upstream" "my_upstream" {
  tags = ["user-level", "low-priority"]
  algorithm = "round-robin"

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

Upstreams

What is an upstream?

Use cases for upstreams

Schema

Set up a Upstream

Did this doc help?

Help us make these docs great!

Still need help