Step-by-Step Tutorial on Kubernetes Gateway API

This tutorial walks you through the Gateway API step by step. Whether you're a developer, DevOps engineer, or platform architect, understanding how the Gateway API works is essential to building modern, scalable microservices environments. While Syncloop is not a Kubernetes tool itself, it works seamlessly in API-first and microservices architectures that often rely on Kubernetes for deployment.

What is Kubernetes Gateway API?

The Kubernetes Gateway API is an official project aiming to evolve and improve Kubernetes networking. Unlike the older Ingress API, the Gateway API provides:

• Better role separation (infra vs app teams)
• More flexible routing (HTTP, TCP, TLS, and more)
• Extensibility through custom route types and policies
• Standardization across multiple vendors

Core resources in the Gateway API include:

• GatewayClass: Defines the capabilities of the gateway controller (like NGINX, Istio, etc.)
• Gateway: Configures a load balancer for network traffic
• HTTPRoute (and other route types): Defines how traffic is routed to services
• BackendRef: Points to your actual Kubernetes services

Let’s now get our hands dirty and walk through setting up the Gateway API.

Prerequisites

Before we begin, you’ll need:

• A Kubernetes cluster (minikube, kind, or any cloud provider)
• kubectl configured for your cluster
• A Gateway API controller installed (e.g., istio, NGINX, or Kong)
• Basic knowledge of Kubernetes concepts like Services, Deployments, and Pods

Step 1: Install the Gateway API CRDs

First, you need to install the official Gateway API CRDs. Run:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/latest/download/standard-install.yaml

This command installs the Custom Resource Definitions for Gateway API types such as Gateway, GatewayClass, and HTTPRoute.

Step 2: Install a Gateway Controller

The CRDs alone don’t route traffic—you need a controller. Choose one (e.g., NGINX Gateway controller) and install it.

For example, to install the NGINX Gateway API controller:

kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/main/deploy/manifests/install.yaml

Ensure the controller is running:

kubectl get pods -n nginx-gateway

Step 3: Create a GatewayClass

Now define the type of Gateway you're using. Here's an example for NGINX:

yaml

apiVersion: gateway.networking.k8s.io/v1

kind: GatewayClass

metadata:

name: nginx-gateway

spec:

controllerName: nginx.org/gateway-controller

Apply it:

kubectl apply -f gatewayclass.yaml

Step 4: Define a Gateway Resource

This resource listens for incoming traffic and routes it to your services.

yaml

apiVersion: gateway.networking.k8s.io/v1

kind: Gateway

metadata:

name: my-gateway

namespace: default

spec:

gatewayClassName: nginx-gateway

listeners:

- name: http

port: 80

protocol: HTTP

hostname: "*"

Apply it:

kubectl apply -f gateway.yaml

Step 5: Deploy a Sample App

Let’s deploy a basic echo server:

kubectl create deployment echo-server --image=k8s.gcr.io/echoserver:1.10

kubectl expose deployment echo-server --port=8080 --target-port=8080

Step 6: Create an HTTPRoute

The HTTPRoute defines rules for routing incoming HTTP traffic.

yaml

apiVersion: gateway.networking.k8s.io/v1

kind: HTTPRoute

metadata:

name: echo-route

namespace: default

spec:

parentRefs:

- name: my-gateway

rules:

- matches:

- path:

type: PathPrefix

value: /

backendRefs:

- name: echo-server

port: 8080

Apply it:

kubectl apply -f httproute.yaml

Step 7: Test the Gateway

Retrieve the external IP of your Gateway:

kubectl get gateway my-gateway

Use curl to test:

curl http://

You should see a response from the echo server.

Step 8: (Optional) Add HTTPS Support

You can extend the Gateway to support TLS. Just update the listeners field to include:

listeners:

- name: https

port: 443

protocol: HTTPS

tls:

mode: Terminate

certificateRefs:

- name: my-cert

kind: Secret

Make sure to create a corresponding Kubernetes TLS Secret.

Best Practices

• Namespace Separation: Use namespaces to isolate routes and services per team or environment.
• Validation Tools: Use tools like kubectl explain or gateway-api-validator to check for spec compliance.
• Monitoring: Pair with tools like Prometheus and Grafana to monitor traffic through the Gateway.

Conclusion

The Kubernetes Gateway API represents a significant leap forward in how traffic is managed within clusters. Its resource model aligns better with enterprise requirements, offering greater control, scalability, and extensibility than traditional Ingress controllers.

Whether you’re building public APIs, internal microservices, or multi-tenant platforms, the Gateway API provides the flexibility and governance needed in modern architectures. And while Syncloop focuses on API management and development, it fits beautifully into cloud-native ecosystems that depend on Kubernetes as the underlying infrastructure.

So if you're looking to modernize your network layer, the Gateway API—and platforms like Syncloop—offer the perfect blend of power and simplicity.

A step-by-step illustrated diagram of the Kubernetes Gateway API architecture—showing flow from client requests through GatewayClass, Gateway, HTTPRoute, and into Kubernetes Services.

  Back to Blogs