quickstart.md

Development Quickstart

This guide will assist you in setting up your development environment for NGINX Kubernetes Gateway, covering the steps to build, install, and execute tasks necessary for submitting pull requests. By following this guide, you'll have a fully prepared development environment that allows you to contribute to the project effectively.

Setup Your Development Environment

Follow these steps to set up your development environment.

1. Install:

   • Go

   • Docker v18.09+

   • Kind

   • git

   • GNU Make

   • yq

   • fieldalignment:

     go install golang.org/x/tools/go/analysis/passes/fieldalignment/cmd/fieldalignment@latest

2. Fork the project repository

3. Clone your repository, and install the project dependencies:

   git clone https://github.com/<YOUR-USERNAME>/nginx-kubernetes-gateway.git
   cd nginx-kubernetes-gateway
   make deps

Build the Binary and Image

Build the Binary

To build the binary, run the make build command from the project's root directory:

make build

This command will build the binary and output it to the /build/.out directory.

Build the Image

To build an NGINX Kubernetes Gateway container image from source run the following make command:

make TAG=$(whoami) container

This will build the docker image nginx-kubernetes-gateway:<your-user>.

Deploy on Kind

1. Create a kind cluster:

   make create-kind-cluster

2. Load the previously built image onto your kind cluster:

   kind load docker-image nginx-kubernetes-gateway:$(whoami)

3. Modify the image name and image pull policy for the nginx-gateway container in the NKG deployment manifest. Set the image name to the image you built in the previous step and the image pull policy to IfNotPresent, so that Kubernetes will not try to pull it from the DockerHub. Once the changes are made, follow the installation instructions to install NKG on your kind cluster.

   Alternatively, you can update the image name and pull policy by using the following command when applying deployment.yaml:

   cat deploy/manifests/deployment.yaml | sed "s|image: ghcr.io/nginxinc/nginx-kubernetes-gateway.*|image: nginx-kubernetes-gateway:$(whoami)|" | sed "s|imagePullPolicy: Always|imagePullPolicy: IfNotPresent|" | kubectl apply -f -

Run Examples

To make sure NKG is running properly, try out the examples.

Run the Unit Tests

To run all the unit tests, run the make unit-test command from the project's root directory:

make unit-test

For more details on testing, see the testing documentation.

Gateway API Conformance Testing

To run Gateway API conformance tests, please follow the instructions on this page.

Run the Linter

To lint the code, run the following make command from the project's root directory:

make lint

Note fieldalignment errors can be fixed by running: fieldalignment -fix <path-to-package>