Get started

This is a guide for getting started with NGINX Gateway Fabric. It explains how to:

By following the steps in order, you will finish with a functional NGINX Gateway Fabric cluster.

Before you begin

To complete this guide, you need the following prerequisites installed:

  • Go 1.16 or newer, which is used by kind
  • Docker, for creating and managing containers
  • kind, which allows for running a local Kubernetes cluster using Docker
  • kubectl, which provides a command line interface (CLI) for interacting with Kubernetes clusters
  • Helm 3.0 or newer to install NGINX Gateway Fabric
  • curl, to test the example application

Set up a kind cluster

Create the file cluster-config.yaml with the following contents, noting the highlighted lines:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

apiVersion: kind.x-k8s.io/v1alpha4
kind: Cluster
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 31437
    hostPort: 8080
    protocol: TCP
  - containerPort: 31438
    hostPort: 8443
    protocol: TCP
Warning:
Take note of the two containerPort values. They are necessary for later configuring a NodePort.

Run the following command:

kind create cluster --config cluster-config.yaml

Creating cluster "kind" ...
 ✓ Ensuring node image (kindest/node:v1.31.0) đŸ–ŧ
 ✓ Preparing nodes đŸ“Ļ
 ✓ Writing configuration 📜
 ✓ Starting control-plane 🕹ī¸
 ✓ Installing CNI 🔌
 ✓ Installing StorageClass 💾
Set kubectl context to "kind-kind"
You can now use your cluster with:

kubectl cluster-info --context kind-kind

Thanks for using kind! 😊
Note:

If you have cloned the NGINX Gateway Fabric repository, you can also create a kind cluster from the root folder with the following make command:

make create-kind-cluster

Install NGINX Gateway Fabric

Add Gateway API resources

Use kubectl to add the API resources for NGINX Gateway Fabric with the following command:

kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.4.0" | kubectl apply -f -

customresourcedefinition.apiextensions.k8s.io/gatewayclasses.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/grpcroutes.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io created
Note:

To use experimental features, you’ll need to install the API resources from the experimental channel instead.

kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.4.0" | kubectl apply -f -

Install the Helm chart

Use helm to install NGINX Gateway Fabric with the following command:

helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.create=false

Pulled: ghcr.io/nginxinc/charts/nginx-gateway-fabric:1.4.0
Digest: sha256:9bbd1a2fcbfd5407ad6be39f796f582e6263512f1f3a8969b427d39063cc6fee
NAME: ngf
LAST DEPLOYED: Mon Oct 21 14:45:14 2024
NAMESPACE: nginx-gateway
STATUS: deployed
REVISION: 1
TEST SUITE: None
Note:

If you installed the API resources from the experimental channel during the last step, you will need to enable the nginxGateway.gwAPIExperimentalFeatures option:

helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.create=false --set nginxGateway.gwAPIExperimentalFeatures.enable=true

Set up a NodePort

Create the file nodeport-config.yaml with the following contents:

Note:
The highlighted nodePort values should equal the containerPort values from cluster-config.yaml when you created the kind cluster.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

apiVersion: v1
kind: Service
metadata:
  name: nginx-gateway
  namespace: nginx-gateway
  labels:
    app.kubernetes.io/name: nginx-gateway-fabric
    app.kubernetes.io/instance: ngf
    app.kubernetes.io/version: "1.4.0"
spec:
  type: NodePort
  selector:
    app.kubernetes.io/name: nginx-gateway-fabric
    app.kubernetes.io/instance: ngf
  ports:
  - name: http
    port: 80
    protocol: TCP
    targetPort: 80
    nodePort: 31437
  - name: https
    port: 443
    protocol: TCP
    targetPort: 443
    nodePort: 31438

Apply it using kubectl:

kubectl apply -f nodeport-config.yaml

service/nginx-gateway created
Warning:

The NodePort resource must be deployed in the same namespace as NGINX Gateway Fabric.

If you are making customizations, ensure your labels: and selectors: also match the labels of the NGINX Gateway Fabric Deployment.

Create an example application

In the previous section, you deployed NGINX Gateway Fabric to a local cluster. This section shows you how to deploy a simple web application to test that NGINX Gateway Fabric works.

Note:
The YAML code in the following sections can be found in the cafe-example folder of the GitHub repository.

Create the application resources

