name: kong-supabase-edge-functions-503-debug

description: Debug and fix 503 errors on Supabase Edge Functions exposed via Kong on VPS — DNS resolution failures and upstream hostname issues.

triggers:

- Kong 503 name resolution failed

- Kong returning 503 for /functions/v1/ endpoints

- Edge Function unreachable from browser but curl works inside container

Symptoms

• - Kong returns 503 with {"message":"name resolution failed"} for /functions/v1/
• - Other Kong routes (auth, rest, storage) work fine
• - curl from inside the container network works, browser fails
• - Kong error log shows: DNS resolution failed: dns server error: 3 name error

Root Cause

Kong's upstream in kong.yml uses a hostname like http://functions:9000, but the Docker internal DNS (127.0.0.11) cannot resolve "functions" because:

1. The Edge Function container was created manually (no Docker Compose alias)

2. The container has Aliases: null in Docker network — no DNS name

3. Kong's kong reload does NOT re-resolve upstream hostnames — it caches them

Fix: nginx proxy sidecar pattern

Step 1: Identify the Edge Function container IP

`bash

docker inspect deploy-vps-functions-1 --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}'

Example output: 172.23.0.x

`

Step 2: Create nginx proxy container

Create /tmp/functions-proxy.Dockerfile:

`dockerfile

FROM nginx:alpine

RUN echo 'server { listen 9000; location / { proxy_pass http://:9000; } }' > /etc/nginx/conf.d/default.conf

EXPOSE 9000

`

Build and run:

`bash

docker build -f /tmp/functions-proxy.Dockerfile -t functions-proxy:latest /tmp

docker run -d --name deploy-vps-functions-proxy --network deploy-vps_default nginx:alpine

`

Wait for it to start, then verify:

`bash

docker run --rm --network deploy-vps_default curlimages/curl:latest -s -o /dev/null -w '%{http_code}' http://deploy-vps-functions-proxy:9000/functions/v1/main

Should return 401 (not 503)

`

Step 3: Update Kong config

In /tmp/kong.yml, change the Edge Function service from:

`yaml

• - service: functions-service

url: http://functions:9000

`

To:

`yaml

• - service: functions-service

url: http://deploy-vps-functions-proxy:9000

`

Step 4: Reload Kong

`bash

docker cp /tmp/kong.yml deploy-vps-kong-1:/tmp/kong.yml

docker exec deploy-vps-kong-1 kong reload

If still 503, do full restart:

docker restart deploy-vps-kong-1

`

Step 5: Verify

`bash

From host:

curl -s -o /dev/null -w '%{http_code}' http://localhost:8000/functions/v1/main

Should return 401 (not 503)

`

Why not hardcode the IP?

Hardcoding 172.23.0.x in kong.yml works but breaks when the container restarts and gets a new IP. The nginx proxy sidecar:

• - Has a stable Docker DNS name (deploy-vps-functions-proxy)
• - Survives Edge Function container restarts
• - Survives IP changes

Making the proxy permanent

The deploy-vps-functions-proxy container created with docker run is NOT permanent — it won't survive docker compose down. Add to docker-compose.yml:

`yaml

functions-proxy:

image: nginx:alpine

container_name: deploy-vps-functions-proxy

volumes:

- /tmp/functions-proxy.conf:/etc/nginx/conf.d/default.conf:ro

networks:

deploy-vps_default:

aliases:

- functions-proxy

restart: unless-stopped

expose:

- "9000"

`

Key Lessons

1. 503 + name resolution failed = Kong can't resolve upstream hostname in Docker DNS

2. kong reload is insufficient for upstream hostname changes — always do docker restart after modifying Kong's upstream config

3. Check Docker network aliases with docker inspect — if aliases is [] or null, the container has no DNS name

4. Use nginx proxy sidecar instead of hardcoding IPs — stable DNS name that survives restarts