diff --git a/.github/actions/markdown-link-check b/.github/actions/markdown-link-check new file mode 160000 index 000000000..0524e79d8 --- /dev/null +++ b/.github/actions/markdown-link-check @@ -0,0 +1 @@ +Subproject commit 0524e79d8d7d1606112722dd7a3b5f5ce367de3e diff --git a/.github/actions/paths-filter b/.github/actions/paths-filter new file mode 160000 index 000000000..de90cc6fb --- /dev/null +++ b/.github/actions/paths-filter @@ -0,0 +1 @@ +Subproject commit de90cc6fb38fc0963ad72b210f1f284cd68cea36 diff --git a/.github/workflows/golangci-lint.yml b/.github/workflows/golangci-lint.yml index 0b41e3a4a..1da0c7a56 100644 --- a/.github/workflows/golangci-lint.yml +++ b/.github/workflows/golangci-lint.yml @@ -60,7 +60,7 @@ jobs: make generate-crd-docs - name: Check CRD Docs Diff run: | - if ! git diff --exit-code -- docs/crd/api.md; then - echo "docs/crd/api.md has changed. Please run 'make generate-crd-docs' and commit the updated file." + if ! git diff --exit-code -- docs/en/latest/reference/api-reference.md; then + echo "docs/en/latest/reference/api-reference.md has changed. Please run 'make generate-crd-docs' and commit the updated file." exit 1 fi diff --git a/.github/workflows/lint-checker.yml b/.github/workflows/lint-checker.yml index ec2c3b4ca..c56a8bbfe 100644 --- a/.github/workflows/lint-checker.yml +++ b/.github/workflows/lint-checker.yml @@ -29,13 +29,48 @@ on: - release-v2-dev jobs: + changes: + runs-on: ubuntu-latest + outputs: + docs: ${{ steps.filter.outputs.docs }} + go: ${{ steps.filter.outputs.go }} + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + submodules: recursive + + - uses: ./.github/actions/paths-filter + id: filter + with: + token: ${{ secrets.GITHUB_TOKEN }} + filters: | + docs: + - 'docs/**/*' + - '*.md' + go: + - '*.go' + - '**/*.go' + - 'go.mod' + - 'go.sum' + - 'Makefile' + - 'Dockerfile' + - 'test/e2e/**/*' + - 'conf/**' + - 'utils/**' + - ".github/**" + run-test: + needs: changes + if: | + (needs.changes.outputs.go == 'true') + runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Go Env uses: actions/setup-go@v4 with: - go-version: '1.21' + go-version: "1.23" - name: run gofmt working-directory: ./ run: | @@ -46,6 +81,9 @@ jobs: exit 1 fi markdownlint: + needs: changes + if: | + (needs.changes.outputs.docs == 'true') name: 🍇 Markdown runs-on: ubuntu-latest steps: @@ -55,8 +93,15 @@ jobs: with: node-version: '20.7.x' - run: npm install -g markdownlint-cli@0.36.0 - - run: markdownlint '**/*.md' --ignore node_modules --ignore CHANGELOG.md --ignore docs/en/latest/references/v2.md + - run: | + markdownlint '**/*.md' \ + --ignore node_modules \ + --ignore CHANGELOG.md \ + --ignore docs/en/latest/reference/api-reference.md markdown-link-check: + needs: changes + if: | + (needs.changes.outputs.docs == 'true') runs-on: ubuntu-latest name: Check Markdown links steps: @@ -68,8 +113,8 @@ jobs: use-quiet-mode: 'yes' use-verbose-mode: 'yes' config-file: 'link-check-config.json' - folder-path: 'docs/en' - file-path: './README.md, ./install.md, ./test/e2e/README.md' + folder-path: 'docs' + file-path: './README.md' max-depth: -1 file-extension: ".md" check-modified-files-only: "no" diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 000000000..79e7228a5 --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,37 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +# MD004/ul-style Unordered list style +MD004: false + +# MD013 Line length +MD013: false + +#MD029/ol-prefix Ordered list item prefix +MD029: false + +# MD033 Inline HTML +MD033: false + +# MD036/no-emphasis-as-heading/no-emphasis-as-header Emphasis used instead of a heading +MD036: false + +MD041: false + +# MD024 +no-duplicate-heading: + siblings_only: true diff --git a/Makefile b/Makefile index 18ed521fc..2719fc66b 100644 --- a/Makefile +++ b/Makefile @@ -41,7 +41,7 @@ E2E_NODES ?= 2 CRD_REF_DOCS_VERSION ?= v0.1.0 CRD_REF_DOCS ?= $(LOCALBIN)/crd-ref-docs CRD_DOCS_CONFIG ?= docs/assets/crd/config.yaml -CRD_DOCS_OUTPUT ?= docs/en/latest/api-reference.md +CRD_DOCS_OUTPUT ?= docs/en/latest/reference/api-reference.md CRD_DOCS_TEMPLATE ?= docs/assets/template export KUBECONFIG = /tmp/$(KIND_NAME).kubeconfig diff --git a/README.md b/README.md index c6ec3f869..705b47d90 100644 --- a/README.md +++ b/README.md @@ -81,19 +81,3 @@ Users can just run kubectl apply -f to install the project ```sh kubectl apply -f dist/install.yaml ``` - -## License - -Copyright 2024. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. diff --git a/docs/assets/template/gv_details.tpl b/docs/assets/template/gv_details.tpl index 611ca1c9b..eae500cf7 100644 --- a/docs/assets/template/gv_details.tpl +++ b/docs/assets/template/gv_details.tpl @@ -39,7 +39,7 @@ ### Types -In this section you will find types that the CRDs rely on. +This section describes the types used by the CRDs. {{- /* Display Types that are not exported Kinds */ -}} {{- range $typ := $gv.SortedTypes -}} diff --git a/docs/assets/template/gv_list.tpl b/docs/assets/template/gv_list.tpl index d723151aa..974599d03 100644 --- a/docs/assets/template/gv_list.tpl +++ b/docs/assets/template/gv_list.tpl @@ -22,11 +22,11 @@ --- title: Custom Resource Definitions API Reference -slug: /reference/apisix-ingress-controller/crd-reference +slug: /reference/apisix-ingress-controller/api-reference description: Explore detailed reference documentation for the custom resource definitions (CRDs) supported by the APISIX Ingress Controller. --- -This document provides the API resource description the APISIX Ingress Controller custom resource definitions (CRDs). +This document provides the API resource description for the APISIX Ingress Controller custom resource definitions (CRDs). ## Packages {{- range $groupVersions }} diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json index 5094cb52b..99f0924e8 100644 --- a/docs/en/latest/config.json +++ b/docs/en/latest/config.json @@ -3,7 +3,18 @@ "sidebar": [ { "type": "doc", - "id": "getting-started" + "id": "overview" + }, + { + "type": "category", + "label": "Getting Started", + "items": [ + "getting-started/get-apisix-ingress-controller", + "getting-started/configure-routes", + "getting-started/load-balancing", + "getting-started/key-authentication", + "getting-started/rate-limiting" + ] }, { "type": "category", @@ -23,8 +34,12 @@ "id": "developer-guide" }, { - "type": "doc", - "id": "api-reference" + "type": "category", + "label": "Reference", + "items": [ + "reference/api-reference", + "reference/example" + ] }, { "type": "doc", diff --git a/docs/en/latest/getting-started/configure-routes.md b/docs/en/latest/getting-started/configure-routes.md new file mode 100644 index 000000000..e248e981d --- /dev/null +++ b/docs/en/latest/getting-started/configure-routes.md @@ -0,0 +1,198 @@ +--- +title: Configure Routes +keywords: + - APISIX ingress + - Apache APISIX + - Kubernetes ingress +description: Learn how to create routes in APISIX using APISIX Ingress controller to forward client to upstream services. +--- + + + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Apache APISIX provides flexible gateway management capabilities based on routes, in which routing paths and target upstreams are defined. + +This tutorial guides you through creating a Route using the APISIX Ingress Controller and verifying its behavior. You’ll configure a Route to a sample Upstream pointing to an httpbin service, then send a request to observe how APISIX proxies the traffic. + +## Prerequisites + +1. Complete [Get APISIX and APISIX Ingress Controller](./get-apisix-ingress-controller.md). + +## Set Up a Sample Upstream + +Install the httpbin example application on the cluster to test the configuration: + +```bash +kubectl apply -f https://raw.githubusercontent.com/apache/apisix-ingress-controller/refs/heads/v2.0.0/examples/httpbin/deployment.yaml +``` + +## Configure a Route + +In this section, you will create a Route that forwards client requests to the httpbin example application, an HTTP request and response service. + +You can use either Gateway API, Ingress, or APISIX CRD resources to configure the route. + +:::important + +If you are using Gateway API, you should first configure the GatewayClass and Gateway resources: + +
+ +Show configuration + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GatewayClass +metadata: + name: apisix +spec: + controllerName: apisix.apache.org/apisix-ingress-controller +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: apisix +spec: + gatewayClassName: apisix + listeners: + - name: http + protocol: HTTP + port: 80 + infrastructure: + parametersRef: + group: apisix.apache.org + kind: GatewayProxy + name: apisix-config +``` + +
+ +If you are using Ingress or APISIX custom resources, you can proceed without additional configuration. + +::: + +Create a Kubernetes manifest file for a Route that proxy requests to httpbin: + + + + + +```yaml title="httpbin-route.yaml" +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: getting-started-ip +spec: + parentRefs: + - name: apisix + rules: + - matches: + - path: + type: Exact + value: /ip + backendRefs: + - name: httpbin + port: 80 +``` + + + + + +```yaml title="httpbin-route.yaml" +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: getting-started-ip +spec: + ingressClassName: apisix + rules: + - http: + paths: + - backend: + service: + name: httpbin + port: + number: 80 + path: /ip + pathType: Exact +``` + + + + + +```yaml title="httpbin-route.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: getting-started-ip +spec: + ingressClassName: apisix + http: + - name: getting-started-ip + match: + paths: + - /ip + backends: + - serviceName: httpbin + servicePort: 80 +``` + + + + + +Apply the configurations to your cluster: + +```shell +kubectl apply -f httpbin-route.yaml +``` + +## Verify + +Expose the service port to your local machine by port forwarding: + +```shell +kubectl port-forward svc/apisix-gateway 9080:80 & +``` + +Send a request to the Route: + +```shell +curl "http://127.0.0.1:9080/ip" +``` + +You should see a response similar to the following: + +```json +{ + "origin": "127.0.0.1" +} +``` diff --git a/docs/en/latest/getting-started/get-apisix-ingress-controller.md b/docs/en/latest/getting-started/get-apisix-ingress-controller.md new file mode 100644 index 000000000..fd977d1aa --- /dev/null +++ b/docs/en/latest/getting-started/get-apisix-ingress-controller.md @@ -0,0 +1,135 @@ +--- +title: Get APISIX and APISIX Ingress Controller +keywords: + - APISIX ingress + - Apache APISIX + - Kubernetes ingress +description: Learn how to quickly install and set up Apache APISIX Ingres Controller. +--- + + + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +APISIX Ingress Controller is a [Kubernetes ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) using [Apache APISIX](https://apisix.apache.org) as the high performance reverse proxy. + +APISIX Ingress Controller can be configured using the native Kubernetes Ingress or Gateway API, as well as with APISIX’s own declarative and easy-to-use custom resources. The controller translates these resources into APISIX configuration. + +This tutorial series walks you through how to quickly get started with APISIX on a [kind](https://kind.sigs.k8s.io) Kubernetes cluster and use the APISIX Ingress Controller to manage resources. + +## Prerequisites + +* Install [Docker](https://docs.docker.com/get-docker/) as a dependency of [kind](https://kind.sigs.k8s.io). +* Install [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) to start a local Kubernetes cluster, or use any existing Kubernetes cluster (version 1.26+). +* Install [Helm](https://helm.sh/docs/intro/install/) (version 3.8+). +* Install [kubectl](https://kubernetes.io/docs/tasks/tools/) to run commands against Kubernetes clusters. + +## Create a Cluster and Configure Namespace + +In this section, you will be creating a kind cluster and configuring the namespace. Skip to [the next section](#install-apisix-and-apisix-ingress-controller-standalone-api-driven-mode) if you already have an existing cluster and a corresponding namspace. + +Ensure you have Docker running and start a kind cluster: + +```shell +kind create cluster +``` + +Create a new namespace `ingress-apisix`: + +```shell +kubectl create namespace ingress-apisix +``` + +Set the namespace to `ingress-apisix` to avoid specifying it explicitly in each subsequent command: + +```shell +kubectl config set-context --current --namespace=ingress-apisix +``` + +## Install APISIX and APISIX Ingress Controller (Standalone API-driven mode) + +Install the Gateway API CRDs, [APISIX Standalone API-driven mode](https://apisix.apache.org/docs/apisix/deployment-modes/#api-driven-experimental), and APISIX Ingress Controller: + +```bash +helm repo add apisix https://charts.apiseven.com +helm repo update + +helm install apisix \ + --namespace ingress-apisix \ + --create-namespace \ + --set apisix.deployment.role=traditional \ + --set apisix.deployment.role_traditional.config_provider=yaml \ + --set etcd.enabled=false \ + --set ingress-controller.enabled=true \ + --set ingress-controller.config.provider.type=apisix-standalone \ + --set ingress-controller.apisix.adminService.namespace=ingress-apisix \ + --set ingress-controller.gatewayProxy.createDefault=true \ + apisix/apisix +``` + +More details on the installation can be found in the [Installation Guide](../install.md). + +## Verify Installation + +Check the statuses of resources in the current namespace: + +```shell +kubectl get all +``` + +You should wait for all pods to be running before proceeding: + +```text +NAME READY STATUS RESTARTS AGE +pod/apisix-7c5fb8d546-gtfqn 1/1 Running 0 113s +pod/apisix-ingress-controller-56c46fd54f-f8fxt 1/1 Running 0 113s + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +service/apisix-admin ClusterIP 10.96.174.119 9180/TCP 113s +service/apisix-gateway NodePort 10.96.231.33 80:31321/TCP 113s +service/apisix-metrics-service ClusterIP 10.96.77.248 8443/TCP 113s + +NAME READY UP-TO-DATE AVAILABLE AGE +deployment.apps/apisix 1/1 1 1 113s +deployment.apps/apisix-ingress-controller 1/1 1 1 113s + +NAME DESIRED CURRENT READY AGE +replicaset.apps/apisix-7c5fb8d546 1 1 1 113s +replicaset.apps/apisix-ingress-controller-56c46fd54f 1 1 1 113s +``` + +To verify the installed APISIX version, map port `80` of the `apisix-gateway` service to port `8080` on the local machine: + +```shell +kubectl port-forward svc/apisix-gateway 9080:80 & +``` + +Send a request to the gateway: + +```shell +curl -sI "http://127.0.0.1:9080" | grep Server +``` + +If everything is ok, you should see the APISIX version: + +```text +Server: APISIX/x.x.x +``` diff --git a/docs/en/latest/getting-started/key-authentication.md b/docs/en/latest/getting-started/key-authentication.md new file mode 100644 index 000000000..0c7e38e84 --- /dev/null +++ b/docs/en/latest/getting-started/key-authentication.md @@ -0,0 +1,250 @@ +--- +title: Key Authentication +keywords: + - APISIX ingress + - Apache APISIX + - Kubernetes ingress +description: Explore how to configure key authentication in APISIX using APISIX Ingress Controller, which implement access control to your APIs. +--- + + + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +APISIX has a flexible plugin extension system and a number of existing plugins for user authentication and authorization. + +In this tutorial, you will create a Consumer, configure its key authentication Credential, and enable key authentication on a route, using APISIX Ingress Controller. + +## Prerequisite + +1. Complete [Get APISIX and APISIX Ingress Controller](./get-apisix-ingress-controller.md). + +## Configure Key Authentication + +For demonstration purpose, you will be creating a route to the [publicly hosted httpbin services](https://httpbin.org). If you would like to proxy requests to services on Kubernetes, please modify accordingly. + +:::important + +If you are using Gateway API, you should first configure the GatewayClass and Gateway resources: + +
+ +Show configuration + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GatewayClass +metadata: + name: apisix +spec: + controllerName: apisix.apache.org/apisix-ingress-controller +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: apisix +spec: + gatewayClassName: apisix + listeners: + - name: http + protocol: HTTP + port: 80 + infrastructure: + parametersRef: + group: apisix.apache.org + kind: GatewayProxy + name: apisix-config +``` + +
+ +If you are using Ingress or APISIX custom resources, you can proceed without additional configuration. + +::: + + + + + +Create a Kubernetes manifest file to configure a consumer: + +```yaml title="consumer.yaml" +apiVersion: apisix.apache.org/v1alpha1 +kind: Consumer +metadata: + name: tom +spec: + gatewayRef: + name: apisix + credentials: + - type: key-auth + name: primary-key + config: + key: secret-key +``` + +Create a Kubernetes manifest file to configure a route and enable key authentication: + +```yaml title="httpbin-route.yaml" +apiVersion: v1 +kind: Service +metadata: + name: httpbin-external-domain +spec: + type: ExternalName + externalName: httpbin.org +--- +apiVersion: apisix.apache.org/v1alpha1 +kind: PluginConfig +metadata: + name: auth-plugin-config +spec: + plugins: + - name: key-auth + config: + _meta: + disable: false +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: getting-started-ip +spec: + parentRefs: + - name: apisix + rules: + - matches: + - path: + type: Exact + value: /ip + filters: + - type: ExtensionRef + extensionRef: + group: apisix.apache.org + kind: PluginConfig + name: auth-plugin-config + backendRefs: + - name: httpbin-external-domain + port: 80 +``` + +Apply the configurations to your cluster: + +```shell +kubectl apply -f consumer.yaml -f httpbin-route.yaml +``` + + + + + +Create a Kubernetes manifest file to configure a consumer: + +```yaml title="consumer.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixConsumer +metadata: + name: tom +spec: + ingressClassName: apisix + authParameter: + keyAuth: + value: + key: secret-key +``` + +Create a Kubernetes manifest file to configure a route and enable key authentication: + +```yaml title="httpbin-route.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixUpstream +metadata: + name: httpbin-external-domain +spec: + externalNodes: + - type: Domain + name: httpbin.org +--- +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: getting-started-ip +spec: + ingressClassName: apisix + http: + - name: getting-started-ip + match: + paths: + - /ip + upstreams: + - name: httpbin-external-domain + authentication: + enable: true + type: keyAuth +``` + +Apply the configurations to your cluster: + +```shell +kubectl apply -f consumer.yaml -f httpbin-route.yaml +``` + + + + + +## Verify + +Expose the service port to your local machine by port forwarding: + +```shell +kubectl port-forward svc/apisix-gateway 9080:80 & +``` + +Send a request without the `apikey` header. + +```shell +curl -i "http://127.0.0.1:9080/ip" +``` + +You should receive an an `HTTP/1.1 401 Unauthorized` response. + +Send a request with a wrong key in the `apikey` header. + +```shell +curl -i "http://127.0.0.1:9080/ip" -H 'apikey: wrong-key' +``` + +Since the key is incorrect, you should receive an `HTTP/1.1 401 Unauthorized` response. + +Send a request with the correct key in the `apikey` header. + +```shell +curl -i "http://127.0.0.1:9080/ip" -H 'apikey: secret-key' +``` + +You should receive an `HTTP/1.1 200 OK` response. diff --git a/docs/en/latest/getting-started/load-balancing.md b/docs/en/latest/getting-started/load-balancing.md new file mode 100644 index 000000000..ee6d2f049 --- /dev/null +++ b/docs/en/latest/getting-started/load-balancing.md @@ -0,0 +1,177 @@ +--- +title: Load Balancing +keywords: + - APISIX ingress + - Apache APISIX + - Kubernetes ingress +description: Learn how to implement load balancing in APISIX using APISIX Ingress Controller, distributing clients requests across multiple upstream nodes. +--- + + + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Load balancing is a technique used to distribute network request loads. It is a key consideration in designing systems that need to handle a large volume of traffic, allowing for improved system performance, scalability, and reliability. + +In this tutorial, you will create a route using APISIX Ingress Controller with two upstream services and uses the round-robin load balancing algorithm to load balance requests. + +## Prerequisite + +1. Complete [Get APISIX and APISIX Ingress Controller](./get-apisix-ingress-controller.md). + +## Configure Load Balancing + +For demonstration purpose, you will be creating a route to the [publicly hosted httpbin services](https://httpbin.org) and [mock.api7.ai](https://mock.api7.ai). If you would like to proxy requests to services on Kubernetes, please modify accordingly. + +:::important + +If you are using Gateway API, you should first configure the GatewayClass and Gateway resources: + +
+ +Show configuration + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GatewayClass +metadata: + name: apisix +spec: + controllerName: apisix.apache.org/apisix-ingress-controller +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: apisix +spec: + gatewayClassName: apisix + listeners: + - name: http + protocol: HTTP + port: 80 + infrastructure: + parametersRef: + group: apisix.apache.org + kind: GatewayProxy + name: apisix-config +``` + +
+ +If you are using Ingress or APISIX custom resources, you can proceed without additional configuration. + +::: + + + + + +APISIX Ingress controller installed with the current helm chart version (`apisix-2.11.2`) has a bug in load balancing, which is actively being fixed. + + + + + +Create a Kubernetes manifest file for a route that proxy requests to two upstream services for load balancing: + +```yaml title="lb-route.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixUpstream +metadata: + name: httpbin-external-domain +spec: + scheme: https + passHost: node + externalNodes: + - type: Domain + name: httpbin.org + weight: 1 + port: 443 +--- +apiVersion: apisix.apache.org/v2 +kind: ApisixUpstream +metadata: + name: mockapi7-external-domain +spec: + scheme: https + passHost: node + externalNodes: + - type: Domain + name: mock.api7.ai + weight: 1 + port: 443 +--- +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: lb-route +spec: + ingressClassName: apisix + http: + - name: lb-route + match: + paths: + - /headers + upstreams: + - name: httpbin-external-domain + - name: mockapi7-external-domain +``` + +Apply the configuration to your cluster: + +```shell +kubectl apply -f lb-route.yaml +``` + + + + + +## Verify + +Expose the service port to your local machine by port forwarding: + +```shell +kubectl port-forward svc/apisix-gateway 9080:80 & +``` + +Generate 50 consecutive requests to the route to see the load-balancing effect: + +```shell +resp=$(seq 50 | xargs -I{} curl "http://127.0.0.1:9080/headers" -sL) && \ + count_httpbin=$(echo "$resp" | grep "httpbin.org" | wc -l) && \ + count_mockapi7=$(echo "$resp" | grep "mock.api7.ai" | wc -l) && \ + echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7 +``` + +The command keeps count of the number of requests that was handled by the two services respectively. The output shows that requests were distributed over to the two services: + +```text +httpbin.org: 23, mock.api7.ai: 27 +``` + +The distribution of requests across services should be close to 1:1 but might not always result in a perfect 1:1 ratio. The slight deviation is due to APISIX operates with multiple workers. diff --git a/docs/en/latest/getting-started/rate-limiting.md b/docs/en/latest/getting-started/rate-limiting.md new file mode 100644 index 000000000..82a5f2726 --- /dev/null +++ b/docs/en/latest/getting-started/rate-limiting.md @@ -0,0 +1,206 @@ +--- +title: Rate Limiting +keywords: + - APISIX ingress + - Apache APISIX + - Kubernetes ingress +description: Implement rate limiting in APISIX using APISIX Ingress Controller to control traffic flow, protect your APIs from misuse, and ensure fair usage by setting request limits. +--- + + + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Rate limiting is one of the commonly used techniques to protect and manage APIs. For example, you can configure your API endpoints to allow for a set number of requests within a given period of time. This ensures fair usage of the upstream services and safeguards the APIs from potential cyber attacks like DDoS (Distributed Denial of Service) or excessive requests from web crawlers. + +In this tutorial, you will enable the `limit-count` plugin to set a rate limiting constraint on the incoming traffic, using APISIX Ingress Controller. + +## Prerequisite + +1. Complete [Get APISIX and APISIX Ingress Controller](./get-apisix-ingress-controller.md). + +## Configure Rate Limiting + +For demonstration purpose, you will be creating a route to the [publicly hosted httpbin services](https://httpbin.org) and [mock.api7.ai](https://mock.api7.ai). If you would like to proxy requests to services on Kubernetes, please modify accordingly. + +:::important + +If you are using Gateway API, you should first configure the GatewayClass and Gateway resources: + +
+ +Show configuration + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GatewayClass +metadata: + name: apisix +spec: + controllerName: apisix.apache.org/apisix-ingress-controller +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: apisix +spec: + gatewayClassName: apisix + listeners: + - name: http + protocol: HTTP + port: 80 + infrastructure: + parametersRef: + group: apisix.apache.org + kind: GatewayProxy + name: apisix-config +``` + +
+ +If you are using Ingress or APISIX custom resources, you can proceed without additional configuration. + +::: + +Create a Kubernetes manifest file for a route and enable `limit-count`: + + + + + +```yaml title="httpbin-route.yaml" +apiVersion: v1 +kind: Service +metadata: + name: httpbin-external-domain +spec: + type: ExternalName + externalName: httpbin.org +--- +apiVersion: apisix.apache.org/v1alpha1 +kind: PluginConfig +metadata: + name: limit-count-plugin-config +spec: + plugins: + - name: limit-count + config: + count: 2 + time_window: 10 + rejected_code: 429 +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: getting-started-ip +spec: + parentRefs: + - name: apisix + rules: + - matches: + - path: + type: Exact + value: /ip + filters: + - type: ExtensionRef + extensionRef: + group: apisix.apache.org + kind: PluginConfig + name: limit-count-plugin-config + backendRefs: + - name: httpbin-external-domain + port: 80 +``` + + + + + +```yaml title="httpbin-route.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixUpstream +metadata: + name: httpbin-external-domain +spec: + externalNodes: + - type: Domain + name: httpbin.org +--- +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: getting-started-ip +spec: + ingressClassName: apisix + http: + - name: getting-started-ip + match: + paths: + - /ip + upstreams: + - name: httpbin-external-domain + plugins: + - name: limit-count + enable: true + config: + count: 2 + time_window: 10 + rejected_code: 429 +``` + + + + + +Apply the configuration to your cluster: + +```shell +kubectl apply -f httpbin-route.yaml +``` + +## Verify + +Expose the service port to your local machine by port forwarding: + +```shell +kubectl port-forward svc/apisix-gateway 9080:80 & +``` + +Generate 50 simultaneous requeststo the route: + +```shell +resp=$(seq 50 | xargs -I{} curl "http://127.0.0.1:9080/ip" -o /dev/null -s -w "%{http_code}\n") && \ + count_200=$(echo "$resp" | grep "200" | wc -l) && \ + count_429=$(echo "$resp" | grep "429" | wc -l) && \ + echo "200": $count_200, "429": $count_429 +``` + +The results are as expected: out of the 50 requests, 2 requests were sent successfully (status code `200`) while the others were rejected (status code `429`). + +```text +"200": 2, "429": 48 +``` diff --git a/docs/en/latest/getting-started.md b/docs/en/latest/overview.md similarity index 52% rename from docs/en/latest/getting-started.md rename to docs/en/latest/overview.md index fc8d02137..954ebb7a2 100644 --- a/docs/en/latest/getting-started.md +++ b/docs/en/latest/overview.md @@ -1,11 +1,12 @@ --- -title: Getting started +title: Overview keywords: - APISIX ingress - Apache APISIX - Kubernetes ingress -description: Guide to get started with Apache APISIX ingress controller. +description: Overview of the APISIX Ingress Controller, its features, APISIX compatibility, and how to contribute to the project. --- + -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - APISIX Ingress Controller is a [Kubernetes ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) using [Apache APISIX](https://apisix.apache.org) as the high performance reverse proxy. APISIX Ingress Controller can be configured using the native Kubernetes Ingress or Gateway API, as well as with APISIX’s own declarative and easy-to-use custom resources. The controller translates these resources into APISIX configuration. -## Quick Start - -Get started with APISIX Ingress Controller in a few simple steps. - -### Prerequisites - -Before installing APISIX Ingress Controller, ensure you have: - -1. A working Kubernetes cluster (version 1.26+) -2. [Helm](https://helm.sh/) (version 3.8+) installed - -### Install APISIX and APISIX Ingress Controller (Standalone API-driven mode) - -Install the Gateway API CRDs, [APISIX Standalone API-driven mode](https://apisix.apache.org/docs/apisix/deployment-modes/#api-driven-experimental), and APISIX Ingress Controller using the following commands: - -```bash -helm repo add apisix https://charts.apiseven.com -helm repo add bitnami https://charts.bitnami.com/bitnami -helm repo update - -helm install apisix \ - --namespace ingress-apisix \ - --create-namespace \ - --set apisix.deployment.role=traditional \ - --set apisix.deployment.role_traditional.config_provider=yaml \ - --set etcd.enabled=false \ - --set ingress-controller.enabled=true \ - --set ingress-controller.config.provider.type=apisix-standalone \ - --set ingress-controller.apisix.adminService.namespace=ingress-apisix \ - --set ingress-controller.gatewayProxy.createDefault=true \ - apisix/apisix -``` - -### Set Up a Sample Upstream - -Install the httpbin example application to test the configuration: - -```bash -kubectl apply -f https://raw.githubusercontent.com/apache/apisix-ingress-controller/refs/heads/v2.0.0/examples/httpbin/deployment.yaml -``` - -### Configure a Route - -Install an ApisixRoute or Ingress resource to route traffic to httpbin: - -> The examples below show how these differ. Both the examples configure a Route in APISIX that routes to an httpbin service as the Upstream. - - - - - -```yaml title="httpbin-route.yaml" -apiVersion: apisix.apache.org/v2 -kind: ApisixRoute -metadata: - name: httpbin-route -spec: - ingressClassName: apisix - http: - - name: route-1 - match: - hosts: - - local.httpbin.org - paths: - - /* - backends: - - serviceName: httpbin - servicePort: 80 -``` - - - - - -```yaml title="httpbin-route.yaml" -apiVersion: networking.k8s.io/v1 -kind: Ingress -metadata: - name: httpbin-route -spec: - ingressClassName: apisix - rules: - - host: local.httpbin.org - http: - paths: - - backend: - service: - name: httpbin - port: - number: 80 - path: / - pathType: Prefix -``` - - - - -:::note - -More details on the installation can be found in the [Installation guide](./install.md). - -::: - -### Verify Route Configuration - -Let's verify the configuration. In order to access APISIX locally, we can use `kubectl port-forward` command to forward traffic from the specified port at your local machine to the specified port on the specified service. - -```bash -kubectl port-forward -n ingress-apisix svc/apisix-gateway 9080:80 -``` - -Run curl command in a APISIX pod to see if the routing configuration works. - -```bash -curl http://127.0.0.1:9080/headers -H 'Host: local.httpbin.org' -``` +See the [Getting Started tutorials](./getting-started/get-apisix-ingress-controller.md) to set up and start using the APISIX Ingress Controller. ## Features diff --git a/docs/en/latest/api-reference.md b/docs/en/latest/reference/api-reference.md similarity index 99% rename from docs/en/latest/api-reference.md rename to docs/en/latest/reference/api-reference.md index 11fce5b36..e2fe407e4 100644 --- a/docs/en/latest/api-reference.md +++ b/docs/en/latest/reference/api-reference.md @@ -1,10 +1,10 @@ --- title: Custom Resource Definitions API Reference -slug: /reference/apisix-ingress-controller/crd-reference +slug: /reference/apisix-ingress-controller/api-reference description: Explore detailed reference documentation for the custom resource definitions (CRDs) supported by the APISIX Ingress Controller. --- -This document provides the API resource description the APISIX Ingress Controller custom resource definitions (CRDs). +This document provides the API resource description for the APISIX Ingress Controller custom resource definitions (CRDs). ## Packages - [apisix.apache.org/v1alpha1](#apisixapacheorgv1alpha1) @@ -102,7 +102,7 @@ PluginConfig defines plugin configuration. ### Types -In this section you will find types that the CRDs rely on. +This section describes the types used by the CRDs. #### AdminKeyAuth @@ -607,7 +607,7 @@ ApisixUpstream defines configuration for upstream services. ### Types -In this section you will find types that the CRDs rely on. +This section describes the types used by the CRDs. #### ActiveHealthCheck diff --git a/docs/en/latest/reference/example.md b/docs/en/latest/reference/example.md new file mode 100644 index 000000000..c3231f4f1 --- /dev/null +++ b/docs/en/latest/reference/example.md @@ -0,0 +1,1024 @@ +--- +title: Configuration Examples +slug: /reference/apisix-ingress-controller/examples +description: Explore a variety of APISIX Ingress Controller configuration examples to help you customize settings to suit your environment effectively. +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +APISIX Ingress Controller supports both Ingress resources and Gateway API for traffic management in Kubernetes. In addition to these standard Kubernetes APIs, the APISIX Ingress Controller also supports a set of [CRDs (Custom Resource Definitions)](./api-reference.md) designed specifically for APISIX-native functionality. + +This document provides examples of common configurations covering how and when to use these resources. You should adjust custom values such as namespaces, route URIs, and credentials to match your environment. + +## Configure CP Endpoint and Admin Key + +To update the Control Plane endpoint and admin key for connectivity between APISIX Ingress Controller and Control Plane at runtime: + +```yaml +apiVersion: apisix.apache.org/v1alpha1 +kind: GatewayProxy +metadata: + name: apisix-config + namespace: apisix-ingress +spec: + provider: + type: ControlPlane + controlPlane: + endpoints: + - http://127.0.0.1:9180 + auth: + type: AdminKey + adminKey: + value: replace-with-your-admin-key +``` + +## Define Controller and Gateway + +To specify the controller responsible for handling resources before applying further configurations: + + + + + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GatewayClass +metadata: + name: apisix +spec: + controllerName: "apisix.apache.org/apisix-ingress-controller" +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: apisix +spec: + gatewayClassName: apisix + listeners: + - name: http + protocol: HTTP + port: 80 + infrastructure: + parametersRef: + group: apisix.apache.org + kind: GatewayProxy + name: apisix-config +``` + + + + + +```yaml +apiVersion: networking.k8s.io/v1 +kind: IngressClass +metadata: + name: apisix +spec: + controller: apisix.apache.org/apisix-ingress-controller + parameters: + apiGroup: apisix.apache.org + kind: GatewayProxy + name: apisix-config + namespace: apisix-ingress + scope: Namespace +``` + + + + + +```yaml +apiVersion: networking.k8s.io/v1 +kind: IngressClass +metadata: + name: apisix +spec: + controller: apisix.apache.org/apisix-ingress-controller + parameters: + apiGroup: apisix.apache.org + kind: GatewayProxy + name: apisix-config + namespace: apisix-ingress + scope: Namespace +``` + + + + + +## Route to K8s Services + +To create a route that proxies requests to a service on K8s: + + + + + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: httpbin +spec: + parentRefs: + - name: apisix + rules: + - matches: + - path: + type: Exact + value: /ip + backendRefs: + - name: httpbin + port: 80 +``` + + + + + +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: httpbin +spec: + ingressClassName: apisix + rules: + - http: + paths: + - path: /ip + pathType: Exact + backend: + service: + name: httpbin + port: + number: 80 +``` + + + + + +```yaml +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: httpbin +spec: + ingressClassName: apisix + http: + - name: httpbin + match: + paths: + - /ip + backends: + - serviceName: httpbin + servicePort: 80 +``` + + + + + +## Route to External Services + +To create a route that proxies requests to a service publicly hosted: + + + + + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: httpbin-external-domain +spec: + type: ExternalName + externalName: httpbin.org +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: get-ip +spec: + parentRefs: + - name: apisix + rules: + - matches: + - path: + type: Exact + value: /ip + backendRefs: + - name: httpbin-external-domain + port: 80 +``` + + + + + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: httpbin-external-domain +spec: + type: ExternalName + externalName: httpbin.org +--- +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: get-ip +spec: + rules: + - http: + paths: + - path: /ip + pathType: Exact + backend: + service: + name: httpbin-external-domain + port: + number: 80 +``` + + + + + +```yaml +apiVersion: apisix.apache.org/v2 +kind: ApisixUpstream +metadata: + name: httpbin-external-domain +spec: + externalNodes: + - type: Domain + name: httpbin.org +--- +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: get-ip +spec: + ingressClassName: apisix + http: + - name: get-ip + match: + paths: + - /ip + upstreams: + - name: httpbin-external-domain +``` + + + + + +## Configure Weighted Services + +To create a route that proxies traffic to upstream services by weight: + + + + + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: httpbin +spec: + parentRefs: + - name: apisix + rules: + - matches: + - path: + type: Exact + value: /ip + backendRefs: + - name: httpbin-1 + port: 80 + weight: 3 + - name: httpbin-2 + port: 80 + weight: 7 +``` + + + + + +```yaml +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: httpbin +spec: + ingressClassName: apisix + http: + - name: httpbin + match: + paths: + - /ip + backends: + - serviceName: httpbin-1 + servicePort: 80 + weight: 3 + - serviceName: httpbin-2 + servicePort: 80 + weight: 7 +``` + + + + + +This configuration is not supported by the Ingress resource. + +## Configure Upstream + +To configure upstream related configurations, including load balancing algorithm, how the host header is passed to upstream, service timeout, and more: + + + + + +```yaml +apiVersion: apisix.apache.org/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: httpbin +spec: + targetRefs: + - name: httpbin + kind: Service + group: "" + timeout: + send: 10s + read: 10s + connect: 10s + scheme: http + retries: 10 + loadbalancer: + type: roundrobin + passHost: rewrite + upstreamHost: httpbin.example.com +``` + + + + + +```yaml +apiVersion: apisix.apache.org/v2 +kind: ApisixUpstream +metadata: + name: httpbin +spec: + ingressClassName: apisix + timeout: + send: 10s + read: 10s + connect: 10s + scheme: http + retries: 10 + loadbalancer: + type: roundrobin + passHost: rewrite + upstreamHost: httpbin.example.com +``` + + + + + +## Configure Consumer and Credentials + + + + + +To create a consumer and configure the authentication credentials directly on the consumer: + +```yaml +apiVersion: apisix.apache.org/v1alpha1 +kind: Consumer +metadata: + name: alice +spec: + gatewayRef: + name: apisix + credentials: + - type: key-auth + name: primary-key + config: + key: alice-primary-key +``` + +You can also use the secret CRD, where the credential should be base64 encoded: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: key-auth-primary +data: + key: YWxpY2UtcHJpbWFyeS1rZXk= +--- +apiVersion: apisix.apache.org/v1alpha1 +kind: Consumer +metadata: + name: alice +spec: + gatewayRef: + name: apisix + credentials: + - type: key-auth + name: key-auth-primary + secretRef: + name: key-auth-primary +``` + + + + + +To create a consumer and configure the authentication credentials directly on the consumer: + +```yaml +apiVersion: apisix.apache.org/v2 +kind: ApisixConsumer +metadata: + name: alice +spec: + ingressClassName: apisix + authParameter: + keyAuth: + value: + key: alice-primary-key +``` + +You can also use the secret CRD, where the credential should be base64 encoded: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: key-auth-primary +data: + key: YWxpY2UtcHJpbWFyeS1rZXk= +--- +apiVersion: apisix.apache.org/v2 +kind: ApisixConsumer +metadata: + name: alice +spec: + ingressClassName: apisix + authParameter: + keyAuth: + secretRef: + name: key-auth-primary +``` + + + + + +## Configure Plugin on Consumer + +To configure plugin(s) on a consumer, such as a rate limiting plugin: + + + + + +```yaml +apiVersion: apisix.apache.org/v1alpha1 +kind: Consumer +metadata: + name: alice +spec: + gatewayRef: + name: apisix + credentials: + - type: key-auth + name: alice-key + config: + key: alice-key + plugins: + - name: limit-count + config: + count: 3 + time_window: 60 + key: remote_addr + key_type: var + policy: local + rejected_code: 429 + rejected_msg: Too many requests + show_limit_quota_header: true + allow_degradation: false +``` + + + + + +ApisixConsumer currently does not support configuring plugins on consumers. + + + + + +## Configure Route Priority and Matching Conditions + +To configure route priority and request matching conditions on a targeted route: + + + + + +```yaml +apiVersion: apisix.apache.org/v1alpha1 +kind: HTTPRoutePolicy +metadata: + name: http-route-policy +spec: + targetRefs: + - group: gateway.networking.k8s.io + kind: HTTPRoute + name: httpbin + priority: 10 + vars: + - - http_x_test_name + - == + - new_name + - - arg_test + - == + - test_name +``` + + + + + +```yaml +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: httpbin +spec: + ingressClassName: apisix + http: + - name: httpbin + match: + paths: + - /* + exprs: + - subject: + scope: Header + name: X-Test-Name + op: Equal + value: new_name + - subject: + scope: Query + name: test + op: Equal + value: test_name + backends: + - serviceName: httpbin + servicePort: 80 +``` + + + + + +## Configure Plugin on a Route + +To configure plugins on a route: + + + + + +```yaml +apiVersion: apisix.apache.org/v1alpha1 +kind: PluginConfig +metadata: + name: auth-plugin-config +spec: + plugins: + - name: key-auth + config: + _meta: + disable: false +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: get-ip +spec: + parentRefs: + - name: apisix + rules: + - matches: + - path: + type: Exact + value: /ip + filters: + - type: ExtensionRef + extensionRef: + group: apisix.apache.org + kind: PluginConfig + name: auth-plugin-config + backendRefs: + - name: httpbin + port: 80 +``` + + + + + +To enable `basic-auth`, `key-auth`, `wolf-rbac`, `jwt-auth`, `ldap-auth`, or `hmac-auth`: + +```yaml +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: get-ip +spec: + ingressClassName: apisix + http: + - name: get-ip + match: + paths: + - /ip + authentication: + enable: true + type: keyAuth + backends: + - serviceName: httpbin + servicePort: 80 +``` + +To enable other plugins: + +```yaml +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: get-ip +spec: + ingressClassName: apisix + http: + - name: get-ip + match: + paths: + - /ip + plugins: + - name: limit-count + enable: true + config: + count: 2 + time_window: 10 + rejected_code: 429 + backends: + - serviceName: httpbin + servicePort: 80 +``` + + + + + +## Configure Global Plugin + +To configure a global plugin: + + + + + +```yaml +apiVersion: apisix.apache.org/v1alpha1 +kind: GatewayProxy +metadata: + name: apisix-config +spec: + plugins: + - name: clickhouse-logger + config: + endpoint_addr: http://clickhouse-clickhouse-installation.apisix.svc.cluster.local:8123 + user: quickstart-user + password: quickstart-pass + logtable: test + database: quickstart_db +``` + + + + + +```yaml +apiVersion: apisix.apache.org/v2 +kind: ApisixGlobalRule +metadata: + name: apisix-global-rule-logging +spec: + ingressClassName: apisix + plugins: + - name: clickhouse-logger + enable: true + config: + endpoint_addr: http://clickhouse-clickhouse-installation.apisix.svc.cluster.local:8123 + user: quickstart-user + password: quickstart-pass + logtable: test + database: quickstart_db +``` + + + + + +## Configure Plugin Metadata + +To configure plugin metadata: + + + + + +```yaml +apiVersion: apisix.apache.org/v1alpha1 +kind: GatewayProxy +metadata: + name: apisix-config +spec: + pluginMetadata: + opentelemetry: { + "trace_id_source": "x-request-id", + "resource": { + "service.name": "APISIX" + }, + "collector": { + "address": "simplest-collector:4318", + "request_timeout": 3, + "request_headers": { + "Authorization": "token" + } + }, + "batch_span_processor": { + "drop_on_queue_full": false, + "max_queue_size": 1024, + "batch_timeout": 2, + "inactive_timeout": 1, + "max_export_batch_size": 16 + }, + "set_ngx_var": true + } +``` + + + + + +Not currently supported. + + + + + +## Configure Plugin Config + +To create a plugin config and reference it in a route: + + + + + +```yaml +apiVersion: apisix.apache.org/v1alpha1 +kind: PluginConfig +metadata: + name: example-plugin-config +spec: + plugins: + - name: response-rewrite + enable: true + config: + headers: + X-Plugin-Config: "example-response-rewrite" + X-Plugin-Test: "enabled" +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: httpbin +spec: + parentRefs: + - name: apisix + rules: + - matches: + - path: + type: Exact + value: /ip + filters: + - type: ExtensionRef + extensionRef: + group: apisix.apache.org + kind: PluginConfig + name: example-plugin-config + backendRefs: + - name: httpbin + port: 80 +``` + + + + + +```yaml +apiVersion: apisix.apache.org/v2 +kind: ApisixPluginConfig +metadata: + name: example-plugin-config +spec: + ingressClassName: apisix + plugins: + - name: response-rewrite + enable: true + config: + headers: + X-Plugin-Config: "example-response-rewrite" + X-Plugin-Test: "enabled" +--- +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: httpbin +spec: + ingressClassName: apisix + http: + - name: get-ip + match: + paths: + - /ip + backends: + - serviceName: httpbin + servicePort: 80 + plugin_config_name: example-plugin-config +``` + + + + + +## Configure Gateway Access Information + +These configurations allow Ingress Controller users to access the gateway. + + + + + +To configure the `statusAddress`: + +```yaml +apiVersion: apisix.apache.org/v1alpha1 +kind: GatewayProxy +metadata: + name: apisix-config +spec: + statusAddress: + - 10.24.87.13 +``` + + + + + +If you are using Ingress resources, you can configure either `statusAddress` or `publishService`. + +To configure the `statusAddress`: + +```yaml +apiVersion: apisix.apache.org/v1alpha1 +kind: GatewayProxy +metadata: + name: apisix-config +spec: + statusAddress: + - 10.24.87.13 +``` + +To configure the `publishService`: + +```yaml +apiVersion: apisix.apache.org/v1alpha1 +kind: GatewayProxy +metadata: + name: apisix-config +spec: + publishService: apisix-ee-3-gateway-gateway +``` + +When using `publishService`, make sure your gateway Service is of `LoadBalancer` type the address can be populated. The controller will use the endpoint of this Service to update the status information of the Ingress resource. The format can be either `namespace/svc-name` or simply `svc-name` if the default namespace is correctly set. + + + + + +Not supported. + + + + diff --git a/link-check-config.json b/link-check-config.json new file mode 100644 index 000000000..f3ef373c5 --- /dev/null +++ b/link-check-config.json @@ -0,0 +1,38 @@ +{ + "ignorePatterns": [ + { + "pattern": "^https://github.com/.*?/issue" + }, + { + "pattern": "^https://github.com/.*?/pull" + }, + { + "pattern": "^#" + }, + { + "pattern": "/enterprise/reference/built-in-variable" + }, + { + "pattern": "/apisix/reference/built-in-variables" + } + ], + "replacementPatterns": [ + { + "pattern": "^https://github.com/apache/apisix-ingress-controller/blob/master/", + "replacement": "{{BASEURL}}/" + }, + { + "pattern": "^https://github.com/apache/apisix-ingress-controller/tree/master/", + "replacement": "{{BASEURL}}/" + }, + { + "pattern": "^https://apisix.apache.org/docs/ingress-controller/(.*?)$", + "replacement": "{{BASEURL}}/docs/$1.md" + } + ], + "timeout": "20s", + "retryOn429": true, + "retryCount": 5, + "fallbackRetryDelay": "30s", + "aliveStatusCodes": [200, 206] +}