Skip to main content
Version: Next

Annotations

This document describes all supported annotations and their functions. You can add these annotations in the Ingress resources so that advanced features in Apache APISIX can be combined into Ingress resources.

Note all keys and values of annotations are strings, so boolean value like true and false should be represented as "true" and "false".

CORS Support#

In order to enable CORS, the annotation k8s.apisix.apache.org/enable-cors should be set to "true", also, there are some other annotations to customize the cors behavior.

  • k8s.apisix.apache.org/cors-allow-origin

This annotation controls which origins will be allowed, multiple origins join together with ,, for instance: https://foo.com,http://bar.com:8080

Default value is "*", which means all origins are allowed.

  • k8s.apisix.apache.org/cors-allow-headers

This annotation controls which headers are accepted, multiple headers join together with ,.

Default is "*", which means all headers are accepted.

  • k8s.apisix.apache.org/cors-allow-methods

This annotation controls which methods are accepted, multiple methods join together with ,.

Default is "*", which means all HTTP methods are accepted.

Allowlist Source Range#

You can specify the allowed client IP addresses or nets by the annotation k8s.apisix.apache.org/allowlist-source-range, multiple IP addresses or nets join together with ,, for instance, k8s.apisix.apache.org/allowlist-source-range: 10.0.5.0/16,127.0.0.1,192.168.3.98. Default value is empty, which means the sources are not limited.

Blocklist Source Range#

You can specify the denied client IP addresses or nets by the annotation k8s.apisix.apache.org/blocklist-source-range, multiple IP addresses or nets join together with ,, for instance, k8s.apisix.apache.org/blocklist-source-range: 127.0.0.1,172.17.0.0/16. Default value is empty, which means the sources are not limited.

Rewrite Target#

You can rewrite requests by specifying the annotation k8s.apisix.apache.org/rewrite-target or k8s.apisix.apache.org/rewrite-target-regex.

The annotation k8s.apisix.apache.org/rewrite-target controls where the request will be forwarded to.

If you want to use regex and match groups, use annotation k8s.apisix.apache.org/rewrite-target-regex and k8s.apisix.apache.org/rewrite-target-regex-template. The first annotation contains the matching rule (regex), the second one contains the rewrite rule.

Both annotations must be used together, otherwise they will be ignored.

For example, we have an Ingress matches prefix path /app, and we set k8s.apisix.apache.org/rewrite-target-regex to /app/(.*) and set k8s.apisix.apache.org/rewrite-target-regex-template to /$1.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: apisix
k8s.apisix.apache.org/rewrite-target-regex: "/app/(.*)"
k8s.apisix.apache.org/rewrite-target-regex-template: "/$1"
name: ingress-v1
spec:
rules:
- host: httpbin.org
http:
paths:
- path: /app
pathType: Prefix
backend:
service:
name: httpbin
port:
number: 80

With this Ingress, any requests with /app prefix will be forwarded to backend without the /app/ part, e.g. request /app/ip will be forwarded to /ip.

Redirect#

You can use the following annotations to control the redirect behavior.

  • k8s.apisix.apache.org/http-to-https

If this annotation set to true and the request is HTTP, it will be automatically redirected to HTTPS with 301 response code, and the URI will keep the same as client request.

For example, the following Ingress, if we set k8s.apisix.apache.org/http-to-https: "true". The client will get a response with 301 status code, and the response header Location will be https://httpbin.org/sample.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: apisix
k8s.apisix.apache.org/http-to-https: "true"
name: ingress-v1
spec:
rules:
- host: httpbin.org
http:
paths:
- path: /sample
pathType: Exact
backend:
service:
name: httpbin
port:
number: 80

Path regular expression#

You can use the follow annotations to enable path regular expression

  • k8s.apisix.apache.org/use-regex

If this annotations set to true and the PathType set to ImplementationSpecific, the path will be match as regular expression.

For example, the following Ingress. Request path with /api/*/action1 will use service1 and /api/*/action2 will be use service2

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: apisix
k8s.apisix.apache.org/use-regex: "true"
name: ingress-v1
spec:
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 websocket#

You can use the follow annotations to enable websocket

  • k8s.apisix.apache.org/enable-websocket

If this annotations set to true the route will enable websoket

For example, the following Ingress, if we set k8s.apisix.apache.org/enable-websocket: "true". /api/* route will enable websocket

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: apisix
k8s.apisix.apache.org/enable-websocket: "true"
name: ingress-v1
spec:
rules:
- host: httpbin.org
http:
paths:
- path: /api/*
pathType: ImplementationSpecific
backend:
service:
name: service1
port:
number: 80

Use ApisixPluginConfig#

You can use the following annotations to use the ApisixPluginConfig.

  • k8s.apisix.apache.org/plugin-config-name

If this annotations set to ApisixPluginConfig.metadata.name the route will use ApisixPluginConfig

ApisixPluginConfig is a resource under the same Namespace as Ingress

As an example, we attach the annotation k8s.apisix.apache.org/plugin-config-name: "echo-and-cors-apc for the following Ingress resource, so that /api/* route will enable the echo and cors plugins.

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:
kubernetes.io/ingress.class: apisix
k8s.apisix.apache.org/plugin-config-name: "echo-and-cors-apc"
name: ingress-v1
spec:
rules:
- host: httpbin.org
http:
paths:
- path: /api/*
pathType: ImplementationSpecific
backend:
service:
name: service1
port:
number: 80