This guide will assist you in setting up your development environment for NGINX Gateway Fabric, 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
- Build the Binary and Images
- Deploy on Kind
- Run the Unit Tests
- Gateway API Conformance Testing
- Run the Linter
- Run the Helm Linter
- Update all the generated files
Follow these steps to set up your development environment.
-
Install:
go install golang.org/x/tools/go/analysis/passes/fieldalignment/cmd/fieldalignment@latest
brew install pre-commit
-
Clone your repository with ssh, and install the project dependencies:
git clone git@github.com:<YOUR-USERNAME>/nginx-gateway-fabric.git cd nginx-gateway-fabric
and then run
pre-commit install
in the project root directory to install the git hooks.
make deps
-
Finally, add the original project repository as the remote upstream:
git remote add upstream git@github.com:nginxinc/nginx-gateway-fabric.git
The Makefile uses the GOARCH variable to build the binary and container images. The default value of GOARCH is amd64
.
If you are deploying NGINX Gateway Fabric on a kind cluster, and the architecture of your machine is not amd64
, you will want to set the GOARCH variable to the architecture of your local machine. You can find the value of GOARCH by running go env
. Export the GOARCH variable in your ~/.zshrc
or ~/.bashrc
.
echo "export GOARCH=< Your architecture (e.g. arm64 or amd64) >" >> ~/.bashrc
source ~/.bashrc
or for zsh:
echo "export GOARCH=< Your architecture (e.g. arm64 or amd64) >" >> ~/.zshrc
source ~/.zshrc
To build the binary, run the make build command from the project's root directory:
make GOARCH=$GOARCH build
This command will build the binary and output it to the /build/.out
directory.
To build the NGINX Gateway Fabric and NGINX container images from source run the following make command:
make GOARCH=$GOARCH TAG=$(whoami) build-images
This will build the docker images nginx-gateway-fabric:<your-user>
and nginx-gateway-fabric/nginx:<your-user>
.
Note: You will need a valid NGINX Plus license certificate and key named
nginx-repo.crt
andnginx-repo.key
in the root of this repo to build the NGINX Plus image.
To build the NGINX Gateway Fabric and NGINX Plus container images from source run the following make command:
make TAG=$(whoami) build-images-with-plus
This will build the docker images nginx-gateway-fabric:<your-user>
and nginx-gateway-fabric/nginx-plus:<your-user>
.
-
Create a
kind
cluster:To create a
kind
cluster with dual (IPv4 and IPv6) enabled:make create-kind-cluster
To create a
kind
cluster with IPv6 or IPv4 only, edit kind cluster config located atnginx-gateway-fabric/config/cluster/kind-cluster.yaml
:kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane networking: ipFamily: ipv6 apiServerAddress: 127.0.0.1
-
Load the previously built images onto your
kind
cluster:kind load docker-image nginx-gateway-fabric:$(whoami) nginx-gateway-fabric/nginx:$(whoami)
or
kind load docker-image nginx-gateway-fabric:$(whoami) nginx-gateway-fabric/nginx-plus:$(whoami)
-
Install Gateway API CRDs:
kubectl kustomize config/crd/gateway-api/standard | kubectl apply -f -
If you're implementing experimental Gateway API features, install Gateway API CRDs from the experimental channel:
kubectl kustomize config/crd/gateway-api/experimental | kubectl apply -f -
-
Install NGF using your custom image and expose NGF with a NodePort Service:
-
To install with Helm (where your release name is
my-release
):helm install my-release ./charts/nginx-gateway-fabric --create-namespace --wait --set service.type=NodePort --set nginxGateway.image.repository=nginx-gateway-fabric --set nginxGateway.image.tag=$(whoami) --set nginxGateway.image.pullPolicy=Never --set nginx.image.repository=nginx-gateway-fabric/nginx --set nginx.image.tag=$(whoami) --set nginx.image.pullPolicy=Never -n nginx-gateway
-
To install NGINX Plus with Helm (where your release name is
my-release
):helm install my-release ./charts/nginx-gateway-fabric --create-namespace --wait --set service.type=NodePort --set nginxGateway.image.repository=nginx-gateway-fabric --set nginxGateway.image.tag=$(whoami) --set nginxGateway.image.pullPolicy=Never --set nginx.image.repository=nginx-gateway-fabric/nginx-plus --set nginx.image.tag=$(whoami) --set nginx.image.pullPolicy=Never --set nginx.plus=true -n nginx-gateway
For more information on Helm configuration options see the Helm README.
-
To install with manifests:
The mainifests files are genarated using Helm from the examples directory. To generate a custom one you can modify the
values.yaml
file in the example you want to use with the desired values and follow the instructions about manifests generation.If the only change is the image repository and tag, you can update the
kustomization.yaml
file indeploy/
with the desired values and deployment mainifest and run the following commands:kubectl apply -f deploy/crds.yaml kubectl kustomize deploy | kubectl apply -f -
-
For more information on how to use the manifests, see the deployment manifests documentation.
To make sure NGF is running properly, try out the examples.
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.
To run Gateway API conformance tests, please follow the instructions on this page.
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>
Run the following make command from the project's root directory to lint the Helm Chart code:
make lint-helm
To update all the generated files, run the following make command from the project's root directory:
make generate-all