Common Causes of 502 Upstream Error in Kong

In Kong Gateway, the Service and Route are core entities that determine how external requests are proxied to your upstream APIs or services.

Here’s how they work together:

1. Service (What you proxy to)

A Service in Kong represents an upstream API or backend application you want to expose via Kong.

Example:

{
  "name": "example-service",
  "url": "http://my-upstream-api:8080"
}

• This defines where Kong should send requests once they are matched.
• It includes details like host, port, path, or protocol.

2. Route (How requests are matched)

A Route defines the rules that determine which requests should be forwarded to a Service.

Example:

{
  "paths": ["/api/v1"],
  "methods": ["GET", "POST"],
  "service": { "id": "example-service-id" }
}

• It maps incoming requests (based on path, method, host, headers, etc.) to a specific Service.
• One service can have multiple routes (e.g., /v1/users, /v1/orders, etc.).

The Flow

Client --> Kong Gateway --> [Route matched] --> [Service invoked] --> Upstream API

1. Kong receives a request.
2. It checks the Route rules (e.g., path, host).
3. If a match is found, it forwards the request to the associated Service.
4. The upstream service processes it and returns the response via Kong.

Plugins

You can attach plugins (like rate-limiting, auth, logging) at:

• Global level (applies to all requests)
• Service level (applies to all routes of a service)
• Route level (applies only to that route)

Quick Example via curl

# Create a service
curl -i -X POST http://localhost:8001/services \
  --data name=example-service \
  --data url=http://httpbin.org

# Create a route to that service
curl -i -X POST http://localhost:8001/services/example-service/routes \
  --data paths[]=/test

Now, accessing http://localhost:8000/test will proxy to http://httpbin.org.

Example 2:

Absolutely. Let’s break down how Services and Routes work in Kong Gateway, with a clear explanation, flow, and examples.

🔹 What Is a Service in Kong?

A Service in Kong Gateway represents an upstream API or microservice. This is the destination Kong forwards requests to. You define a service with details like the host, port, and protocol (HTTP, HTTPS, TCP, etc.).

Example:

{
  "name": "user-service",
  "url": "http://user-api.internal:8080"
}

Or more explicitly:

{
  "name": "user-service",
  "host": "user-api.internal",
  "port": 8080,
  "protocol": "http"
}

🔸 What Is a Route in Kong?

A Route defines how incoming client requests are mapped to a Service. Routes define rules and match criteria like:

• Path (e.g., /users)
• HTTP method (e.g., GET, POST)
• Host (e.g., api.myapp.com)
• Headers
• SNI (for SSL)
• TCP/UDP port

Example:

{
  "paths": ["/users"],
  "methods": ["GET", "POST"],
  "service": { "id": "uuid-of-user-service" }
}

🔄 How Do They Work Together?

