Skip to main content
Version: 1.4.0

Developing for Apache APISIX Ingress Controller

This document explains how to get started with developing for Apache APISIX Ingress controller.


  • Install Go 1.13 or later, and we use go module to manage the go package dependencies.
  • Prepare an available Kubernetes cluster in your workstation, we recommend you to use KIND.
  • Install Apache APISIX in Kubernetes by Helm Chart.

Fork and Clone#

  • Fork the repository from apache/apisix-ingress-controller to your own GitHub account.
  • Clone the fork repository to your workstation.
  • Run go mod download to download modules to local cache. By the way, if you are a developer in China, we suggest you setting GOPROXY to to speed up the downloading.


cd /path/to/apisix-ingress-controller
make build
./apisix-ingress-controller version


Run unit test cases#

cd /path/to/apisix-ingress-controller
make unit-test

Run e2e test cases#

We using KIND for running e2e test cases. Please ensure kind CLI has been installed. Currently we using KIND latest version v0.11.1 and using Kubernetes v1.21.1 for testing.

cd /path/to/apisix-ingress-controller
make e2e-test

Note the running of e2e cases is somewhat slow, so please be patient.

See here to learn how to just run partial e2e cases.

Build docker image#

cd /path/to/apisix-ingress-controller
make build-image IMAGE_TAG=a.b.c

Note: The Dockerfile in this repository is only for development, not for release.

If you're coding for apisix-ingress-controller and adding some e2e test cases to verify your changes, you should push the images to the image registry that your Kubernetes cluster can access, if you're using Kind, just run the following command:

make push-images-to-kind

Run apisix-ingress-controller locally#

We assume all prerequisites above mentioned are met, what's more, since we want to run apisix-ingress-controller in bare-metal environment, please make sure both the proxy service and admin api service of Apache APISIX are exposed outside of the Kubernetes cluster, e.g. configuring them as NodePort services.

Let's assume the Admin API service address of Apache APISIX is Next launch the ingress-apisix-controller by the following command.

cd /path/to/apisix-ingress-controller
./apisix-ingress-controller ingress \
--kubeconfig /path/to/kubeconfig \
--http-listen :8080 \
--log-output stderr \
--apisix-admin-key edd1c9f034335f136f87ad84b625c8f1

Something you need to pay attention to:

  • configuring of --kubeconfig, if you are using Minikube, the file path should be ~/.kube/config.
  • configuring of --apisix-admin-key, if you have changed the admin key in Apache APISIX, also changing it here, if you disable the authentication if Apache APISIX, just removing this option.