Development
This document walks through how you can set up your development environment to contribute to APISIX Ingress controller.
#
PrerequisitesBefore you get started make sure you have:
- Installed Go 1.19 or later
- A Kubernetes cluster available. We recommend using kind.
- Installed APISIX in Kubernetes using Helm.
#
Fork and clone- Fork the repository apache/apisix-ingress-controller to your GitHub account
- Clone the fork to your workstation.
- Run
go mod download
to download the required modules.
tip
If you are in China, you can speed up the downloads by setting GOPROXY
to https://goproxy.cn
.
#
Build from sourceTo build APISIX Ingress controller, run the command below on the root of the project:
make build
Now you can run it by:
./apisix-ingress-controller version
#
Making changesPrior to opening a pull request with changes or new features, please open an issue.
Make sure that the license, code style, and document format are consistent with the project specification. You can do this by running:
make update-all
Your pull requests will more likely to be accepted if:
- All tests are passing and tests are included for new functionalities
- README and documentation is updated with the chages
- PR is linked to the issue with semantic keywords ("fixes #145")
- Has detailed PR descriptions and good commit messages
#
Running testsTo run unit tests:
make unit-test
To run end-to-end tests, you need to install kind.
Currently, we use Kind version 0.11.1
and Kubernetes version 1.21.1
for running the tests.
make e2e-test-local
note
End-to-end tests are comprehensive and takes time to run.
See focused specs to learn how you can run partial tests.
To run e2e tests on any changes, you can build a Docker image and push it to a registry that the Kubernetes cluster can access:
make build-image IMAGE_TAG=a.b.c
make push-images IMAGE_TAG=a.b.c
#
Running locallyMake sure to expose both the APISIX proxy and the Admin API to outside the Kubernetes cluster. You can use NodePort service or use port-forward
as shown below:
Also, we can also use port-forward
to expose the Admin API port of Apache APISIX Pod. The default port of Apache APISIX Admin API is 9180, next I'll expose the local port 127.0.0.1:9180
:
kubectl port-forward -n ${namespace of Apache APISIX} ${Pod name of Apache APISIX} 9180:9180
This will expose the default 9180
port of the Admin API to outside the cluster.
You can now run APISIX Ingress controller by:
cd /path/to/apisix-ingress-controller
./apisix-ingress-controller ingress \
--kubeconfig /path/to/kubeconfig \
--http-listen :8080 \
--log-output stderr \
--default-apisix-cluster-base-url http://127.0.0.1:9180/apisix/admin \
--default-apisix-cluster-admin-key edd1c9f034335f136f87ad84b625c8f1
note
- If you are using minikube, the path to kubeconfig should be
~/.kube/config
. - If you have changed the default Admin API key, you have to pass it in the
--default-apisix-cluster-admin-key
flag. You can remove the flag if you have disabled authentication.