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-conifg-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-conifg-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-conifg-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