Create the file cafe.yaml with the following contents:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: coffee
spec:
  replicas: 1
  selector:
    matchLabels:
      app: coffee
  template:
    metadata:
      labels:
        app: coffee
    spec:
      containers:
      - name: coffee
        image: nginxdemos/nginx-hello:plain-text
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: coffee
spec:
  ports:
  - port: 80
    targetPort: 8080
    protocol: TCP
    name: http
  selector:
    app: coffee
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tea
spec:
  replicas: 1
  selector:
    matchLabels:
      app: tea
  template:
    metadata:
      labels:
        app: tea
    spec:
      containers:
      - name: tea
        image: nginxdemos/nginx-hello:plain-text
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: tea
spec:
  ports:
  - port: 80
    targetPort: 8080
    protocol: TCP
    name: http
  selector:
    app: tea

Apply it:

kubectl apply -f cafe.yaml

deployment.apps/coffee created
service/coffee created
deployment.apps/tea created
service/tea created

Verify that the new pods are in the default namespace:

kubectl -n default get pods

NAME                      READY   STATUS    RESTARTS   AGE
coffee-6db967495b-wk2mm   1/1     Running   0          10s
tea-7b7d6c947d-d4qcf      1/1     Running   0          10s

Create Gateway and HTTPRoute resources

Create the file gateway.yaml with the following contents:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gateway
spec:
  gatewayClassName: nginx
  listeners:
  - name: http
    port: 80
    protocol: HTTP
    hostname: "*.example.com"

Apply it using kubectl:

kubectl apply -f gateway.yaml

gateway.gateway.networking.k8s.io/gateway created

Create the file cafe-routes.yaml with the following contents:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: coffee
spec:
  parentRefs:
  - name: gateway
    sectionName: http
  hostnames:
  - "cafe.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /coffee
    backendRefs:
    - name: coffee
      port: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: tea
spec:
  parentRefs:
  - name: gateway
    sectionName: http
  hostnames:
  - "cafe.example.com"
  rules:
  - matches:
    - path:
        type: Exact
        value: /tea
    backendRefs:
    - name: tea
      port: 80

Apply it using kubectl:

kubectl apply -f cafe-routes.yaml

httproute.gateway.networking.k8s.io/coffee created
httproute.gateway.networking.k8s.io/tea created

Verify the configuration

You can check that all of the expected services are available using kubectl get:

kubectl get service --all-namespaces

NAMESPACE       NAME            TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGE
default         coffee          ClusterIP   10.96.18.163    <none>        80/TCP                       2m51s
default         kubernetes      ClusterIP   10.96.0.1       <none>        443/TCP                      4m41s
default         tea             ClusterIP   10.96.169.132   <none>        80/TCP                       2m51s
kube-system     kube-dns        ClusterIP   10.96.0.10      <none>        53/UDP,53/TCP,9153/TCP       4m40s
nginx-gateway   nginx-gateway   NodePort    10.96.186.45    <none>        80:31437/TCP,443:31438/TCP   3m6s

You can also use kubectl describe on the new resources to check their status:

kubectl describe httproutes

Name:         coffee
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  gateway.networking.k8s.io/v1
Kind:         HTTPRoute
Metadata:
  Creation Timestamp:  2024-10-21T13:46:51Z
  Generation:          1
  Resource Version:    821
  UID:                 cc591089-d3aa-44d3-a851-e2bbfa285029
Spec:
  Hostnames:
    cafe.example.com
  Parent Refs:
    Group:         gateway.networking.k8s.io
    Kind:          Gateway
    Name:          gateway
    Section Name:  http
  Rules:
    Backend Refs:
      Group:
      Kind:    Service
      Name:    coffee
      Port:    80
      Weight:  1
    Matches:
      Path:
        Type:   PathPrefix
        Value:  /coffee
Status:
  Parents:
    Conditions:
      Last Transition Time:  2024-10-21T13:46:51Z
      Message:               The route is accepted
      Observed Generation:   1
      Reason:                Accepted
      Status:                True
      Type:                  Accepted
      Last Transition Time:  2024-10-21T13:46:51Z
      Message:               All references are resolved
      Observed Generation:   1
      Reason:                ResolvedRefs
      Status:                True
      Type:                  ResolvedRefs
    Controller Name:         gateway.nginx.org/nginx-gateway-controller
    Parent Ref:
      Group:         gateway.networking.k8s.io
      Kind:          Gateway
      Name:          gateway
      Namespace:     default
      Section Name:  http
Events:              <none>


