Proxy Requests to External Services

Configure APISIX or API7 Ingress Controller to proxy requests to external services hosted outside your Kubernetes cluster.

Applies to:API7 Ingress Controller (drives API7 Gateway)APISIX Ingress Controller (drives Apache APISIX)

Goal

Configure the gateway to proxy HTTP requests from a Kubernetes route to an external service such as httpbin.org.

Before you begin

Complete Set Up Ingress Controller and Gateway.
You have kubectl configured against the cluster used in the setup guide.
Choose a free local port for the gateway port-forward. The examples use 9080.

Set the variables this guide uses:

export EXTERNAL_DOMAIN="httpbin.org"
export ROUTE_PATH="/ip"
export GATEWAY_SERVICE_NAME="apisix-gateway"   # your gateway's Service name in namespace aic
export GATEWAY_HTTP_PORT="80"
export FORWARD_PORT="9080"

Steps

Step 1: Create the ExternalName Service and route

Create a manifest for an ExternalName Service and a route that proxies requests to httpbin.org:

httpbin-route.yaml

apiVersion: v1
kind: Service
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
  ports:
  - name: http
    port: 80
    appProtocol: http
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: httpbin-ip
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches:
    - path:
        type: Exact
        value: /ip
    backendRefs:
    - name: httpbin-external-domain
      port: 80

httpbin-route.yaml

apiVersion: v1
kind: Service
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
  ports:
  - name: http
    port: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: aic
  name: httpbin-ip
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /ip
        pathType: Exact
        backend:
          service:
            name: httpbin-external-domain
            port:
              number: 80

httpbin-route.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  ingressClassName: apisix
  externalNodes:
  - type: Domain
    name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: aic
  name: httpbin-ip
spec:
  ingressClassName: apisix
  http:
    - name: httpbin-ip
      match:
        paths:
          - /ip
      upstreams:
      - name: httpbin-external-domain

For Gateway API HTTPRoute resources, the controller reads appProtocol from an ExternalName Service port just as it does for a selector-based Service. Use http, https, kubernetes.io/ws, or kubernetes.io/wss to select the upstream protocol. See Detect Upstream Protocol with appProtocol.

Step 2: Apply the configuration

Apply the manifest to your cluster:

kubectl apply -f httpbin-route.yaml

Validate

Forward the gateway HTTP port to your local machine:

kubectl port-forward -n aic "svc/${GATEWAY_SERVICE_NAME}" "${FORWARD_PORT}:${GATEWAY_HTTP_PORT}" &

Send a request to the route:

curl "http://127.0.0.1:${FORWARD_PORT}${ROUTE_PATH}"

Expected: a JSON response with an origin field similar to:

{
  "origin": "183.94.122.205"
}

Roll back / Clean up

Delete the manifest created in this guide:

kubectl delete -f httpbin-route.yaml

Stop the local port-forward process if it is still running:

kill %1 2>/dev/null || true

Troubleshoot

Symptom	Cause	Fix
`curl` returns `502 Bad Gateway`.	The external domain is not reachable from the gateway, or the `ExternalName` Service has no port defined.	Verify `EXTERNAL_DOMAIN` resolves from the cluster and the Service `ports` list includes the referenced `port`.
`curl` returns `404 Not Found`.	The route path does not match `ROUTE_PATH`.	Confirm the route matches `/ip` exactly and references `httpbin-external-domain` on port `80`.
`kubectl` reports a missing `ExternalName` error.	The `ExternalName` type is not supported by the backend or the DNS lookup failed.	Check that `httpbin.org` is reachable from the gateway Pod and that the cluster DNS is working.