Targets

Uses: Kong Gateway Admin API decK KIC Konnect API Terraform

What is a Target?

A Target identifies an instance of an upstream service using an IP address or hostname with a port. Each Upstream can have many Targets. Targets are used by Upstreams for load balancing. For example, if you have an example_upstream Upstream, you can point it to two different Targets: httpbin.konghq.com and httpbun.com. This is so that if one of the servers (like httpbin.konghq.com) is unavailable, it automatically detects the problem and routes all traffic to the working server (httpbun.com).

The following diagram illustrates how Targets are used by Upstreams for load balancing:

 
flowchart LR

  A("Request")
  B("`Route 
  (/mock)`")
  C("`Service
  (example_service)`")
  D("Target:
  httpbin.konghq.com")
  E("Target:
  httpbun.com")
  F(Upstream service:
  httpbin.konghq.com)
  G(Upstream service:
  httpbun.com)

  A --> B
  subgraph id1 ["`**KONG GATEWAY**`"]
    B --> C --> D & E
  subgraph id3 ["`**Upstream** (load balancer)`"]
  
    D & E
  end

  end

  subgraph id2 ["`**Target upstream services**`"]
    D --> F
    E --> G

  end

  style id2 stroke:none!important

Using hostnames

A Target can also have a hostname instead of an IP address. In that case, the name is resolved and all entries found are individually added to the load balancer.

For example, let’s say you add api.host.com:123 with weight=100:

If the hostname api.host.com resolves to an A record with 2 IP addresses, both IP addresses are added as a target, each with weight=100 and port 123.
If the hostname resolves to an SRV record, then the port and weight fields from the DNS record are used, and override the port and weight set in the Target.

The balancer honors the DNS record’s ttl setting. Upon expiry, it queries the nameserver and updates the balancer. When a DNS record has ttl=0, the hostname is added as a single target, with the specified weight. The nameserver is queried for every request, adding latency to the request.

Schema

Set up a Target

The following creates a new Target called example_upstream:

_format_version: "3.0"
upstreams:
  - name: example_upstream
    targets:
    - target: httpbun.com:80
      weight: 100

To create a Target, call the Admin API’s /targets endpoint.

curl -i -X POST http://localhost:8001/upstreams/{upstreamName|Id}/targets/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "target": "httpbun.com:80",
      "weight": 100
    }
    '

To create a Target, call the Konnect control plane config API’s /targets endpoint.

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/upstreams/{upstreamId}/targets/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "target": "httpbun.com:80",
      "weight": 100
    }
    '

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.

See the Konnect API reference to learn about region-specific URLs and personal access tokens.

apiVersion: configuration.konghq.com/v1
kind: KongTarget
metadata:
  name: 
  annotations:
    kubernetes.io/ingress.class: kong
upstreamRef:
    name: example_upstream
target: httpbun.com:80
weight: 100

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_target" "my_target" {
  target = "httpbun.com:80"
  weight = 100

  upstream_id = konnect_gateway_upstream.my_upstream.id
  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

The following creates a new Upstream and a Target with basic configuration:

In Kong Manager or Gateway Manager, navigate to Workspaces > Upstreams.
Click New Upstream.
Enter a unique name for the Upstream. For example: example_upstream.
Click Save.
From your Upstream, select the Targets tab.
Click New Target.
Enter an IP address/hostname and port in the Target Address field, for example: httpbun.com:80
Update the weight for example: 100.
Click Save.

Targets

What is a Target?

Using hostnames

Schema

Set up a Target

Help us make these docs great!

Still need help