Name:         tea
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  gateway.networking.k8s.io/v1
Kind:         HTTPRoute
Metadata:
  Creation Timestamp:  2024-10-21T13:46:51Z
  Generation:          1
  Resource Version:    823
  UID:                 d72d2a19-1c4d-48c4-9808-5678cff6c331
Spec:
  Hostnames:
    cafe.example.com
  Parent Refs:
    Group:         gateway.networking.k8s.io
    Kind:          Gateway
    Name:          gateway
    Section Name:  http
  Rules:
    Backend Refs:
      Group:
      Kind:    Service
      Name:    tea
      Port:    80
      Weight:  1
    Matches:
      Path:
        Type:   Exact
        Value:  /tea
Status:
  Parents:
    Conditions:
      Last Transition Time:  2024-10-21T13:46:51Z
      Message:               The route is accepted
      Observed Generation:   1
      Reason:                Accepted
      Status:                True
      Type:                  Accepted
      Last Transition Time:  2024-10-21T13:46:51Z
      Message:               All references are resolved
      Observed Generation:   1
      Reason:                ResolvedRefs
      Status:                True
      Type:                  ResolvedRefs
    Controller Name:         gateway.nginx.org/nginx-gateway-controller
    Parent Ref:
      Group:         gateway.networking.k8s.io
      Kind:          Gateway
      Name:          gateway
      Namespace:     default
      Section Name:  http
Events:              <none>

kubectl describe gateways

Name:         gateway
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  gateway.networking.k8s.io/v1
Kind:         Gateway
Metadata:
  Creation Timestamp:  2024-10-21T13:46:36Z
  Generation:          1
  Resource Version:    824
  UID:                 2ae8ec42-70eb-41a4-b249-3e47177aea48
Spec:
  Gateway Class Name:  nginx
  Listeners:
    Allowed Routes:
      Namespaces:
        From:  Same
    Hostname:  *.example.com
    Name:      http
    Port:      80
    Protocol:  HTTP
Status:
  Addresses:
    Type:   IPAddress
    Value:  10.244.0.5
  Conditions:
    Last Transition Time:  2024-10-21T13:46:51Z
    Message:               Gateway is accepted
    Observed Generation:   1
    Reason:                Accepted
    Status:                True
    Type:                  Accepted
    Last Transition Time:  2024-10-21T13:46:51Z
    Message:               Gateway is programmed
    Observed Generation:   1
    Reason:                Programmed
    Status:                True
    Type:                  Programmed
  Listeners:
    Attached Routes:  2
    Conditions:
      Last Transition Time:  2024-10-21T13:46:51Z
      Message:               Listener is accepted
      Observed Generation:   1
      Reason:                Accepted
      Status:                True
      Type:                  Accepted
      Last Transition Time:  2024-10-21T13:46:51Z
      Message:               Listener is programmed
      Observed Generation:   1
      Reason:                Programmed
      Status:                True
      Type:                  Programmed
      Last Transition Time:  2024-10-21T13:46:51Z
      Message:               All references are resolved
      Observed Generation:   1
      Reason:                ResolvedRefs
      Status:                True
      Type:                  ResolvedRefs
      Last Transition Time:  2024-10-21T13:46:51Z
      Message:               No conflicts
      Observed Generation:   1
      Reason:                NoConflicts
      Status:                False
      Type:                  Conflicted
    Name:                    http
    Supported Kinds:
      Group:  gateway.networking.k8s.io
      Kind:   HTTPRoute
      Group:  gateway.networking.k8s.io
      Kind:   GRPCRoute
Events:       <none>

Test NGINX Gateway Fabric

By configuring the cluster with the ports 31437 and 31438, there is implicit port forwarding from your local machine to NodePort, allowing for direct communication to the NGINX Gateway Fabric service.

You can use curl to test the new services by targeting the hostname (cafe.example.com) with the /coffee and /tea paths:

curl --resolve cafe.example.com:8080:127.0.0.1 http://cafe.example.com:8080/coffee

Server address: 10.244.0.6:8080
Server name: coffee-6db967495b-wk2mm
Date: 21/Oct/2024:13:52:13 +0000
URI: /coffee
Request ID: fb226a54fd94f927b484dd31fb30e747

curl --resolve cafe.example.com:8080:127.0.0.1 http://cafe.example.com:8080/tea

Server address: 10.244.0.7:8080
Server name: tea-7b7d6c947d-d4qcf
Date: 21/Oct/2024:13:52:17 +0000
URI: /tea
Request ID: 43882f2f5794a1ee05d2ea017a035ce3

See also

Last modified October 22, 2024