Annotations
Annotations can be used with the native Kubernetes ingress resource to access advanced features in Apache APISIX. Alternatively, you can use APISIX's CRDs for a better experience.
This document describes all the available annotations and their uses.
note
Key-value pairs in annotations are strings. So boolean values should be reprsented as "true"
and "false"
.
#
CORSYou can enable CORS by adding the annotation as shown below:
metadata:
annotations:
k8s.apisix.apache.org/enable-cors: "true"
You can also customize the behaviour with some additional annotations as shown below.
#
Allow originsThis annotation configures which origins are allowed. Multiple origins can be added in a comma separated form.
k8s.apisix.apache.org/cors-allow-origin: "https://foo.com,http://bar.com:8080"
The default value is "*"
which means all origins are allowed.
#
Allow headersThis annotation configures which headers are allowed. Multiple headers can be added in a comma separated form.
k8s.apisix.apache.org/cors-allow-headers: "Host: https://bar.com:8080"
The default value is "*"
which means all headers are allowed.
#
Allow methodsThis annotation configures which HTTP methods are allowed. Multiple methods can be added in a comma separated form.
k8s.apisix.apache.org/cors-allow-methods: "GET,POST"
The default value is "*"
which means all methods are allowed.
#
Allowlist source rangeThis annotation can be used to specify which client IP addresses or nets are allowed. Multiple IP addresses can also be specified by separating them with commas.
k8s.apisix.apache.org/allowlist-source-range: "10.0.5.0/16,127.0.0.1,192.168.3.98"
The default value is empty which means all IP addresses are allowed.
#
Blocklist source rangeThis annotation can be used to specify which client IP addresses or nets are blocked. Multiple IP addresses can also be specified by separating them with commas.
k8s.apisix.apache.org/blocklist-source-range: "127.0.0.1,172.17.0.0/16"
The default value is empty which means no IP addresses are blocked.
#
Customized http methods
http-allow-methods
andhttp-block-methods
are mutually exclusive. If they're both set, onlyhttp-allow-methods
works
#
Allow http methodsThis annotation can be used to specify which http method are allowed. Multiple methods can also be specified by separating them with commas.
k8s.apisix.apache.org/http-allow-methods: "GET,POST"
The default value is empty which means all methods are allowed.
#
Block http methodsThis annotation can be used to specify which http method are blocked. Multiple methods can also be specified by separating them with commas.
k8s.apisix.apache.org/http-block-method: "PUT,DELETE"
The default value is empty which means no methods are blocked.
#
Rewrite targetThese annotations are used to rewrite requests.
The annotation k8s.apisix.apache.org/rewrite-target
specifies where to forward the request.
If you want to use regex and match groups, use the annotations k8s.apisix.apache.org/rewrite-target-regex
and k8s.apisix.apache.org/rewrite-target-regex-template
. The former should contain the matching rule and the latter should contain the rewrite rule. Both these annotations must be used together.
The example below configures the Ingress to forward all requests with /app
prefix to the backend removing the /app/
part. So, a request to /app/ip
will be forwarded to /ip
.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
k8s.apisix.apache.org/rewrite-target-regex: "/app/(.*)"
k8s.apisix.apache.org/rewrite-target-regex-template: "/$1"
name: ingress-v1
spec:
ingressClassName: apisix
rules:
- host: httpbin.org
http:
paths:
- path: /app
pathType: Prefix
backend:
service:
name: httpbin
port:
number: 80
#
HTTP to HTTPSThis annotation is used to redirect HTTP requests to HTTPS with a 301
status code and with the same URI as the original request.
The example below will redirect HTTP requests with a 301
status code with a response header Location:https://httpbin.org/sample
.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
k8s.apisix.apache.org/http-to-https: "true"
name: ingress-v1
spec:
ingressClassName: apisix
rules:
- host: httpbin.org
http:
paths:
- path: /sample
pathType: Exact
backend:
service:
name: httpbin
port:
number: 80
#
Regex pathsThis annotation is can be used to enable regular expressions in path matching.
With this annotation set to "true"
and PathType
set to ImplementationSpecific
, the path matching will use regex. The example below configures Ingress to route requests to path /api/*/action1
to service1
and /api/*/action2
to service2
.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
k8s.apisix.apache.org/use-regex: "true"
name: ingress-v1
spec:
ingressClassName: apisix
rules:
- host: httpbin.org
http:
paths:
- path: /api/.*/action1
pathType: ImplementationSpecific
backend:
service:
name: service1
port:
number: 80
- path: /api/.*/action2
pathType: ImplementationSpecific
backend:
service:
name: service2
port:
number: 80
#
Enable websocketThis annotation is use to enable websocket connections.
In the example below, the annotation will enable websocket connections on the route /api/*
:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
k8s.apisix.apache.org/enable-websocket: "true"
name: ingress-v1
spec:
ingressClassName: apisix
rules:
- host: httpbin.org
http:
paths:
- path: /api/*
pathType: ImplementationSpecific
backend:
service:
name: service1
port:
number: 80
#
Response RewriteYou can enable Response Rewrite by adding the annotation as shown below:
metadata:
annotations:
k8s.apisix.apache.org/enable-response-rewrite: "true"
You can customize the behaviour with some additional annotations as shown below.
#
New HTTP status codeThis annotation configures the new HTTP status code in the response.
k8s.apisix.apache.org/response-rewrite-status-code: "404"
If unset, falls back to the original status code.
#
New bodyThis annotation configures the new body in the response.
k8s.apisix.apache.org/response-rewrite-body: "bar-body"
#
Body Base64When set, the body of the request will be decoded before writing to the client.
k8s.apisix.apache.org/response-rewrite-body-base64: "true"
The default value is "false"
.
#
Using ApisixPluginConfig resourceThis annotation is used to enable a defined ApisixPluginConfig resource on a particular route.
The value of the annotation should be the name of the created ApisixPluginConfig
resource.
The example below shows how this is configured. The created route /api/*
will have the echo and cors Plugins enabled as has the resource configured through annotations:
apiVersion: apisix.apache.org/v2
kind: ApisixPluginConfig
metadata:
name: echo-and-cors-apc
spec:
plugins:
- name: echo
enable: true
config:
before_body: "This is the preface"
after_body: "This is the epilogue"
headers:
X-Foo: v1
X-Foo2: v2
- name: cors
enable: true
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
k8s.apisix.apache.org/plugin-config-name: "echo-and-cors-apc"
name: ingress-v1
spec:
ingressClassName: apisix
rules:
- host: httpbin.org
http:
paths:
- path: /api/*
pathType: ImplementationSpecific
backend:
service:
name: service1
port:
number: 80
#
Upstream schemeThe scheme used when communicating with the Upstream. this value can be one of 'http', 'https', 'grpc', 'grpcs'. Defaults to 'http'.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: apisix
k8s.apisix.apache.org/upstream-scheme: grpcs
name: ingress-v1
spec:
rules:
- host: e2e.apisix.local
http:
paths:
- path: /helloworld.Greeter/SayHello
pathType: ImplementationSpecific
backend:
service:
name: test-backend-service-e2e-test
port:
number: 50053
#
Cross-namespace referencesThis annotation can be used to route to services in a different namespace.
In the example configuration below, the Ingress resource in the default
namespace references the httpbin service in the test
namespace:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
k8s.apisix.apache.org/svc-namespace: test
name: ingress-v1-svc
namespace: default
spec:
ingressClassName: apisix
rules:
- host: httpbin.org
http:
paths:
- path: /ip
pathType: Exact
backend:
service:
name: httpbin
port:
number: 80