From 92a1633f0681fef686ea6e3de5149e8d52853353 Mon Sep 17 00:00:00 2001 From: Navendu Pottekkat Date: Fri, 21 Oct 2022 12:40:42 +0530 Subject: [PATCH 1/3] docs: update annotations page Signed-off-by: Navendu Pottekkat --- docs/en/latest/annotations.md | 271 +++++++++++++++++++++++++ docs/en/latest/concepts/annotations.md | 259 ----------------------- docs/en/latest/config.json | 7 +- 3 files changed, 276 insertions(+), 261 deletions(-) create mode 100644 docs/en/latest/annotations.md delete mode 100644 docs/en/latest/concepts/annotations.md diff --git a/docs/en/latest/annotations.md b/docs/en/latest/annotations.md new file mode 100644 index 0000000000..2936ac4d01 --- /dev/null +++ b/docs/en/latest/annotations.md @@ -0,0 +1,271 @@ +--- +title: Annotations +keywords: + - APISIX ingress + - Apache APISIX + - Kubernetes ingress + - Annotations +description: Guide to using additional features of APISIX Ingress with annotations. +--- + + + +Annotations can be used with the [native Kubernetes ingress resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) to access advanced features in Apache APISIX. Alternatively, you can use [APISIX's CRDs](https://apisix.apache.org/docs/ingress-controller/concepts/apisix_route/) 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"`. + +::: + +## CORS + +You can enable [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) by adding the annotation as shown below: + +```yaml +metadata: + annotations: + k8s.apisix.apache.org/enable-cors: "true" +``` + +You can also customize the behaviour with some additional annotations as shown below. + +### Allow origins + +This annotation configures which origins are allowed. Multiple origins can be added in a comma separated form. + +```yaml +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 headers + +This annotation configures which headers are allowed. Multiple headers can be added in a comma separated form. + +```yaml +k8s.apisix.apache.org/cors-allow-headers: "Host: https://bar.com:8080" +``` + +The default value is `"*"` which means all headers are allowed. + +### Allow methods + +This annotation configures which HTTP methods are allowed. Multiple methods can be added in a comma separated form. + +```yaml +k8s.apisix.apache.org/cors-allow-methods: "GET,POST" +``` + +The default value is `"*"` which means all methods are allowed. + +## Allowlist source range + +This 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. + +```yaml +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 range + +This 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. + +```yaml +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. + +## Rewrite target + +These 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`. + +```yaml +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 +``` + +## HTTP to HTTPS + +This 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`. + +```yaml +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 +``` + +## Regex paths + +This 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`. + +```yaml +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 + +This annotation is use to enable websocket connections. + +In the example below, the annotation will enable websocket connections on the route `/api/*`: + +```yaml +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 +``` + +## Using ApisixPluginConfig resource + +This annotation is used to enable a defined [ApisixPluginConfig](https://apisix.apache.org/docs/ingress-controller/references/apisix_pluginconfig_v2/) 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](https://apisix.apache.org/docs/apisix/plugins/echo/) and [cors](https://apisix.apache.org/docs/apisix/plugins/cors/) Plugins enabled as has the resource configured through annotations: + +```yaml +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 +``` diff --git a/docs/en/latest/concepts/annotations.md b/docs/en/latest/concepts/annotations.md deleted file mode 100644 index 895b470145..0000000000 --- a/docs/en/latest/concepts/annotations.md +++ /dev/null @@ -1,259 +0,0 @@ ---- -title: Annotations ---- - - - -This document describes all supported annotations and their functions. You can add these annotations in the [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) resources so that advanced features in [Apache APISIX](https://apisix.apache.org) can be combined into [Ingress](https://kubernetes.io/docs/concepts/services-networking/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](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), 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`. - -```yaml -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`. - -```yaml -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` - -```yaml -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 - -```yaml -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](https://apisix.apache.org/docs/apisix/plugins/echo/) and [cors](https://apisix.apache.org/docs/apisix/plugins/cors/) plugins. - -```yaml -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 -``` diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json index bff5ed08b7..d21b0130e2 100644 --- a/docs/en/latest/config.json +++ b/docs/en/latest/config.json @@ -60,10 +60,13 @@ "concepts/apisix_route", "concepts/apisix_upstream", "concepts/apisix_tls", - "concepts/apisix_cluster_config", - "concepts/annotations" + "concepts/apisix_cluster_config" ] }, + { + "type": "doc", + "id": "annotations" + }, { "type": "doc", "id": "design" From 4cc6e2d419620260bd51d26c2d96743afd6e3333 Mon Sep 17 00:00:00 2001 From: Navendu Pottekkat Date: Fri, 21 Oct 2022 13:09:30 +0530 Subject: [PATCH 2/3] fix lint errors Signed-off-by: Navendu Pottekkat --- docs/en/latest/annotations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/latest/annotations.md b/docs/en/latest/annotations.md index 2936ac4d01..d70f42977a 100644 --- a/docs/en/latest/annotations.md +++ b/docs/en/latest/annotations.md @@ -27,7 +27,7 @@ description: Guide to using additional features of APISIX Ingress with annotatio # --> -Annotations can be used with the [native Kubernetes ingress resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) to access advanced features in Apache APISIX. Alternatively, you can use [APISIX's CRDs](https://apisix.apache.org/docs/ingress-controller/concepts/apisix_route/) for a better experience. +Annotations can be used with the [native Kubernetes ingress resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) to access advanced features in Apache APISIX. Alternatively, you can use [APISIX's CRDs](https://apisix.apache.org/docs/ingress-controller/concepts/apisix_route) for a better experience. This document describes all the available annotations and their uses. @@ -225,7 +225,7 @@ spec: ## Using ApisixPluginConfig resource -This annotation is used to enable a defined [ApisixPluginConfig](https://apisix.apache.org/docs/ingress-controller/references/apisix_pluginconfig_v2/) resource on a particular route. +This annotation is used to enable a defined [ApisixPluginConfig](https://apisix.apache.org/docs/ingress-controller/references/apisix_pluginconfig_v2) resource on a particular route. The value of the annotation should be the name of the created `ApisixPluginConfig` resource. From c905281c5ec413c8acb5b24aa18a6394cffc073c Mon Sep 17 00:00:00 2001 From: Navendu Pottekkat Date: Mon, 24 Oct 2022 10:08:57 +0530 Subject: [PATCH 3/3] revert moving annotations page Signed-off-by: Navendu Pottekkat --- docs/en/latest/{ => concepts}/annotations.md | 0 docs/en/latest/config.json | 7 ++----- 2 files changed, 2 insertions(+), 5 deletions(-) rename docs/en/latest/{ => concepts}/annotations.md (100%) diff --git a/docs/en/latest/annotations.md b/docs/en/latest/concepts/annotations.md similarity index 100% rename from docs/en/latest/annotations.md rename to docs/en/latest/concepts/annotations.md diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json index d21b0130e2..bff5ed08b7 100644 --- a/docs/en/latest/config.json +++ b/docs/en/latest/config.json @@ -60,13 +60,10 @@ "concepts/apisix_route", "concepts/apisix_upstream", "concepts/apisix_tls", - "concepts/apisix_cluster_config" + "concepts/apisix_cluster_config", + "concepts/annotations" ] }, - { - "type": "doc", - "id": "annotations" - }, { "type": "doc", "id": "design"