1. A client sends a request to Kong (e.g., GET https://api.myapp.com/users).
2. Kong matches the request to a Route based on the defined criteria.
3. The Route is linked to a Service.
4. Kong forwards the request to the upstream Service.
5. The response is returned to the client.

🔁 Flow Diagram (Simplified)

Client
  |
  v
[Request: GET /users]
  |
  v
[Kong Gateway]
  |
  ├─► Match Route: "/users" → user-service
  |
  └─► Forward to: http://user-api.internal:8080
              |
              v
      [Upstream Service Response]
              |
              v
          [Kong Gateway]
              |
              v
            Client

🧪 Practical Example Using curl

1. Create Service

curl -i -X POST http://localhost:8001/services \
  --data name=user-service \
  --data url='http://user-api.internal:8080'

2. Create Route

curl -i -X POST http://localhost:8001/services/user-service/routes \
  --data paths[]='/users'

Now, when you call:

curl http://localhost:8000/users

Kong will route it to:

http://user-api.internal:8080

Advanced Matching Capabilities

Routes can also match based on:

• hosts (virtual hosts like api.myapp.com)
• methods (GET, POST, etc.)
• headers (e.g., X-Version)
• snis (for SSL/TLS)
• sources/destinations (for TCP streams)

Best Practices

• Keep one route per API path unless multi-match is needed.
• Use tags to categorize services/routes for environments.
• Apply plugins at service or route level depending on scope:
  • Service-level plugin: applies to all routes to that service.
  • Route-level plugin: applies only to that specific route.

Would you like a visual diagram in PNG or SVG format, or a Postman collection to test this setup?

Why Only IP is Logged for Upstream

1. Upstream Targets Are Resolved to IPs
   • When you define an upstream with a hostname and add targets, Kong internally resolves the hostname to an IP using DNS and then proxies to that IP.
   • Kong logs the resolved IP address, not the hostname, to provide the actual connection endpoint for traceability.
2. Performance and Audit Reasons
   • Logging IPs ensures consistency across distributed deployments, since DNS entries may change over time.
   • IPs provide exact traceability in debugging and auditing upstream behavior.
3. DNS Caching and TTL
   • Kong caches DNS results. Once a hostname is resolved to an IP, that IP is used and logged during the TTL window.
4. No Custom Log Format or Plugin in Use
   • By default, Kong does not resolve or log upstream hostnames unless a custom plugin or log transformer is used.

Here’s a minimal yet flexible Ansible playbook to deploy routes in Kong Gateway using the uri module to interact with the Admin API. This example assumes:

• Kong Admin API is accessible (e.g. http://localhost:8001).
• A service is already defined (or you can create one using Ansible).
• You’re deploying a route for an existing service.

✅ Example Directory Layout

kong_routes/
├── playbook.yml
└── vars/
    └── routes.yml

📄 vars/routes.yml

kong_admin_url: "http://localhost:8001"

kong_routes:
  - name: route1
    service: example-service
    paths: ["/example"]
    methods: ["GET"]
    strip_path: true

📄 playbook.yml

- name: Deploy Routes to Kong
  hosts: localhost
  connection: local
  vars_files:
    - vars/routes.yml
  tasks:
    - name: Ensure route exists in Kong
      uri:
        url: "{{ kong_admin_url }}/routes"
        method: POST
        body_format: json
        headers:
          Content-Type: "application/json"
        body: >-
          {
            "name": "{{ item.name }}",
            "paths": {{ item.paths | to_json }},
            "methods": {{ item.methods | to_json }},
            "strip_path": {{ item.strip_path }},
            "service": { "name": "{{ item.service }}" }
          }
        status_code: 201
      loop: "{{ kong_routes }}"
      ignore_errors: true  # optional: prevents failure if route exists

✅ Optional: Create Service First

Add this before the route task if needed:

    - name: Ensure service exists
      uri:
        url: "{{ kong_admin_url }}/services"
        method: POST
        body_format: json
        headers:
          Content-Type: "application/json"
        body: >-
          {
            "name": "{{ item.service }}",
            "url": "http://mockbin.org"  # change to your backend URL
          }
        status_code: 201
      loop: "{{ kong_routes }}"
      ignore_errors: true

Would you like this to support idempotency (check if the route already exists and update it), or include support for Kong Konnect or authentication headers (e.g. RBAC tokens)?

headers:
Content-Type: “application/json”
Authorization: “Bearer {{ kong_admin_token }}”

To export a Kong service with its route(s) and plugin(s) and re-deploy it via Ansible, follow this structured approach:

Step 1: Export Kong Configuration (Service + Route + Plugins)

Use Kong’s Admin API or deck (Kong’s declarative configuration tool).

Option A: Use deck

deck dump –select-tag my-service-tag –output-file exported.yaml

🔹 Tagging helps isolate what to export (tag services, routes, plugins with my-service-tag beforehand).
🔹 You can also export the full config with deck dump.

Option B: Use cURL (for manual/scripted extraction)

# Get service

curl -s http://<KONG_ADMIN&gt;:8001/services/my-service > service.json

# Get route(s) for the service

curl -s http://<KONG_ADMIN&gt;:8001/services/my-service/routes > routes.json

# Get plugins for the service

curl -s http://<KONG_ADMIN&gt;:8001/services/my-service/plugins > plugins.json

 Step 2: Transform into Ansible-compatible format

Create a folder structure:

kong/

├── files/

│   └── exported.yaml  # if using deck

├── templates/

│   └── service.json.j2

│   └── routes.json.j2

│   └── plugins.json.j2

└── tasks/

    └── deploy-kong.yml

✅ Step 3: Create Ansible Playbook

If using deck:

# tasks/deploy-kong.yml

– name: Deploy config to Kong via deck

  ansible.builtin.command:

    cmd: “deck sync –state exported.yaml”

  args:

    chdir: “{{ playbook_dir }}/files”

If using cURL approach (raw API):

- name: Create service in Kong
  uri:
    url: "http://{{ kong_admin_host }}:8001/services"
    method: POST
    body: "{{ lookup('file', 'templates/service.json.j2') | from_json }}"
    body_format: json
    status_code: [201, 409]  # 409 = already exists
    headers:
      Content-Type: "application/json"

- name: Create route for the service
  uri:
    url: "http://{{ kong_admin_host }}:8001/services/{{ service_name }}/routes"
    method: POST
    body: "{{ lookup('file', 'templates/routes.json.j2') | from_json }}"
    body_format: json
    status_code: [201, 409]
    headers:
      Content-Type: "application/json"

- name: Add plugins to service
  uri:
    url: "http://{{ kong_admin_host }}:8001/services/{{ service_name }}/plugins"
    method: POST
    body: "{{ lookup('file', 'templates/plugins.json.j2') | from_json }}"
    body_format: json
    status_code: [201, 409]
    headers:
      Content-Type: "application/json"

Step 4: Run Playbook

ansible-playbook deploy-kong.yml -e “kong_admin_host=your.kong.gateway”

 Optional: Use Tags to Scope with deck

Tag services during creation to support selective dumps later:

curl -X PATCH http://localhost:8001/services/my-service \

  –data “tags=my-service-tag”

example of j2

{
  "name": "my-service",
  "host": "example.internal",
  "port": 8080,
  "protocol": "http",
  "path": "/api",
  "connect_timeout": 60000,
  "write_timeout": 60000,
  "read_timeout": 60000,
  "retries": 5,
  "tags": ["exported", "my-tag"]
}

Full ansible playbook 

---
- name: Deploy Kong service with routes and plugins
  hosts: kong
  gather_facts: no
  vars:
    kong_admin_url: "{{ kong_admin_host | default('http://localhost:8001') }}"
  tasks:

    - name: Load service JSON
      set_fact:
        service_payload: "{{ lookup('file', 'templates/service.json.j2') | from_json }}"

    - name: Create service
      uri:
        url: "{{ kong_admin_url }}/services"
        method: POST
        body: "{{ service_payload }}"
        body_format: json
        status_code: [201, 409]
        headers:
          Content-Type: "application/json"

    - name: Load routes JSON (could be a single or multiple routes)
      set_fact:
        routes_payload: "{{ lookup('file', 'templates/routes.json.j2') | from_json }}"

    - name: Create route(s) for the service
      uri:
        url: "{{ kong_admin_url }}/services/{{ service_payload.name }}/routes"
        method: POST
        body: "{{ item }}"
        body_format: json
        status_code: [201, 409]
        headers:
          Content-Type: "application/json"
      loop: "{{ routes_payload | type_debug == 'list' | ternary(routes_payload, [routes_payload]) }}"

    - name: Load plugins JSON
      set_fact:
        plugins_payload: "{{ lookup('file', 'templates/plugins.json.j2') | from_json }}"

    - name: Add plugin(s) to the service
      uri:
        url: "{{ kong_admin_url }}/services/{{ service_payload.name }}/plugins"
        method: POST
        body: "{{ item }}"
        body_format: json
        status_code: [201, 409]
        headers:
          Content-Type: "application/json"
      loop: "{{ plugins_payload }}"