Skip to content

Quick Start

This guide walks you through creating your first HTTPRoute to expose a Kubernetes service through Pingora proxy.

Prerequisites

Ensure you have completed:

Deploy a Sample Application

First, deploy a simple application to expose:

kubectl create deployment nginx --image=nginx:latest
kubectl expose deployment nginx --port=80

Create a Gateway

Create a Gateway resource to define an entry point:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: pingora-gateway
  namespace: pingora-system
spec:
  gatewayClassName: pingora
  listeners:
    - name: http
      port: 80
      protocol: HTTP

Apply the Gateway:

kubectl apply --filename gateway.yaml

Create an HTTPRoute

Create an HTTPRoute to expose the nginx service:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: nginx
  namespace: default
spec:
  parentRefs:
    - name: pingora-gateway
      namespace: pingora-system
  hostnames:
    - nginx.example.com
  rules:
    - backendRefs:
        - name: nginx
          port: 80

Apply the route:

kubectl apply --filename httproute.yaml

Verify the Route

Check that the HTTPRoute is accepted:

kubectl get httproute nginx

Expected output:

NAME    HOSTNAMES               AGE
nginx   ["nginx.example.com"]   30s

Check the route status:

kubectl get httproute nginx --output jsonpath='{.status.parents[*].conditions}' | jq

Expected output includes "type":"Accepted","status":"True".

Access Your Application

Get the proxy service IP:

kubectl get service --namespace pingora-system --selector app.kubernetes.io/component=proxy

For testing, use port-forward:

kubectl port-forward --namespace pingora-system service/pingora-gateway-controller-proxy 8080:80

Then access via curl:

curl --header "Host: nginx.example.com" http://localhost:8080

Path-Based Routing

Route different paths to different services:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-routes
spec:
  parentRefs:
    - name: pingora-gateway
      namespace: pingora-system
  hostnames:
    - api.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1
      backendRefs:
        - name: api-v1
          port: 8080
    - matches:
        - path:
            type: PathPrefix
            value: /v2
      backendRefs:
        - name: api-v2
          port: 8080

Header-Based Routing

Route based on request headers:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: header-routes
spec:
  parentRefs:
    - name: pingora-gateway
      namespace: pingora-system
  hostnames:
    - app.example.com
  rules:
    - matches:
        - headers:
            - name: X-Version
              value: beta
      backendRefs:
        - name: app-beta
          port: 8080
    - backendRefs:
        - name: app-stable
          port: 8080

Troubleshooting

Route Not Accepted

Check controller logs:

kubectl logs --selector app.kubernetes.io/name=pingora-gateway-controller \
  --namespace pingora-system

Common issues:

  • Gateway not found (wrong namespace or name in parentRefs)
  • Service not found (wrong service name or namespace)
  • GatewayClass not accepted

Connection Refused

Verify the proxy is running and has endpoints:

kubectl get endpoints --namespace pingora-system

Check if backend service has healthy pods:

kubectl get pods --selector app=nginx

Next Steps