NGINX Kubernetes Gateway is an open-source project that provides an implementation of the Gateway API using NGINX as the data plane. The goal of this project is to implement the core Gateway APIs -- Gateway
, GatewayClass
, HTTPRoute
, TCPRoute
, TLSRoute
, and UDPRoute
-- to configure an HTTP or TCP/UDP load balancer, reverse-proxy, or API gateway for applications running on Kubernetes. NGINX Kubernetes Gateway is currently under development and supports a subset of the Gateway API.
Warning: This project is actively in development (pre-alpha feature state) and should not be deployed in a production environment. All APIs, SDKs, designs, and packages are subject to change.
Before you can build and run the NGINX Kubernetes Gateway, make sure you have the following software installed on your machine:
-
Clone the repo and change into the
nginx-kubernetes-gateway
directory:git clone https://github.com/nginxinc/nginx-kubernetes-gateway.git cd nginx-kubernetes-gateway
-
Build the image:
make PREFIX=myregistry.example.com/nginx-kubernetes-gateway container
Set the
PREFIX
variable to the name of the registry you'd like to push the image to. By default, the image will be namednginx-kubernetes-gateway:0.0.1
. -
Push the image to your container registry:
docker push myregistry.example.com/nginx-kubernetes-gateway:0.0.1
Make sure to substitute
myregistry.example.com/nginx-kubernetes-gateway
with your private registry.
You can deploy NGINX Kubernetes Gateway on an existing Kubernetes 1.16+ cluster. The following instructions walk through the steps for deploying on a kind cluster.
-
Load the NGINX Kubernetes Gateway image onto your kind cluster:
kind load docker-image nginx-kubernetes-gateway:0.0.1
Make sure to substitute the image name with the name of the image you built.
-
Install the Gateway CRDs:
kubectl apply -k "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v0.4.2"
-
Deploy the NGINX Kubernetes Gateway:
Before deploying, make sure to update the Deployment spec in
nginx-gateway.yaml
to reference the image you built.kubectl apply -f deploy/manifests/nginx-gateway.yaml
-
Confirm the NGINX Kubernetes Gateway is running in
nginx-gateway
namespace:kubectl get pods -n nginx-gateway NAME READY STATUS RESTARTS AGE nginx-gateway-5d4f4c7db7-xk2kq 2/2 Running 0 112s
You can gain access to NGINX Kubernetes Gateway by creating a NodePort
Service or a LoadBalancer
Service.
Create a service with type NodePort
:
kubectl apply -f deploy/manifests/service/nodeport.yaml
A NodePort
service will randomly allocate one port on every node of the cluster. To access NGINX Kubernetes Gateway, use an IP address of any node in the cluster along with the allocated port.
Create a service with type LoadBalancer
using the appropriate manifest for your cloud provider.
-
For GCP or Azure:
kubectl apply -f deploy/manifests/service/loadbalancer.yaml
Lookup the public IP of the load balancer:
kubectl get svc nginx-gateway -n nginx-gateway
Use the public IP of the load balancer to access NGINX Kubernetes Gateway.
-
For AWS:
kubectl apply -f deploy/manifests/service/loadbalancer-aws-nlb.yaml
In AWS, the NLB DNS name will be reported by Kubernetes in lieu of a public IP. To get the DNS name run:
kubectl get svc nginx-gateway -n nginx-gateway
In general, you should rely on the NLB DNS name, however for testing purposes you can resolve the DNS name to get the IP address of the load balancer:
nslookup <dns-name>
To test the NGINX Kubernetes Gateway run:
make unit-test