This document contains instructions for the tutorial APISIX in Kubernetes. For a detailed guide, see the series Hands-On With Apache APISIX Ingress.
Before you proceed to the tutorial, make sure you have:
- Access to a Kubernetes cluster. This tutorial uses minikube for creating a local cluster.
- Install and configure kubectl for communicating with the Kubernetes cluster.
- Install Helm to deploy APISIX.
APISIX and APISIX Ingress controller can be installed using Helm:
helm repo add apisix https://charts.apiseven.com
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
kubectl create ns ingress-apisix
helm install apisix apisix/apisix \
--set gateway.type=NodePort \
--set ingress-controller.enabled=true \
--namespace ingress-apisix \
--set ingress-controller.config.apisix.serviceNamespace=ingress-apisix
kubectl get pods --namespace ingress-apisixIf you are using minikube, you can expose APISIX by running:
minikube service apisix-gateway --url -n ingress-apisixYou can use the shown URL to access apisix-gateway service.
Our sample application, bare-minimum-api can be installed in Kubernetes by running:
kubectl run bare-minimum-api-v1 --image navendup/bare-minimum-api --port 8080 -- 8080 v1.0
kubectl expose pod bare-minimum-api-v1 --port 8080
kubectl run bare-minimum-api-v2 --image navendup/bare-minimum-api --port 8080 -- 8080 v2.0
kubectl expose pod bare-minimum-api-v2 --port 8080The ApisixRoute resource will create a Route to direct traffic between the two "versions" of our sample application (sample-route-crd.yaml):
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: api-routes
spec:
http:
- name: route-1
match:
hosts:
- local.navendu.me
paths:
- /v1
backends:
- serviceName: bare-minimum-api-v1
servicePort: 8080
- name: route-2
match:
hosts:
- local.navendu.me
paths:
- /v2
backends:
- serviceName: bare-minimum-api-v2
servicePort: 8080You can then apply this configuration:
kubectl apply -f sample-route-crd.yamlHere is the same configuration using the default Kubernetes Ingress resource (sample-route-ingress.yaml):
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: api-routes
spec:
ingressClassName: apisix
rules:
- host: local.navendu.me
http:
paths:
- backend:
service:
name: bare-minimum-api-v1
port:
number: 8080
path: /v1
pathType: Exact
- backend:
service:
name: bare-minimum-api-v2
port:
number: 8080
path: /v2
pathType: ExactYou can send a request to APISIX and it will be routed to the backend service based on the created Route:
curl http://127.0.0.1:51538/v2 -H 'host:local.navendu.me'You can delete this Route using kubectl:
kubectl delete -f sample-route-crd.yamlYou can configure a canary release with the ApisixRoute resource (canary-release-crd.yaml):
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: canary-release
spec:
http:
- name: route-v1
match:
paths:
- /*
backends:
- serviceName: bare-minimum-api-v1
servicePort: 8080
weight: 100
- serviceName: bare-minimum-api-v2
servicePort: 8080
weight: 0kubectl apply -f canary-release-crd.yamlYou can adjust weights and test how the traffic is split between the two services:
curl http://127.0.0.1:51538/api -H 'host:local.navendu.me'The annotation k8s.apisix.apache.org/allowlist-source-range will only allow the whitelisted IP addresses to access the service (annotation-ingress.yaml):
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: api-routes
annotations:
k8s.apisix.apache.org/allowlist-source-range: "172.17.0.1"
spec:
ingressClassName: apisix
rules:
- host: local.navendu.me
http:
paths:
- backend:
service:
name: bare-minimum-api-v1
port:
number: 8080
path: /v1
pathType: Exact
- backend:
service:
name: bare-minimum-api-v2
port:
number: 8080
path: /v2
pathType: Exactkubectl apply -f annotation-ingress.yamlThe limit-count Plugin limits the number of requests to your service (limit-count-crd.yaml):
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: method-route
spec:
http:
- name: method
match:
hosts:
- local.navendu.me
paths:
- /api
backends:
- serviceName: bare-minimum-api-v1
servicePort: 8080
weight: 50
- serviceName: bare-minimum-api-v2
servicePort: 8080
weight: 50
plugins:
- name: limit-count
enable: true
config:
count: 10
time_window: 10You can test by sending multiple requests:
for i in {1..20}
do
curl http://127.0.0.1:57761/api -H 'host:local.navendu.me'
doneThe Kubernetes Gateway API also works with Apache APISIX Ingress.
First you have to enable it. You can do this while installing APISIX via Helm:
helm repo add apisix https://charts.apiseven.com
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
kubectl create ns ingress-apisix
helm install apisix apisix/apisix --namespace ingress-apisix \
--set gateway.type=NodePort \
--set ingress-controller.enabled=true \
--set ingress-controller.config.apisix.serviceNamespace=ingress-apisix \
--set ingress-controller.config.kubernetes.enableGatewayAPI=trueYou also have to install the Gateway API CRDs as they are not installed by default:
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.5.0/standard-install.yamlapiVersion: gateway.networking.k8s.io/v1alpha2
kind: HTTPRoute
metadata:
name: canary-release
spec:
hostnames:
- local.navendu.me
rules:
- backendRefs:
- name: bare-minimum-api-v1
port: 8080
weight: 50
- name: bare-minimum-api-v2
port: 8080
weight: 50You can learn more from the series Hands-On With Apache APISIX Ingress.