From 8e4f067ffc1aad5275ae2c0b91659cbde99589d1 Mon Sep 17 00:00:00 2001 From: Spencer Gibb Date: Mon, 11 Sep 2023 19:08:08 -0400 Subject: [PATCH] Antora migration (#3050) * Migrate Structure * Insert explicit ids for headers * Remove unnecessary asciidoc attributes * Copy default antora files * Fix indentation for all pages * Split files * Generate a default navigation * Remove includes * Fix cross references * Enable Section Summary TOC for small pages * Migrate to antora documentation * Migrate to antora documentation --- .github/workflows/deploy-docs.yml | 32 + .gitignore | 10 + README.adoc | 149 +- docs/antora-playbook.yml | 43 + docs/antora.yml | 12 + .../images/gateway-grafana-dashboard.jpeg | Bin 0 -> 241759 bytes .../images/spring_cloud_gateway_diagram.png | Bin 0 -> 27306 bytes docs/modules/ROOT/nav.adoc | 64 + .../ROOT/pages}/_attributes.adoc | 2 - docs/modules/ROOT/pages/appendix.adoc | 21 + docs/modules/ROOT/pages/configprops.adoc | 6 + docs/modules/ROOT/pages/index.adoc | 0 .../ROOT/pages}/intro.adoc | 3 + .../spring-cloud-gateway-proxy-exchange.adoc | 72 + .../spring-cloud-gateway-server-mvc.adoc | 5 + .../starter.adoc | 14 + .../ROOT/pages/spring-cloud-gateway.adoc | 7 + .../spring-cloud-gateway/actuator-api.adoc | 291 ++ .../aot-and-native-image-support.adoc | 8 + .../configuration-properties.adoc | 5 + .../spring-cloud-gateway/configuration.adoc | 45 + ...dicate-factories-and-filter-factories.adoc | 50 + .../cors-configuration.adoc | 61 + .../spring-cloud-gateway/developer-guide.adoc | 156 + .../fluent-java-routes-api.adoc | 41 + .../gatewayfilter-factories.adoc | 10 + .../circuitbreaker-filter-factory.adoc | 168 + .../default-filters.adoc | 19 + .../fallback-headers.adoc | 43 + .../local-cache-response-filter.adoc | 55 + ...ovejsonattributesresponsebody-factory.adoc | 42 + .../the-addrequestheader-factory.adoc | 40 + ...addrequestheadersifnotpresent-factory.adoc | 44 + .../the-addrequestparameter-factory.adoc | 40 + .../the-addresponseheader-factory.adoc | 41 + .../the-cacherequestbody-factory.adoc | 42 + .../the-deduperesponseheader-factory.adoc | 25 + .../the-jsontogrpc-factory.adoc | 80 + .../the-maprequestheader-factory.adoc | 24 + .../the-modifyrequestbody-factory.adoc | 44 + .../the-modifyresponsebody-factory.adoc | 24 + .../the-prefixpath-factory.adoc | 23 + .../the-preservehostheader-factory.adoc | 21 + .../the-redirectto-factory.adoc | 26 + .../the-removerequestheader-factory.adoc | 23 + .../the-removerequestparameter-factory.adoc | 24 + .../the-removeresponseheader-factory.adoc | 26 + .../the-requestheadersize-factory.adoc | 23 + .../the-requestratelimiter-factory.adoc | 120 + .../the-requestsize-factory.adoc | 35 + .../the-retry-factory.adoc | 86 + ...rewritelocationresponseheader-factory.adoc | 35 + .../the-rewritepath-factory.adoc | 24 + .../the-rewriteresponseheader-factory.adoc | 24 + .../the-savesession-factory.adoc | 24 + .../the-secureheaders-factory.adoc | 38 + .../the-setpath-factory.adoc | 26 + .../the-setrequestheader-factory.adoc | 41 + .../the-setrequesthostheader-factory.adoc | 27 + .../the-setresponseheader-factory.adoc | 41 + .../the-setstatus-factory.adoc | 40 + .../the-stripprefix-factory.adoc | 24 + .../the-tokenrelay-factory.adoc | 103 + .../spring-cloud-gateway/global-filters.adoc | 200 + .../pages/spring-cloud-gateway/glossary.adoc | 11 + .../spring-cloud-gateway/how-it-works.adoc | 15 + .../http-timeouts-configuration.adoc | 75 + .../httpheadersfilters.adoc | 45 + .../reactor-netty-access-logs.adoc | 27 + .../request-predicates-factories.adoc | 376 ++ .../route-metadata-configuration.adoc | 32 + .../pages/spring-cloud-gateway/starter.adoc | 16 + ...coveryclient-route-definition-locator.adoc | 36 + .../spring-cloud-gateway/tls-and-ssl.adoc | 71 + .../spring-cloud-gateway/troubleshooting.adoc | 25 + docs/pom.xml | 27 +- .../resources/antora-resources/antora.yml | 20 + docs/src/main/asciidoc/README.adoc | 12 +- docs/src/main/asciidoc/_configprops.adoc | 154 - docs/src/main/asciidoc/appendix.adoc | 20 - docs/src/main/asciidoc/index.adoc | 1 - .../main/asciidoc/spring-cloud-gateway.adoc | 3344 ----------------- 82 files changed, 3554 insertions(+), 3645 deletions(-) create mode 100644 .github/workflows/deploy-docs.yml create mode 100644 docs/antora-playbook.yml create mode 100644 docs/antora.yml create mode 100644 docs/modules/ROOT/assets/images/gateway-grafana-dashboard.jpeg create mode 100644 docs/modules/ROOT/assets/images/spring_cloud_gateway_diagram.png create mode 100644 docs/modules/ROOT/nav.adoc rename docs/{src/main/asciidoc => modules/ROOT/pages}/_attributes.adoc (90%) create mode 100644 docs/modules/ROOT/pages/appendix.adoc create mode 100644 docs/modules/ROOT/pages/configprops.adoc create mode 100644 docs/modules/ROOT/pages/index.adoc rename docs/{src/main/asciidoc => modules/ROOT/pages}/intro.adoc (78%) create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway-proxy-exchange.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway-server-mvc.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway-server-mvc/starter.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/actuator-api.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/aot-and-native-image-support.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/configuration-properties.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/configuration.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/configuring-route-predicate-factories-and-filter-factories.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/cors-configuration.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/developer-guide.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/fluent-java-routes-api.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/circuitbreaker-filter-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/default-filters.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/fallback-headers.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/local-cache-response-filter.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/removejsonattributesresponsebody-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-addrequestheader-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-addrequestheadersifnotpresent-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-addrequestparameter-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-addresponseheader-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-cacherequestbody-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-deduperesponseheader-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-jsontogrpc-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-maprequestheader-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-modifyrequestbody-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-modifyresponsebody-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-prefixpath-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-preservehostheader-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-redirectto-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-removerequestheader-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-removerequestparameter-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-removeresponseheader-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-requestheadersize-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-requestratelimiter-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-requestsize-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-retry-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-rewritelocationresponseheader-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-rewritepath-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-rewriteresponseheader-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-savesession-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-secureheaders-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setpath-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setrequestheader-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setrequesthostheader-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setresponseheader-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setstatus-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-stripprefix-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-tokenrelay-factory.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/global-filters.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/glossary.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/how-it-works.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/http-timeouts-configuration.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/httpheadersfilters.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/reactor-netty-access-logs.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/request-predicates-factories.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/route-metadata-configuration.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/starter.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/the-discoveryclient-route-definition-locator.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/tls-and-ssl.adoc create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway/troubleshooting.adoc create mode 100644 docs/src/main/antora/resources/antora-resources/antora.yml delete mode 100644 docs/src/main/asciidoc/_configprops.adoc delete mode 100644 docs/src/main/asciidoc/appendix.adoc delete mode 100644 docs/src/main/asciidoc/index.adoc delete mode 100644 docs/src/main/asciidoc/spring-cloud-gateway.adoc diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 000000000..be4b92dfc --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,32 @@ +name: Deploy Docs +on: + push: + branches-ignore: [ gh-pages ] + tags: '**' + repository_dispatch: + types: request-build-reference # legacy + #schedule: + #- cron: '0 10 * * *' # Once per day at 10am UTC + workflow_dispatch: +permissions: + actions: write +jobs: + build: + runs-on: ubuntu-latest + # if: github.repository_owner == 'spring-cloud' + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + ref: docs-build + fetch-depth: 1 + - name: Dispatch (partial build) + if: github.ref_type == 'branch' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }} + - name: Dispatch (full build) + if: github.ref_type == 'tag' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) diff --git a/.gitignore b/.gitignore index 62227c8c6..f13025a5f 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,13 @@ _site/ *.swo .vscode/ .flattened-pom.xml + +node +node_modules +build +package.json +package-lock.json +_configprops.adoc +_spans.adoc +_metrics.adoc +_conventions.adoc \ No newline at end of file diff --git a/README.adoc b/README.adoc index 39d20fae0..5cbad6095 100644 --- a/README.adoc +++ b/README.adoc @@ -9,10 +9,9 @@ image::https://github.com/spring-cloud/spring-cloud-gateway/workflows/Build/badg image::https://codecov.io/gh/spring-cloud/spring-cloud-gateway/branch/main/graph/badge.svg["Codecov", link="https://codecov.io/gh/spring-cloud/spring-cloud-gateway/branch/main"] -This project provides an API Gateway built on top of the Spring Ecosystem, including: Spring 6, Spring Boot 3 and Project Reactor. Spring Cloud Gateway aims to provide a simple, yet effective way to route to APIs and provide cross cutting concerns to them such as: security, monitoring/metrics, and resiliency. - -== Features +[[features]] += Features * Java 17 * Spring Framework 6 @@ -25,99 +24,20 @@ This project provides an API Gateway built on top of the Spring Ecosystem, inclu * API or configuration driven * Supports Spring Cloud `DiscoveryClient` for configuring Routes -== Building - -:jdkversion: 17 - -=== Basic Compile and Test +[[building]] += Building -To build the source you will need to install JDK {jdkversion}. - -Spring Cloud uses Maven for most build-related activities, and you -should be able to get off the ground quite quickly by cloning the -project you are interested in and typing - ----- -$ ./mvnw install ----- - -NOTE: You can also install Maven (>=3.3.3) yourself and run the `mvn` command -in place of `./mvnw` in the examples below. If you do that you also -might need to add `-P spring` if your local Maven settings do not -contain repository declarations for spring pre-release artifacts. - -NOTE: Be aware that you might need to increase the amount of memory -available to Maven by setting a `MAVEN_OPTS` environment variable with -a value like `-Xmx512m -XX:MaxPermSize=128m`. We try to cover this in -the `.mvn` configuration, so if you find you have to do it to make a -build succeed, please raise a ticket to get the settings added to -source control. - -The projects that require middleware (i.e. Redis) for testing generally -require that a local instance of [Docker](https://www.docker.com/get-started) is installed and running. - - -=== Documentation - -The spring-cloud-build module has a "docs" profile, and if you switch -that on it will try to build asciidoc sources from -`src/main/asciidoc`. As part of that process it will look for a -`README.adoc` and process it by loading all the includes, but not -parsing or rendering it, just copying it to `${main.basedir}` -(defaults to `${basedir}`, i.e. the root of the project). If there are -any changes in the README it will then show up after a Maven build as -a modified file in the correct place. Just commit it and push the change. - -=== Working with the code -If you don't have an IDE preference we would recommend that you use -https://www.springsource.com/developer/sts[Spring Tools Suite] or -https://eclipse.org[Eclipse] when working with the code. We use the -https://eclipse.org/m2e/[m2eclipse] eclipse plugin for maven support. Other IDEs and tools -should also work without issue as long as they use Maven 3.3.3 or better. - -==== Activate the Spring Maven profile -Spring Cloud projects require the 'spring' Maven profile to be activated to resolve -the spring milestone and snapshot repositories. Use your preferred IDE to set this -profile to be active, or you may experience build errors. - -==== Importing into eclipse with m2eclipse -We recommend the https://eclipse.org/m2e/[m2eclipse] eclipse plugin when working with -eclipse. If you don't already have m2eclipse installed it is available from the "eclipse -marketplace". - -NOTE: Older versions of m2e do not support Maven 3.3, so once the -projects are imported into Eclipse you will also need to tell -m2eclipse to use the right profile for the projects. If you -see many different errors related to the POMs in the projects, check -that you have an up to date installation. If you can't upgrade m2e, -add the "spring" profile to your `settings.xml`. Alternatively you can -copy the repository settings from the "spring" profile of the parent -pom into your `settings.xml`. - -==== Importing into eclipse without m2eclipse -If you prefer not to use m2eclipse you can generate eclipse project metadata using the -following command: - -[indent=0] ----- - $ ./mvnw eclipse:eclipse ----- - -The generated eclipse projects can be imported by selecting `import existing projects` -from the `file` menu. - - -== Contributing - -:spring-cloud-build-branch: master +:spring-cloud-build-branch: main Spring Cloud is released under the non-restrictive Apache 2.0 license, and follows a very standard Github development process, using Github -tracker for issues and merging pull requests into master. If you want +tracker for issues and merging pull requests into main. If you want to contribute even something trivial please do not hesitate, but follow the guidelines below. -=== Sign the Contributor License Agreement +[[sign-the-contributor-license-agreement]] +== Sign the Contributor License Agreement + Before we accept a non-trivial patch or pull request we will need you to sign the https://cla.pivotal.io/sign/spring[Contributor License Agreement]. Signing the contributor's agreement does not grant anyone commit rights to the main @@ -125,19 +45,21 @@ repository, but it does mean that we can accept your contributions, and you will author credit if we do. Active contributors might be asked to join the core team, and given the ability to merge pull requests. -=== Code of Conduct -This project adheres to the Contributor Covenant https://github.com/spring-cloud/spring-cloud-build/blob/master/docs/src/main/asciidoc/code-of-conduct.adoc[code of +[[code-of-conduct]] +== Code of Conduct +This project adheres to the Contributor Covenant https://github.com/spring-cloud/spring-cloud-build/blob/main/docs/src/main/asciidoc/code-of-conduct.adoc[code of conduct]. By participating, you are expected to uphold this code. Please report unacceptable behavior to spring-code-of-conduct@pivotal.io. -=== Code Conventions and Housekeeping +[[code-conventions-and-housekeeping]] +== Code Conventions and Housekeeping None of these is essential for a pull request, but they will all help. They can also be added after the original pull request but before a merge. * Use the Spring Framework code format conventions. If you use Eclipse you can import formatter settings using the `eclipse-code-formatter.xml` file from the - https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-dependencies-parent/eclipse-code-formatter.xml[Spring + https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/spring-cloud-dependencies-parent/eclipse-code-formatter.xml[Spring Cloud Build] project. If using IntelliJ, you can use the https://plugins.jetbrains.com/plugin/6546[Eclipse Code Formatter Plugin] to import the same file. @@ -150,13 +72,14 @@ added after the original pull request but before a merge. than cosmetic changes). * Add some Javadocs and, if you change the namespace, some XSD doc elements. * A few unit tests would help a lot as well -- someone has to do it. -* If no-one else is using your branch, please rebase it against the current master (or +* If no-one else is using your branch, please rebase it against the current main (or other target branch in the main project). * When writing a commit message please follow https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[these conventions], if you are fixing an existing issue please add `Fixes gh-XXXX` at the end of the commit message (where XXXX is the issue number). -=== Checkstyle +[[checkstyle]] +== Checkstyle Spring Cloud Build comes with a set of checkstyle rules. You can find them in the `spring-cloud-build-tools` module. The most notable files under the module are: @@ -174,7 +97,8 @@ Spring Cloud Build comes with a set of checkstyle rules. You can find them in th <2> File header setup <3> Default suppression rules -==== Checkstyle configuration +[[checkstyle-configuration]] +=== Checkstyle configuration Checkstyle rules are *disabled by default*. To add checkstyle to your project just define the following properties and plugins. @@ -233,16 +157,18 @@ If you need to suppress some rules (e.g. line length needs to be longer), then i It's advisable to copy the `${spring-cloud-build.rootFolder}/.editorconfig` and `${spring-cloud-build.rootFolder}/.springformat` to your project. That way, some default formatting rules will be applied. You can do so by running this script: ```bash -$ curl https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/.editorconfig -o .editorconfig +$ curl https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/.editorconfig -o .editorconfig $ touch .springformat ``` -=== IDE setup +[[ide-setup]] +== IDE setup -==== Intellij IDEA +[[intellij-idea]] +=== Intellij IDEA In order to setup Intellij you should import our coding conventions, inspection profiles and set up the checkstyle plugin. -The following files can be found in the https://github.com/spring-cloud/spring-cloud-build/tree/master/spring-cloud-build-tools[Spring Cloud Build] project. +The following files can be found in the https://github.com/spring-cloud/spring-cloud-build/tree/main/spring-cloud-build-tools[Spring Cloud Build] project. .spring-cloud-build-tools/ ---- @@ -265,13 +191,13 @@ The following files can be found in the https://github.com/spring-cloud/spring-c .Code style -image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-code-style.png[Code style] +image::intellij-code-style.png[Code style] Go to `File` -> `Settings` -> `Editor` -> `Code style`. There click on the icon next to the `Scheme` section. There, click on the `Import Scheme` value and pick the `Intellij IDEA code style XML` option. Import the `spring-cloud-build-tools/src/main/resources/intellij/Intellij_Spring_Boot_Java_Conventions.xml` file. .Inspection profiles -image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-inspections.png[Code style] +image::intellij-inspections.png[Code style] Go to `File` -> `Settings` -> `Editor` -> `Inspections`. There click on the icon next to the `Profile` section. There, click on the `Import Profile` and import the `spring-cloud-build-tools/src/main/resources/intellij/Intellij_Project_Defaults.xml` file. @@ -279,21 +205,23 @@ Go to `File` -> `Settings` -> `Editor` -> `Inspections`. There click on the icon To have Intellij work with Checkstyle, you have to install the `Checkstyle` plugin. It's advisable to also install the `Assertions2Assertj` to automatically convert the JUnit assertions -image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-checkstyle.png[Checkstyle] +image::intellij-checkstyle.png[Checkstyle] -Go to `File` -> `Settings` -> `Other settings` -> `Checkstyle`. There click on the `+` icon in the `Configuration file` section. There, you'll have to define where the checkstyle rules should be picked from. In the image above, we've picked the rules from the cloned Spring Cloud Build repository. However, you can point to the Spring Cloud Build's GitHub repository (e.g. for the `checkstyle.xml` : `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle.xml`). We need to provide the following variables: +Go to `File` -> `Settings` -> `Other settings` -> `Checkstyle`. There click on the `+` icon in the `Configuration file` section. There, you'll have to define where the checkstyle rules should be picked from. In the image above, we've picked the rules from the cloned Spring Cloud Build repository. However, you can point to the Spring Cloud Build's GitHub repository (e.g. for the `checkstyle.xml` : `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/spring-cloud-build-tools/src/main/resources/checkstyle.xml`). We need to provide the following variables: -- `checkstyle.header.file` - please point it to the Spring Cloud Build's, `spring-cloud-build-tools/src/main/resources/checkstyle-header.txt` file either in your cloned repo or via the `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle-header.txt` URL. -- `checkstyle.suppressions.file` - default suppressions. Please point it to the Spring Cloud Build's, `spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` file either in your cloned repo or via the `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` URL. +- `checkstyle.header.file` - please point it to the Spring Cloud Build's, `spring-cloud-build-tools/src/main/resources/checkstyle-header.txt` file either in your cloned repo or via the `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/spring-cloud-build-tools/src/main/resources/checkstyle-header.txt` URL. +- `checkstyle.suppressions.file` - default suppressions. Please point it to the Spring Cloud Build's, `spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` file either in your cloned repo or via the `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` URL. - `checkstyle.additional.suppressions.file` - this variable corresponds to suppressions in your local project. E.g. you're working on `spring-cloud-contract`. Then point to the `project-root/src/checkstyle/checkstyle-suppressions.xml` folder. Example for `spring-cloud-contract` would be: `/home/username/spring-cloud-contract/src/checkstyle/checkstyle-suppressions.xml`. IMPORTANT: Remember to set the `Scan Scope` to `All sources` since we apply checkstyle rules for production and test sources. -=== Duplicate Finder +[[duplicate-finder]] +== Duplicate Finder Spring Cloud Build brings along the `basepom:duplicate-finder-maven-plugin`, that enables flagging duplicate and conflicting classes and resources on the java classpath. -==== Duplicate Finder configuration +[[duplicate-finder-configuration]] +=== Duplicate Finder configuration Duplicate finder is *enabled by default* and will run in the `verify` phase of your Maven build, but it will only take effect in your project if you add the `duplicate-finder-maven-plugin` to the `build` section of the projecst's `pom.xml`. @@ -339,3 +267,8 @@ If you need to add `ignoredClassPatterns` or `ignoredResourcePatterns` to your s ---- + +[[contributing]] += Contributing + +Unresolved directive in - include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing.adoc[] diff --git a/docs/antora-playbook.yml b/docs/antora-playbook.yml new file mode 100644 index 000000000..f5693e83c --- /dev/null +++ b/docs/antora-playbook.yml @@ -0,0 +1,43 @@ +antora: + extensions: + - '@springio/antora-extensions/partial-build-extension' + - require: '@springio/antora-extensions/latest-version-extension' + - require: '@springio/antora-extensions/inject-collector-cache-config-extension' + - '@antora/collector-extension' + - '@antora/atlas-extension' + - require: '@springio/antora-extensions/root-component-extension' + root_component_name: 'cloud-gateway' + # FIXME: Run antora once using this extension to migrate to the Asciidoc Tabs syntax + # and then remove this extension + - require: '@springio/antora-extensions/tabs-migration-extension' + unwrap_example_block: always + save_result: true +site: + title: Spring Cloud Gateway + url: https://docs.spring.io/spring-cloud-gateway/reference/ +content: + sources: + - url: ./.. + branches: HEAD + start_path: docs + worktrees: true +asciidoc: + attributes: + page-stackoverflow-url: https://stackoverflow.com/tags/spring-cloud + page-pagination: '' + hide-uri-scheme: '@' + tabs-sync-option: '@' + chomp: 'all' + extensions: + - '@asciidoctor/tabs' + - '@springio/asciidoctor-extensions' + sourcemap: true +urls: + latest_version_segment: '' +runtime: + log: + failure_level: warn + format: pretty +ui: + bundle: + url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.5/ui-bundle.zip diff --git a/docs/antora.yml b/docs/antora.yml new file mode 100644 index 000000000..7afd0be1e --- /dev/null +++ b/docs/antora.yml @@ -0,0 +1,12 @@ +name: cloud-gateway +version: true +title: spring-cloud-gateway +nav: + - modules/ROOT/nav.adoc +ext: + collector: + run: + command: ./mvnw --no-transfer-progress -B process-resources -Pdocs -pl docs -Dantora-maven-plugin.phase=none -Dgenerate-docs.phase=none -Dgenerate-readme.phase=none -Dgenerate-cloud-resources.phase=none -Dmaven-dependency-plugin-for-docs.phase=none -Dmaven-dependency-plugin-for-docs-classes.phase=none -DskipTests + local: true + scan: + dir: ./target/classes/antora-resources/ diff --git a/docs/modules/ROOT/assets/images/gateway-grafana-dashboard.jpeg b/docs/modules/ROOT/assets/images/gateway-grafana-dashboard.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..3a231f70f646825b66c51c6c7c6d3c4535650d55 GIT binary patch literal 241759 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 AKmY&$ literal 0 HcmV?d00001 diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc new file mode 100644 index 000000000..7f3d7517f --- /dev/null +++ b/docs/modules/ROOT/nav.adoc @@ -0,0 +1,64 @@ +* xref:intro.adoc[] +* xref:spring-cloud-gateway.adoc[] +** xref:spring-cloud-gateway/starter.adoc[] +** xref:spring-cloud-gateway/glossary.adoc[] +** xref:spring-cloud-gateway/how-it-works.adoc[] +** xref:spring-cloud-gateway/configuring-route-predicate-factories-and-filter-factories.adoc[] +** xref:spring-cloud-gateway/request-predicates-factories.adoc[] +** xref:spring-cloud-gateway/gatewayfilter-factories.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-addrequestheader-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-addrequestheadersifnotpresent-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-addrequestparameter-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-addresponseheader-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/circuitbreaker-filter-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-cacherequestbody-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-deduperesponseheader-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/fallback-headers.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-jsontogrpc-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/local-cache-response-filter.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-maprequestheader-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-modifyrequestbody-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-modifyresponsebody-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-prefixpath-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-preservehostheader-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-redirectto-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/removejsonattributesresponsebody-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-removerequestheader-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-removerequestparameter-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-removeresponseheader-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-requestheadersize-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-requestratelimiter-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-rewritelocationresponseheader-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-rewritepath-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-rewriteresponseheader-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-savesession-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-secureheaders-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-setpath-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-setrequestheader-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-setresponseheader-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-setstatus-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-stripprefix-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-retry-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-requestsize-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-setrequesthostheader-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/the-tokenrelay-factory.adoc[] +*** xref:spring-cloud-gateway/gatewayfilter-factories/default-filters.adoc[] +** xref:spring-cloud-gateway/global-filters.adoc[] +** xref:spring-cloud-gateway/httpheadersfilters.adoc[] +** xref:spring-cloud-gateway/tls-and-ssl.adoc[] +** xref:spring-cloud-gateway/configuration.adoc[] +** xref:spring-cloud-gateway/route-metadata-configuration.adoc[] +** xref:spring-cloud-gateway/http-timeouts-configuration.adoc[] +** xref:spring-cloud-gateway/fluent-java-routes-api.adoc[] +** xref:spring-cloud-gateway/the-discoveryclient-route-definition-locator.adoc[] +** xref:spring-cloud-gateway/reactor-netty-access-logs.adoc[] +** xref:spring-cloud-gateway/cors-configuration.adoc[] +** xref:spring-cloud-gateway/actuator-api.adoc[] +** xref:spring-cloud-gateway/troubleshooting.adoc[] +** xref:spring-cloud-gateway/developer-guide.adoc[] +** xref:spring-cloud-gateway/aot-and-native-image-support.adoc[] +** xref:spring-cloud-gateway/configuration-properties.adoc[] +* xref:spring-cloud-gateway-server-mvc.adoc[] +** xref:spring-cloud-gateway-server-mvc/starter.adoc[] +* xref:spring-cloud-gateway-proxy-exchange.adoc[] +* xref:appendix.adoc[] diff --git a/docs/src/main/asciidoc/_attributes.adoc b/docs/modules/ROOT/pages/_attributes.adoc similarity index 90% rename from docs/src/main/asciidoc/_attributes.adoc rename to docs/modules/ROOT/pages/_attributes.adoc index d110bd248..8b1252910 100644 --- a/docs/src/main/asciidoc/_attributes.adoc +++ b/docs/modules/ROOT/pages/_attributes.adoc @@ -1,8 +1,6 @@ :doctype: book :idprefix: :idseparator: - -:toc: left -:toclevels: 4 :tabsize: 4 :numbered: :sectanchors: diff --git a/docs/modules/ROOT/pages/appendix.adoc b/docs/modules/ROOT/pages/appendix.adoc new file mode 100644 index 000000000..7667304ba --- /dev/null +++ b/docs/modules/ROOT/pages/appendix.adoc @@ -0,0 +1,21 @@ +:numbered!: +[appendix] +[[common-application-properties]] += Common application properties +:page-section-summary-toc: 1 + + +Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches. +This appendix provides a list of common Spring Cloud Gateway properties and references to the underlying classes that consume them. + +NOTE: Property contributions can come from additional jar files on your classpath, so you should not consider this an exhaustive list. +Also, you can define your own properties. + +[[observability]] +== Observability metadata + +include::partial$_metrics.adoc[] + +include::partial$_spans.adoc[] + +include::partial$_conventions.adoc[] diff --git a/docs/modules/ROOT/pages/configprops.adoc b/docs/modules/ROOT/pages/configprops.adoc new file mode 100644 index 000000000..32cbb8e58 --- /dev/null +++ b/docs/modules/ROOT/pages/configprops.adoc @@ -0,0 +1,6 @@ +[[configuration-properties]] += Configuration Properties + +Below you can find a list of configuration properties. + +include::partial$_configprops.adoc[] diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc new file mode 100644 index 000000000..e69de29bb diff --git a/docs/src/main/asciidoc/intro.adoc b/docs/modules/ROOT/pages/intro.adoc similarity index 78% rename from docs/src/main/asciidoc/intro.adoc rename to docs/modules/ROOT/pages/intro.adoc index 200bc11ed..9e8e0145f 100644 --- a/docs/src/main/asciidoc/intro.adoc +++ b/docs/modules/ROOT/pages/intro.adoc @@ -1,2 +1,5 @@ +[[spring-cloud-gateway-intro]] += Introduction +// TODO: docs, rework intro for 4 modules This project provides an API Gateway built on top of the Spring Ecosystem, including: Spring 6, Spring Boot 3 and Project Reactor. Spring Cloud Gateway aims to provide a simple, yet effective way to route to APIs and provide cross cutting concerns to them such as: security, monitoring/metrics, and resiliency. diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway-proxy-exchange.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway-proxy-exchange.adoc new file mode 100644 index 000000000..719aaf00f --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway-proxy-exchange.adoc @@ -0,0 +1,72 @@ +[[proxy-exchange-gateway]] += Proxy Exchange Gateway with Spring MVC or Webflux + +WARNING: The following describes an alternative style gateway. None of the Spring Cloud Gateway Server documentation applies to what follows. + +Spring Cloud Gateway provides a utility object called `ProxyExchange`. +You can use it inside a regular Spring web handler as a method parameter. +It supports basic downstream HTTP exchanges through methods that mirror the HTTP verbs. +With MVC, it also supports forwarding to a local handler through the `forward()` method. +To use the `ProxyExchange`, include the right module in your classpath (either `spring-cloud-gateway-mvc` or `spring-cloud-gateway-webflux`). + +The following MVC example proxies a request to `/test` downstream to a remote server: + +[source,java] +---- +@RestController +@SpringBootApplication +public class GatewaySampleApplication { + + @Value("${remote.home}") + private URI home; + + @GetMapping("/test") + public ResponseEntity proxy(ProxyExchange proxy) throws Exception { + return proxy.uri(home.toString() + "/image/png").get(); + } + +} +---- + +The following example does the same thing with Webflux: + +[source,java] +---- +@RestController +@SpringBootApplication +public class GatewaySampleApplication { + + @Value("${remote.home}") + private URI home; + + @GetMapping("/test") + public Mono> proxy(ProxyExchange proxy) throws Exception { + return proxy.uri(home.toString() + "/image/png").get(); + } + +} +---- + +Convenience methods on the `ProxyExchange` enable the handler method to discover and enhance the URI path of the incoming request. +For example, you might want to extract the trailing elements of a path to pass them downstream: + +[source,java] +---- +@GetMapping("/proxy/path/**") +public ResponseEntity proxyPath(ProxyExchange proxy) throws Exception { + String path = proxy.path("/proxy/path/"); + return proxy.uri(home.toString() + "/foos/" + path).get(); +} +---- + +All the features of Spring MVC and Webflux are available to gateway handler methods. +As a result, you can inject request headers and query parameters, for instance, and you can constrain the incoming requests with declarations in the mapping annotation. +See the documentation for `@RequestMapping` in Spring MVC for more details of those features. + +You can add headers to the downstream response by using the `header()` methods on `ProxyExchange`. + +You can also manipulate response headers (and anything else you like in the response) by adding a mapper to the `get()` method (and other methods). +The mapper is a `Function` that takes the incoming `ResponseEntity` and converts it to an outgoing one. + +First-class support is provided for "`sensitive`" headers (by default, `cookie` and `authorization`), which are not passed downstream, and for "`proxy`" (`x-forwarded-*`) headers. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway-server-mvc.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway-server-mvc.adoc new file mode 100644 index 000000000..24ce7b0f5 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway-server-mvc.adoc @@ -0,0 +1,5 @@ +[[spring-cloud-gateway-server-mvc]] += Spring Cloud Gateway Server MVC +:page-section-summary-toc: 1 + +// TODO: diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway-server-mvc/starter.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway-server-mvc/starter.adoc new file mode 100644 index 000000000..7924560ee --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway-server-mvc/starter.adoc @@ -0,0 +1,14 @@ +[[gateway-starter]] += How to Include Spring Cloud Gateway Server MVC +:page-section-summary-toc: 1 + +To include Spring Cloud Gateway Server MVC in your project, use the starter with a group ID of `org.springframework.cloud` and an artifact ID of `spring-cloud-starter-gateway-mvc`. +See the https://projects.spring.io/spring-cloud/[Spring Cloud Project page] for details on setting up your build system with the current Spring Cloud Release Train. + +If you include the starter, but you do not want the gateway to be enabled, set `spring.cloud.gateway.enabled=false`. + +IMPORTANT: Spring Cloud Gateway Server MVC is built on https://spring.io/projects/spring-boot#learn[Spring Boot] and https://docs.spring.io/spring-framework/reference/web.html[Spring Web MVC]. +As a consequence, many of the asynchronous or reactive libraries may not apply when you use Spring Cloud Gateway Server MVC. + +IMPORTANT: Spring Cloud Gateway Server MVC works with traditional Servlet runtimes such as Tomcat and Jetty. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway.adoc new file mode 100644 index 000000000..1f8964426 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway.adoc @@ -0,0 +1,7 @@ +[[spring-cloud-gateway]] += Spring Cloud Gateway Reactive Server +:page-section-summary-toc: 1 + +*{spring-cloud-version}* + + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/actuator-api.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/actuator-api.adoc new file mode 100644 index 000000000..c7d09a280 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/actuator-api.adoc @@ -0,0 +1,291 @@ +[[actuator-api]] += Actuator API + +The `/gateway` actuator endpoint lets you monitor and interact with a Spring Cloud Gateway application. +To be remotely accessible, the endpoint has to be https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.html#production-ready-endpoints-enabling-endpoints[enabled] and https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.html#production-ready-endpoints-exposing-endpoints[exposed over HTTP or JMX] in the application properties. +The following listing shows how to do so: + +.application.properties +[source,properties] +---- +management.endpoint.gateway.enabled=true # default value +management.endpoints.web.exposure.include=gateway +---- + +[[verbose-actuator-format]] +== Verbose Actuator Format + +A new, more verbose format has been added to Spring Cloud Gateway. +It adds more detail to each route, letting you view the predicates and filters associated with each route along with any configuration that is available. +The following example configures `/actuator/gateway/routes`: + +[source,json] +---- +[ + { + "predicate": "(Hosts: [**.addrequestheader.org] && Paths: [/headers], match trailing slash: true)", + "route_id": "add_request_header_test", + "filters": [ + "[[AddResponseHeader X-Response-Default-Foo = 'Default-Bar'], order = 1]", + "[[AddRequestHeader X-Request-Foo = 'Bar'], order = 1]", + "[[PrefixPath prefix = '/httpbin'], order = 2]" + ], + "uri": "lb://testservice", + "order": 0 + } +] +---- + +This feature is enabled by default. To disable it, set the following property: + +.application.properties +[source,properties] +---- +spring.cloud.gateway.actuator.verbose.enabled=false +---- + +This will default to `true` in a future release. + +[[retrieving-route-filters]] +== Retrieving Route Filters + +This section details how to retrieve route filters, including: + +* xref:spring-cloud-gateway/actuator-api.adoc#gateway-global-filters[Global Filters] +* <> + +[[gateway-global-filters]] +=== Global Filters + +To retrieve the xref:spring-cloud-gateway/global-filters.adoc[global filters] applied to all routes, make a `GET` request to `/actuator/gateway/globalfilters`. The resulting response is similar to the following: + +---- +{ + "org.springframework.cloud.gateway.filter.ReactiveLoadBalancerClientFilter@77856cc5": 10100, + "org.springframework.cloud.gateway.filter.RouteToRequestUrlFilter@4f6fd101": 10000, + "org.springframework.cloud.gateway.filter.NettyWriteResponseFilter@32d22650": -1, + "org.springframework.cloud.gateway.filter.ForwardRoutingFilter@106459d9": 2147483647, + "org.springframework.cloud.gateway.filter.NettyRoutingFilter@1fbd5e0": 2147483647, + "org.springframework.cloud.gateway.filter.ForwardPathFilter@33a71d23": 0, + "org.springframework.cloud.gateway.filter.AdaptCachedBodyGlobalFilter@135064ea": 2147483637, + "org.springframework.cloud.gateway.filter.WebsocketRoutingFilter@23c05889": 2147483646 +} +---- + +The response contains the details of the global filters that are in place. +For each global filter, there is a string representation of the filter object (for example, `org.springframework.cloud.gateway.filter.ReactiveLoadBalancerClientFilter@77856cc5`) and the corresponding xref:spring-cloud-gateway/global-filters.adoc#gateway-combined-global-filter-and-gatewayfilter-ordering[order] in the filter chain. + +[[gateway-route-filters]] +=== Route Filters +To retrieve the xref:spring-cloud-gateway/gatewayfilter-factories.adoc[`GatewayFilter` factories] applied to routes, make a `GET` request to `/actuator/gateway/routefilters`. +The resulting response is similar to the following: + +---- +{ + "[AddRequestHeaderGatewayFilterFactory@570ed9c configClass = AbstractNameValueGatewayFilterFactory.NameValueConfig]": null, + "[SecureHeadersGatewayFilterFactory@fceab5d configClass = Object]": null, + "[SaveSessionGatewayFilterFactory@4449b273 configClass = Object]": null +} +---- + +The response contains the details of the `GatewayFilter` factories applied to any particular route. +For each factory there is a string representation of the corresponding object (for example, `[SecureHeadersGatewayFilterFactory@fceab5d configClass = Object]`). +Note that the `null` value is due to an incomplete implementation of the endpoint controller, because it tries to set the order of the object in the filter chain, which does not apply to a `GatewayFilter` factory object. + +[[refreshing-the-route-cache]] +== Refreshing the Route Cache + +To clear the routes cache, make a `POST` request to `/actuator/gateway/refresh`. +The request returns a 200 without a response body. + +To clear the routes with specific metadata values, add the Query parameter `metadata` specifying the `key:value` pairs that the routes to be cleared should match. +If an error is produced during the asynchronous refresh, the refresh will not modify the existing routes. + +Sending `POST` request to `/actuator/gateway/refresh?metadata=group:group-1` will only refresh the routes whose `group` metadata is `group-1`: `first_route` and `third_route`. +[source,json] +---- +[{ + "route_id": "first_route", + "route_object": { + "predicate": "...", + }, + "metadata": { "group": "group-1" } +}, +{ + "route_id": "second_route", + "route_object": { + "predicate": "...", + }, + "metadata": { "group": "group-2" } +}, +{ + "route_id": "third_route", + "route_object": { + "predicate": "...", + }, + "metadata": { "group": "group-1" } +}] +---- + +[[retrieving-the-routes-defined-in-the-gateway]] +== Retrieving the Routes Defined in the Gateway + +To retrieve the routes defined in the gateway, make a `GET` request to `/actuator/gateway/routes`. +The resulting response is similar to the following: + +---- +[{ + "route_id": "first_route", + "route_object": { + "predicate": "org.springframework.cloud.gateway.handler.predicate.PathRoutePredicateFactory$$Lambda$432/1736826640@1e9d7e7d", + "filters": [ + "OrderedGatewayFilter{delegate=org.springframework.cloud.gateway.filter.factory.PreserveHostHeaderGatewayFilterFactory$$Lambda$436/674480275@6631ef72, order=0}" + ] + }, + "order": 0 +}, +{ + "route_id": "second_route", + "route_object": { + "predicate": "org.springframework.cloud.gateway.handler.predicate.PathRoutePredicateFactory$$Lambda$432/1736826640@cd8d298", + "filters": [] + }, + "order": 0 +}] +---- + +The response contains the details of all the routes defined in the gateway. +The following table describes the structure of each element (each is a route) of the response: + +[cols="3,2,4"] +|=== +| Path | Type | Description + +|`route_id` +| String +| The route ID. + +|`route_object.predicate` +| Object +| The route predicate. + +|`route_object.filters` +| Array +| The xref:spring-cloud-gateway/gatewayfilter-factories.adoc[`GatewayFilter` factories] applied to the route. + +|`order` +| Number +| The route order. + +|=== + +[[gateway-retrieving-information-about-a-particular-route]] +== Retrieving Information about a Particular Route + +To retrieve information about a single route, make a `GET` request to `/actuator/gateway/routes/\{id}` (for example, `/actuator/gateway/routes/first_route`). +The resulting response is similar to the following: + +---- +{ + "id": "first_route", + "predicates": [{ + "name": "Path", + "args": {"_genkey_0":"/first"} + }], + "filters": [], + "uri": "https://www.uri-destination.org", + "order": 0 +} +---- + +The following table describes the structure of the response: + +[cols="3,2,4"] +|=== +| Path | Type | Description + +|`id` +| String +| The route ID. + +|`predicates` +| Array +| The collection of route predicates. Each item defines the name and the arguments of a given predicate. + +|`filters` +| Array +| The collection of filters applied to the route. + +|`uri` +| String +| The destination URI of the route. + +|`order` +| Number +| The route order. + +|=== + +[[creating-and-deleting-a-particular-route-definition]] +== Creating and Deleting a Particular Route Definition + +To create a route definition, make a `POST` request to `/gateway/routes/\{id_route_to_create}` with a JSON body that specifies the fields of the route (see xref:spring-cloud-gateway/actuator-api.adoc#gateway-retrieving-information-about-a-particular-route[Retrieving Information about a Particular Route]). + +To delete a route definition, make a `DELETE` request to `/gateway/routes/\{id_route_to_delete}`. + +[[creating-multiple-route-definitions]] +== Creating multiple Route Definitions + +To create multiple route definitions in a single request, make a `POST` request to `/gateway/routes` with a JSON body that specifies the fields of the route, including the route id (see xref:spring-cloud-gateway/actuator-api.adoc#gateway-retrieving-information-about-a-particular-route[Retrieving Information about a Particular Route]). + +The route definitions will be discarded if any route raises an error during the creation of the routes. + +[[recap:-the-list-of-all-endpoints]] +== Recap: The List of All endpoints + +The following table below summarizes the Spring Cloud Gateway actuator endpoints (note that each endpoint has `/actuator/gateway` as the base-path): + +[cols="2,2,5"] +|=== +| ID | HTTP Method | Description + +|`globalfilters` +|GET +| Displays the list of global filters applied to the routes. + +|`routefilters` +|GET +| Displays the list of `GatewayFilter` factories applied to a particular route. + +|`refresh` +|POST +| Clears the routes cache. + +|`routes` +|GET +| Displays the list of routes defined in the gateway. + +|`routes/\{id}` +|GET +| Displays information about a particular route. + +|`routes/\{id}` +|POST +| Adds a new route to the gateway. + +|`routes/\{id}` +|DELETE +| Removes an existing route from the gateway. + +|=== + +[[sharing-routes-between-multiple-gateway-instances]] +== Sharing Routes between multiple Gateway instances +Spring Cloud Gateway offers two `RouteDefinitionRepository` implementations. The first one is the +`InMemoryRouteDefinitionRepository` which only lives within the memory of one Gateway instance. +This type of Repository is not suited to populate Routes across multiple Gateway instances. + +In order to share Routes across a cluster of Spring Cloud Gateway instances, `RedisRouteDefinitionRepository` can be used. +To enable this kind of repository, the following property has to set to true: `spring.cloud.gateway.redis-route-definition-repository.enabled` +Likewise to the RedisRateLimiter Filter Factory it requires the use of the spring-boot-starter-data-redis-reactive Spring Boot starter. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/aot-and-native-image-support.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/aot-and-native-image-support.adoc new file mode 100644 index 000000000..c7d01c71b --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/aot-and-native-image-support.adoc @@ -0,0 +1,8 @@ +[[aot-and-native-image-support]] += AOT and Native Image Support +:page-section-summary-toc: 1 + +Since `4.0.0`, Spring Cloud Gateway supports Spring AOT transformations and native images. + +TIP: If you're using load-balanced routes, you need to explicitly define your `LoadBalancerClient` service IDs. You can do so by using the `value` or `name` attributes of the `@LoadBalancerClient` annotation or as values of the `spring.cloud.loadbalancer.eager-load.clients` property. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/configuration-properties.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/configuration-properties.adoc new file mode 100644 index 000000000..1aed51731 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/configuration-properties.adoc @@ -0,0 +1,5 @@ +[[configuration-properties]] += Configuration properties +:page-section-summary-toc: 1 + +To see the list of all Spring Cloud Gateway related configuration properties, see link:appendix.html[the appendix]. diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/configuration.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/configuration.adoc new file mode 100644 index 000000000..0770f4d77 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/configuration.adoc @@ -0,0 +1,45 @@ +[[configuration]] += Configuration + +Configuration for Spring Cloud Gateway is driven by a collection of `RouteDefinitionLocator` instances. +The following listing shows the definition of the `RouteDefinitionLocator` interface: + +.RouteDefinitionLocator.java +[source,java] +---- +public interface RouteDefinitionLocator { + Flux getRouteDefinitions(); +} +---- + +By default, a `PropertiesRouteDefinitionLocator` loads properties by using Spring Boot's `@ConfigurationProperties` mechanism. + +The earlier configuration examples all use a shortcut notation that uses positional arguments rather than named ones. +The following two examples are equivalent: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: setstatus_route + uri: https://example.org + filters: + - name: SetStatus + args: + status: 401 + - id: setstatusshortcut_route + uri: https://example.org + filters: + - SetStatus=401 +---- + +For some usages of the gateway, properties are adequate, but some production use cases benefit from loading configuration from an external source, such as a database. Future milestone versions will have `RouteDefinitionLocator` implementations based off of Spring Data Repositories, such as Redis, MongoDB, and Cassandra. + +[[routedefinition-metrics]] +== RouteDefinition Metrics + +To enable `RouteDefinition` metrics, add spring-boot-starter-actuator as a project dependency. Then, by default, the metrics will be available as long as the property `spring.cloud.gateway.metrics.enabled` is set to `true`. A gauge metric named `spring.cloud.gateway.routes.count` will be added, whose value is the number of `RouteDefinitions`. This metric will be available from `/actuator/metrics/spring.cloud.gateway.routes.count`. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/configuring-route-predicate-factories-and-filter-factories.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/configuring-route-predicate-factories-and-filter-factories.adoc new file mode 100644 index 000000000..9ab70bad8 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/configuring-route-predicate-factories-and-filter-factories.adoc @@ -0,0 +1,50 @@ +[[configuring-route-predicate-factories-and-gateway-filter-factories]] += Configuring Route Predicate Factories and Gateway Filter Factories + +There are two ways to configure predicates and filters: shortcuts and fully expanded arguments. Most examples below use the shortcut way. + +The name and argument names are listed as `code` in the first sentence or two of each section. The arguments are typically listed in the order that are needed for the shortcut configuration. + +[[shortcut-configuration]] +== Shortcut Configuration + +Shortcut configuration is recognized by the filter name, followed by an equals sign (`=`), followed by argument values separated by commas (`,`). + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: after_route + uri: https://example.org + predicates: + - Cookie=mycookie,mycookievalue +---- + +The previous sample defines the `Cookie` Route Predicate Factory with two arguments, the cookie name, `mycookie` and the value to match `mycookievalue`. + +[[fully-expanded-arguments]] +== Fully Expanded Arguments + +Fully expanded arguments appear more like standard yaml configuration with name/value pairs. Typically, there will be a `name` key and an `args` key. The `args` key is a map of key value pairs to configure the predicate or filter. + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: after_route + uri: https://example.org + predicates: + - name: Cookie + args: + name: mycookie + regexp: mycookievalue +---- + +This is the full configuration of the shortcut configuration of the `Cookie` predicate shown above. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/cors-configuration.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/cors-configuration.adoc new file mode 100644 index 000000000..99a562c3d --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/cors-configuration.adoc @@ -0,0 +1,61 @@ +[[cors-configuration]] += CORS Configuration +:cors-configuration-docs-uri: https://docs.spring.io/spring/docs/5.0.x/javadoc-api/org/springframework/web/cors/CorsConfiguration.html + +You can configure the gateway to control CORS behavior globally or per route. +Both offer the same possibilities. + +[[global-cors-configuration]] +== Global CORS Configuration + +The "`global`" CORS configuration is a map of URL patterns to {cors-configuration-docs-uri}[Spring Framework `CorsConfiguration`]. +The following example configures CORS: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + globalcors: + cors-configurations: + '[/**]': + allowedOrigins: "https://docs.spring.io" + allowedMethods: + - GET +---- + +In the preceding example, CORS requests are allowed from requests that originate from `docs.spring.io` for all GET requested paths. + +To provide the same CORS configuration to requests that are not handled by some gateway route predicate, set the `spring.cloud.gateway.globalcors.add-to-simple-url-handler-mapping` property to `true`. +This is useful when you try to support CORS preflight requests and your route predicate does not evaluate to `true` because the HTTP method is `options`. + +[[route-cors-configuration]] +== Route CORS Configuration + +The "`route`" configuration allows applying CORS directly to a route as metadata with key `cors`. +Like in the case of global configuration, the properties belong to {cors-configuration-docs-uri}[Spring Framework `CorsConfiguration`]. + +NOTE: If no `Path` predicate is present in the route '/**' will be applied. + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: cors_route + uri: https://example.org + predicates: + - Path=/service/** + metadata: + cors + allowedOrigins: '*' + allowedMethods: + - GET + - POST + allowedHeaders: '*' + maxAge: 30 +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/developer-guide.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/developer-guide.adoc new file mode 100644 index 000000000..2ba6507d2 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/developer-guide.adoc @@ -0,0 +1,156 @@ +[[developer-guide]] += Developer Guide + +These are basic guides to writing some custom components of the gateway. + +[[writing-custom-route-predicate-factories]] +== Writing Custom Route Predicate Factories + + +In order to write a Route Predicate you will need to implement `RoutePredicateFactory` as a bean. There is an abstract class called `AbstractRoutePredicateFactory` which you can extend. + +.MyRoutePredicateFactory.java +[source,java] +---- +@Component +public class MyRoutePredicateFactory extends AbstractRoutePredicateFactory { + + public MyRoutePredicateFactory() { + super(Config.class); + } + + @Override + public Predicate apply(Config config) { + // grab configuration from Config object + return exchange -> { + //grab the request + ServerHttpRequest request = exchange.getRequest(); + //take information from the request to see if it + //matches configuration. + return matches(config, request); + }; + } + + public static class Config { + //Put the configuration properties for your filter here + } + +} +---- +[[writing-custom-gatewayfilter-factories]] +== Writing Custom GatewayFilter Factories + +To write a `GatewayFilter`, you must implement `GatewayFilterFactory` as a bean. +You can extend an abstract class called `AbstractGatewayFilterFactory`. +The following examples show how to do so: + +.PreGatewayFilterFactory.java +==== +[source,java] +---- +@Component +public class PreGatewayFilterFactory extends AbstractGatewayFilterFactory { + + public PreGatewayFilterFactory() { + super(Config.class); + } + + @Override + public GatewayFilter apply(Config config) { + // grab configuration from Config object + return (exchange, chain) -> { + //If you want to build a "pre" filter you need to manipulate the + //request before calling chain.filter + ServerHttpRequest.Builder builder = exchange.getRequest().mutate(); + //use builder to manipulate the request + return chain.filter(exchange.mutate().request(builder.build()).build()); + }; + } + + public static class Config { + //Put the configuration properties for your filter here + } + +} +---- + +.PostGatewayFilterFactory.java +[source,java] +---- +@Component +public class PostGatewayFilterFactory extends AbstractGatewayFilterFactory { + + public PostGatewayFilterFactory() { + super(Config.class); + } + + @Override + public GatewayFilter apply(Config config) { + // grab configuration from Config object + return (exchange, chain) -> { + return chain.filter(exchange).then(Mono.fromRunnable(() -> { + ServerHttpResponse response = exchange.getResponse(); + //Manipulate the response in some way + })); + }; + } + + public static class Config { + //Put the configuration properties for your filter here + } + +} +---- +==== + +[[naming-custom-filters-and-references-in-configuration]] +=== Naming Custom Filters And References In Configuration + +Custom filters class names should end in `GatewayFilterFactory`. + +For example, to reference a filter named `Something` in configuration files, the filter +must be in a class named `SomethingGatewayFilterFactory`. + +WARNING: It is possible to create a gateway filter named without the +`GatewayFilterFactory` suffix, such as `class AnotherThing`. This filter could be +referenced as `AnotherThing` in configuration files. This is **not** a supported naming +convention and this syntax may be removed in future releases. Please update the filter +name to be compliant. + +[[writing-custom-global-filters]] +== Writing Custom Global Filters + +To write a custom global filter, you must implement `GlobalFilter` interface as a bean. +This applies the filter to all requests. + +The following examples show how to set up global pre- and post-filters, respectively: + +[source,java] +---- +@Bean +public GlobalFilter customGlobalFilter() { + return (exchange, chain) -> exchange.getPrincipal() + .map(Principal::getName) + .defaultIfEmpty("Default User") + .map(userName -> { + //adds header to proxied request + exchange.getRequest().mutate().header("CUSTOM-REQUEST-HEADER", userName).build(); + return exchange; + }) + .flatMap(chain::filter); +} + +@Bean +public GlobalFilter customGlobalPostFilter() { + return (exchange, chain) -> chain.filter(exchange) + .then(Mono.just(exchange)) + .map(serverWebExchange -> { + //adds header to response + serverWebExchange.getResponse().getHeaders().set("CUSTOM-RESPONSE-HEADER", + HttpStatus.OK.equals(serverWebExchange.getResponse().getStatusCode()) ? "It worked": "It did not work"); + return serverWebExchange; + }) + .then(); +} +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/fluent-java-routes-api.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/fluent-java-routes-api.adoc new file mode 100644 index 000000000..b9a87f6fa --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/fluent-java-routes-api.adoc @@ -0,0 +1,41 @@ +[[fluent-java-routes-api]] += Fluent Java Routes API + +To allow for simple configuration in Java, the `RouteLocatorBuilder` bean includes a fluent API. +The following listing shows how it works: + +.GatewaySampleApplication.java +[source,java] +---- +// static imports from GatewayFilters and RoutePredicates +@Bean +public RouteLocator customRouteLocator(RouteLocatorBuilder builder, ThrottleGatewayFilterFactory throttle) { + return builder.routes() + .route(r -> r.host("**.abc.org").and().path("/image/png") + .filters(f -> + f.addResponseHeader("X-TestHeader", "foobar")) + .uri("http://httpbin.org:80") + ) + .route(r -> r.path("/image/webp") + .filters(f -> + f.addResponseHeader("X-AnotherHeader", "baz")) + .uri("http://httpbin.org:80") + .metadata("key", "value") + ) + .route(r -> r.order(-1) + .host("**.throttle.org").and().path("/get") + .filters(f -> f.filter(throttle.apply(1, + 1, + 10, + TimeUnit.SECONDS))) + .uri("http://httpbin.org:80") + .metadata("key", "value") + ) + .build(); +} +---- + +This style also allows for more custom predicate assertions. +The predicates defined by `RouteDefinitionLocator` beans are combined using logical `and`. +By using the fluent Java API, you can use the `and()`, `or()`, and `negate()` operators on the `Predicate` class. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories.adoc new file mode 100644 index 000000000..76c6951f1 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories.adoc @@ -0,0 +1,10 @@ +[[gatewayfilter-factories]] += `GatewayFilter` Factories +:page-section-summary-toc: 1 + +Route filters allow the modification of the incoming HTTP request or outgoing HTTP response in some manner. +Route filters are scoped to a particular route. +Spring Cloud Gateway includes many built-in GatewayFilter Factories. + +NOTE: For more detailed examples of how to use any of the following filters, take a look at the https://github.com/spring-cloud/spring-cloud-gateway/tree/master/spring-cloud-gateway-server/src/test/java/org/springframework/cloud/gateway/filter/factory[unit tests]. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/circuitbreaker-filter-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/circuitbreaker-filter-factory.adoc new file mode 100644 index 000000000..ab1e0d08e --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/circuitbreaker-filter-factory.adoc @@ -0,0 +1,168 @@ +[[spring-cloud-circuitbreaker-filter-factory]] += The `CircuitBreaker` `GatewayFilter` Factory + +The Spring Cloud CircuitBreaker GatewayFilter factory uses the Spring Cloud CircuitBreaker APIs to wrap Gateway routes in +a circuit breaker. Spring Cloud CircuitBreaker supports multiple libraries that can be used with Spring Cloud Gateway. Spring Cloud supports Resilience4J out of the box. + +To enable the Spring Cloud CircuitBreaker filter, you need to place `spring-cloud-starter-circuitbreaker-reactor-resilience4j` on the classpath. +The following example configures a Spring Cloud CircuitBreaker `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: circuitbreaker_route + uri: https://example.org + filters: + - CircuitBreaker=myCircuitBreaker +---- + +To configure the circuit breaker, see the configuration for the underlying circuit breaker implementation you are using. + +* https://cloud.spring.io/spring-cloud-circuitbreaker/reference/html/spring-cloud-circuitbreaker.html[Resilience4J Documentation] + +The Spring Cloud CircuitBreaker filter can also accept an optional `fallbackUri` parameter. +Currently, only `forward:` schemed URIs are supported. +If the fallback is called, the request is forwarded to the controller matched by the URI. +The following example configures such a fallback: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: circuitbreaker_route + uri: lb://backing-service:8088 + predicates: + - Path=/consumingServiceEndpoint + filters: + - name: CircuitBreaker + args: + name: myCircuitBreaker + fallbackUri: forward:/inCaseOfFailureUseThis + - RewritePath=/consumingServiceEndpoint, /backingServiceEndpoint +---- + +The following listing does the same thing in Java: + +.Application.java +[source,java] +---- +@Bean +public RouteLocator routes(RouteLocatorBuilder builder) { + return builder.routes() + .route("circuitbreaker_route", r -> r.path("/consumingServiceEndpoint") + .filters(f -> f.circuitBreaker(c -> c.name("myCircuitBreaker").fallbackUri("forward:/inCaseOfFailureUseThis")) + .rewritePath("/consumingServiceEndpoint", "/backingServiceEndpoint")).uri("lb://backing-service:8088") + .build(); +} +---- + +This example forwards to the `/inCaseofFailureUseThis` URI when the circuit breaker fallback is called. +Note that this example also demonstrates the (optional) Spring Cloud LoadBalancer load-balancing (defined by the `lb` prefix on the destination URI). + +CircuitBreaker also supports URI variables in the `fallbackUri`. +This allows more complex routing options, like forwarding sections of the original host or url path using https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/util/pattern/PathPattern.html[PathPattern expression]. + +In the example below the call `consumingServiceEndpoint/users/1` will be redirected to `inCaseOfFailureUseThis/users/1`. + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: circuitbreaker_route + uri: lb://backing-service:8088 + predicates: + - Path=/consumingServiceEndpoint/{*segments} + filters: + - name: CircuitBreaker + args: + name: myCircuitBreaker + fallbackUri: forward:/inCaseOfFailureUseThis/{segments} +---- + +The primary scenario is to use the `fallbackUri` to define an internal controller or handler within the gateway application. +However, you can also reroute the request to a controller or handler in an external application, as follows: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: ingredients + uri: lb://ingredients + predicates: + - Path=//ingredients/** + filters: + - name: CircuitBreaker + args: + name: fetchIngredients + fallbackUri: forward:/fallback + - id: ingredients-fallback + uri: http://localhost:9994 + predicates: + - Path=/fallback +---- + +In this example, there is no `fallback` endpoint or handler in the gateway application. +However, there is one in another application, registered under `http://localhost:9994`. + +In case of the request being forwarded to fallback, the Spring Cloud CircuitBreaker Gateway filter also provides the `Throwable` that has caused it. +It is added to the `ServerWebExchange` as the `ServerWebExchangeUtils.CIRCUITBREAKER_EXECUTION_EXCEPTION_ATTR` attribute that can be used when handling the fallback within the gateway application. + +For the external controller/handler scenario, headers can be added with exception details. +You can find more information on doing so in the xref:spring-cloud-gateway/gatewayfilter-factories/fallback-headers.adoc[FallbackHeaders GatewayFilter Factory section]. + +[[circuit-breaker-status-codes]] +== Tripping The Circuit Breaker On Status Codes + +In some cases you might want to trip a circuit breaker based on the status code +returned from the route it wraps. The circuit breaker config object takes a list of +status codes that if returned will cause the circuit breaker to be tripped. When setting the +status codes you want to trip the circuit breaker you can either use an integer with the status code +value or the String representation of the `HttpStatus` enumeration. + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: circuitbreaker_route + uri: lb://backing-service:8088 + predicates: + - Path=/consumingServiceEndpoint + filters: + - name: CircuitBreaker + args: + name: myCircuitBreaker + fallbackUri: forward:/inCaseOfFailureUseThis + statusCodes: + - 500 + - "NOT_FOUND" +---- + +.Application.java +[source,java] +---- +@Bean +public RouteLocator routes(RouteLocatorBuilder builder) { + return builder.routes() + .route("circuitbreaker_route", r -> r.path("/consumingServiceEndpoint") + .filters(f -> f.circuitBreaker(c -> c.name("myCircuitBreaker").fallbackUri("forward:/inCaseOfFailureUseThis").addStatusCode("INTERNAL_SERVER_ERROR")) + .rewritePath("/consumingServiceEndpoint", "/backingServiceEndpoint")).uri("lb://backing-service:8088") + .build(); +} +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/default-filters.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/default-filters.adoc new file mode 100644 index 000000000..bc7038486 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/default-filters.adoc @@ -0,0 +1,19 @@ +[[default-filters]] += Default Filters +:page-section-summary-toc: 1 + +To add a filter and apply it to all routes, you can use `spring.cloud.gateway.default-filters`. +This property takes a list of filters. +The following listing defines a set of default filters: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + default-filters: + - AddResponseHeader=X-Response-Default-Red, Default-Blue + - PrefixPath=/httpbin +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/fallback-headers.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/fallback-headers.adoc new file mode 100644 index 000000000..f753e30a3 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/fallback-headers.adoc @@ -0,0 +1,43 @@ +[[fallback-headers]] += The `FallbackHeaders` `GatewayFilter` Factory + +The `FallbackHeaders` factory lets you add Spring Cloud CircuitBreaker execution exception details in the headers of a request forwarded to a `fallbackUri` in an external application, as in the following scenario: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: ingredients + uri: lb://ingredients + predicates: + - Path=//ingredients/** + filters: + - name: CircuitBreaker + args: + name: fetchIngredients + fallbackUri: forward:/fallback + - id: ingredients-fallback + uri: http://localhost:9994 + predicates: + - Path=/fallback + filters: + - name: FallbackHeaders + args: + executionExceptionTypeHeaderName: Test-Header +---- + +In this example, after an execution exception occurs while running the circuit breaker, the request is forwarded to the `fallback` endpoint or handler in an application running on `localhost:9994`. +The headers with the exception type, message and (if available) root cause exception type and message are added to that request by the `FallbackHeaders` filter. + +You can overwrite the names of the headers in the configuration by setting the values of the following arguments (shown with their default values): + +* `executionExceptionTypeHeaderName` (`"Execution-Exception-Type"`) +* `executionExceptionMessageHeaderName` (`"Execution-Exception-Message"`) +* `rootCauseExceptionTypeHeaderName` (`"Root-Cause-Exception-Type"`) +* `rootCauseExceptionMessageHeaderName` (`"Root-Cause-Exception-Message"`) + +For more information on circuit breakers and the gateway see the xref:spring-cloud-gateway/gatewayfilter-factories/circuitbreaker-filter-factory.adoc[Spring Cloud CircuitBreaker Factory section]. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/local-cache-response-filter.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/local-cache-response-filter.adoc new file mode 100644 index 000000000..14a9fea76 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/local-cache-response-filter.adoc @@ -0,0 +1,55 @@ +[[local-cache-response-filter]] += The `LocalResponseCache` `GatewayFilter` Factory + +This filter allows caching the response body and headers to follow these rules: + +* It can only cache bodiless GET requests. +* It caches the response only for one of the following status codes: HTTP 200 (OK), HTTP 206 (Partial Content), or HTTP 301 (Moved Permanently). +* Response data is not cached if `Cache-Control` header does not allow it (`no-store` present in the request or `no-store` or `private` present in the response). +* If the response is already cached and a new request is performed with no-cache value in `Cache-Control` header, it returns a bodiless response with 304 (Not Modified). + +This filter configures the local response cache per route and is available only if the `spring.cloud.gateway.filter.local-response-cache.enabled` property is enabled. And a xref:spring-cloud-gateway/global-filters.adoc#local-cache-response-global-filter[local response cache configured globally] is also available as feature. + +It accepts the first parameter to override the time to expire a cache entry (expressed in `s` for seconds, `m` for minutes, and `h` for hours) and a second parameter to set the maximum size of the cache to evict entries for this route (`KB`, `MB`, or `GB`). + +The following listing shows how to add local response cache `GatewayFilter`: + +[source,java] +---- +@Bean +public RouteLocator routes(RouteLocatorBuilder builder) { + return builder.routes() + .route("rewrite_response_upper", r -> r.host("*.rewriteresponseupper.org") + .filters(f -> f.prefixPath("/httpbin") + .localResponseCache(Duration.ofMinutes(30), "500MB") + ).uri(uri)) + .build(); +} +---- + +or this + +.application.yaml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: resource + uri: http://localhost:9000 + predicates: + - Path=/resource + filters: + - LocalResponseCache=30m,500MB +---- + +NOTE: This filter also automatically calculates the `max-age` value in the HTTP `Cache-Control` header. +Only if `max-age` is present on the original response is the value rewritten with the number of seconds set in the `timeToLive` configuration parameter. +In consecutive calls, this value is recalculated with the number of seconds left until the response expires. + +NOTE: To enable this feature, add `com.github.ben-manes.caffeine:caffeine` and `spring-boot-starter-cache` as project dependencies. + +WARNING: If your project creates custom `CacheManager` beans, it will either need to be marked with `@Primary` or injected using `@Qualifier`. + + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/removejsonattributesresponsebody-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/removejsonattributesresponsebody-factory.adoc new file mode 100644 index 000000000..e33f97b07 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/removejsonattributesresponsebody-factory.adoc @@ -0,0 +1,42 @@ +[[removejsonattributesresponsebody-gatewayfilter-factory]] += `RemoveJsonAttributesResponseBody` `GatewayFilter` Factory + +The `RemoveJsonAttributesResponseBody` `GatewayFilter` factory takes a collection of `attribute names` to search for, an optional last parameter from the list can be a boolean to remove the attributes just at root level (that's the default value if not present at the end of the parameter configuration, `false`) or recursively (`true`). +It provides a convenient method to apply a transformation to JSON body content by deleting attributes from it. + +The following example configures an `RemoveJsonAttributesResponseBody` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: removejsonattributes_route + uri: https://example.org + filters: + - RemoveJsonAttributesResponseBody=id,color +---- + +This removes attributes "id" and "color" from the JSON content body at root level. + +The following example configures an `RemoveJsonAttributesResponseBody` `GatewayFilter` that uses the optional last parameter: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: removejsonattributes_recursively_route + uri: https://example.org + predicates: + - Path=/red/{segment} + filters: + - RemoveJsonAttributesResponseBody=id,color,true +---- + +This removes attributes "id" and "color" from the JSON content body at any level. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-addrequestheader-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-addrequestheader-factory.adoc new file mode 100644 index 000000000..47063c518 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-addrequestheader-factory.adoc @@ -0,0 +1,40 @@ +[[the-addrequestheader-gatewayfilter-factory]] += The `AddRequestHeader` `GatewayFilter` Factory + +The `AddRequestHeader` `GatewayFilter` factory takes a `name` and `value` parameter. +The following example configures an `AddRequestHeader` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: add_request_header_route + uri: https://example.org + filters: + - AddRequestHeader=X-Request-red, blue +---- + +This listing adds `X-Request-red:blue` header to the downstream request's headers for all matching requests. + +`AddRequestHeader` is aware of the URI variables used to match a path or host. +URI variables may be used in the value and are expanded at runtime. +The following example configures an `AddRequestHeader` `GatewayFilter` that uses a variable: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: add_request_header_route + uri: https://example.org + predicates: + - Path=/red/{segment} + filters: + - AddRequestHeader=X-Request-Red, Blue-{segment} +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-addrequestheadersifnotpresent-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-addrequestheadersifnotpresent-factory.adoc new file mode 100644 index 000000000..df8a0a146 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-addrequestheadersifnotpresent-factory.adoc @@ -0,0 +1,44 @@ +[[the-addrequestheadersifnotpresent-gatewayfilter-factory]] += The `AddRequestHeadersIfNotPresent` `GatewayFilter` Factory + +The `AddRequestHeadersIfNotPresent` `GatewayFilter` factory takes a collection of `name` and `value` pairs separated by colon. +The following example configures an `AddRequestHeadersIfNotPresent` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: add_request_headers_route + uri: https://example.org + filters: + - AddRequestHeadersIfNotPresent=X-Request-Color-1:blue,X-Request-Color-2:green +---- + +This listing adds 2 headers `X-Request-Color-1:blue` and `X-Request-Color-2:green` to the downstream request's headers for all matching requests. +This is similar to how `AddRequestHeader` works, but unlike `AddRequestHeader` it will do it only if the header is not already there. +Otherwise, the original value in the client request is sent. + +Additionally, to set a multi-valued header, use the header name multiple times like `AddRequestHeadersIfNotPresent=X-Request-Color-1:blue,X-Request-Color-1:green`. + +`AddRequestHeadersIfNotPresent` also supports URI variables used to match a path or host. +URI variables may be used in the value and are expanded at runtime. +The following example configures an `AddRequestHeadersIfNotPresent` `GatewayFilter` that uses a variable: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: add_request_header_route + uri: https://example.org + predicates: + - Path=/red/{segment} + filters: + - AddRequestHeadersIfNotPresent=X-Request-Red:Blue-{segment} +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-addrequestparameter-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-addrequestparameter-factory.adoc new file mode 100644 index 000000000..10f726483 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-addrequestparameter-factory.adoc @@ -0,0 +1,40 @@ +[[the-addrequestparameter-gatewayfilter-factory]] += The `AddRequestParameter` `GatewayFilter` Factory + +The `AddRequestParameter` `GatewayFilter` Factory takes a `name` and `value` parameter. +The following example configures an `AddRequestParameter` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: add_request_parameter_route + uri: https://example.org + filters: + - AddRequestParameter=red, blue +---- + +This will add `red=blue` to the downstream request's query string for all matching requests. + +`AddRequestParameter` is aware of the URI variables used to match a path or host. +URI variables may be used in the value and are expanded at runtime. +The following example configures an `AddRequestParameter` `GatewayFilter` that uses a variable: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: add_request_parameter_route + uri: https://example.org + predicates: + - Host: {segment}.myhost.org + filters: + - AddRequestParameter=foo, bar-{segment} +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-addresponseheader-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-addresponseheader-factory.adoc new file mode 100644 index 000000000..187f2d1a7 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-addresponseheader-factory.adoc @@ -0,0 +1,41 @@ +[[the-addresponseheader-gatewayfilter-factory]] += The `AddResponseHeader` `GatewayFilter` Factory + +The `AddResponseHeader` `GatewayFilter` Factory takes a `name` and `value` parameter. +The following example configures an `AddResponseHeader` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: add_response_header_route + uri: https://example.org + filters: + - AddResponseHeader=X-Response-Red, Blue +---- + +This adds `X-Response-Red:Blue` header to the downstream response's headers for all matching requests. + +`AddResponseHeader` is aware of URI variables used to match a path or host. +URI variables may be used in the value and are expanded at runtime. +The following example configures an `AddResponseHeader` `GatewayFilter` that uses a variable: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: add_response_header_route + uri: https://example.org + predicates: + - Host: {segment}.myhost.org + filters: + - AddResponseHeader=foo, bar-{segment} +---- + + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-cacherequestbody-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-cacherequestbody-factory.adoc new file mode 100644 index 000000000..8f4386699 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-cacherequestbody-factory.adoc @@ -0,0 +1,42 @@ +[[the-cacherequestbody-gatewayfilter-factory]] += The `CacheRequestBody` `GatewayFilter` Factory + +Some situations necessitate reading the request body. Since the request can be read only once, we need to cache the request body. +You can use the `CacheRequestBody` filter to cache the request body before sending it downstream and getting the body from `exchange` attribute. + +The following listing shows how to cache the request body `GatewayFilter`: + +[source,java] +---- +@Bean +public RouteLocator routes(RouteLocatorBuilder builder) { + return builder.routes() + .route("cache_request_body_route", r -> r.path("/downstream/**") + .filters(f -> f.prefixPath("/httpbin") + .cacheRequestBody(String.class).uri(uri)) + .build(); +} +---- + + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: cache_request_body_route + uri: lb://downstream + predicates: + - Path=/downstream/** + filters: + - name: CacheRequestBody + args: + bodyClass: java.lang.String +---- +`CacheRequestBody` extracts the request body and converts it to a body class (such as `java.lang.String`, defined in the preceding example). +`CacheRequestBody` then places it in the attributes available from `ServerWebExchange.getAttributes()`, with a key defined in `ServerWebExchangeUtils.CACHED_REQUEST_BODY_ATTR`. + +NOTE: This filter works only with HTTP (including HTTPS) requests. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-deduperesponseheader-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-deduperesponseheader-factory.adoc new file mode 100644 index 000000000..7868a68b9 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-deduperesponseheader-factory.adoc @@ -0,0 +1,25 @@ +[[the-deduperesponseheader-gatewayfilter-factory]] += The `DedupeResponseHeader` `GatewayFilter` Factory + +The `DedupeResponseHeader` GatewayFilter factory takes a `name` parameter and an optional `strategy` parameter. `name` can contain a space-separated list of header names. +The following example configures a `DedupeResponseHeader` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: dedupe_response_header_route + uri: https://example.org + filters: + - DedupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin +---- + +This removes duplicate values of `Access-Control-Allow-Credentials` and `Access-Control-Allow-Origin` response headers in cases when both the gateway CORS logic and the downstream logic add them. + +The `DedupeResponseHeader` filter also accepts an optional `strategy` parameter. +The accepted values are `RETAIN_FIRST` (default), `RETAIN_LAST`, and `RETAIN_UNIQUE`. + + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-jsontogrpc-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-jsontogrpc-factory.adoc new file mode 100644 index 000000000..c956f6d3f --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-jsontogrpc-factory.adoc @@ -0,0 +1,80 @@ +[[the-jsontogrpc-gatewayfilter-factory]] += The `JsonToGrpc` `GatewayFilter` Factory + +The JSONToGRPCFilter GatewayFilter Factory converts a JSON payload to a gRPC request. + +The filter takes the following arguments: + +* `protoDescriptor`: Proto descriptor file. + +This file can be generated using `protoc` and specifying the `--descriptor_set_out` flag: + +[source,bash] +---- +protoc --proto_path=src/main/resources/proto/ \ +--descriptor_set_out=src/main/resources/proto/hello.pb \ +src/main/resources/proto/hello.proto +---- + +* `protoFile`: Proto definition file. + +* `service`: Short name of the service that handles the request. + +* `method`: Method name in the service that handles the request. + +NOTE: `streaming` is not supported. + + +*application.yml.* + +[source,java] +---- +@Bean +public RouteLocator routes(RouteLocatorBuilder builder) { + return builder.routes() + .route("json-grpc", r -> r.path("/json/hello").filters(f -> { + String protoDescriptor = "file:src/main/proto/hello.pb"; + String protoFile = "file:src/main/proto/hello.proto"; + String service = "HelloService"; + String method = "hello"; + return f.jsonToGRPC(protoDescriptor, protoFile, service, method); + }).uri(uri)) +---- + +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: json-grpc + uri: https://localhost:6565/testhello + predicates: + - Path=/json/** + filters: + - name: JsonToGrpc + args: + protoDescriptor: file:proto/hello.pb + protoFile: file:proto/hello.proto + service: HelloService + method: hello + +---- + +When a request is made through the gateway to `/json/hello`, the request is transformed by using the definition provided in `hello.proto`, sent to `HelloService/hello`, and the response back is transformed to JSON. + +By default, it creates a `NettyChannel` by using the default `TrustManagerFactory`. However, you can customize this `TrustManager` by creating a bean of type `GrpcSslConfigurer`: + +[source,java] +---- + +@Configuration +public class GRPCLocalConfiguration { + @Bean + public GRPCSSLContext sslContext() { + TrustManager trustManager = trustAllCerts(); + return new GRPCSSLContext(trustManager); + } +} +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-maprequestheader-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-maprequestheader-factory.adoc new file mode 100644 index 000000000..2aca6671b --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-maprequestheader-factory.adoc @@ -0,0 +1,24 @@ +[[the-maprequestheader-gatewayfilter-factory]] += The `MapRequestHeader` `GatewayFilter` Factory + +The `MapRequestHeader` `GatewayFilter` factory takes `fromHeader` and `toHeader` parameters. +It creates a new named header (`toHeader`), and the value is extracted out of an existing named header (`fromHeader`) from the incoming http request. +If the input header does not exist, the filter has no impact. +If the new named header already exists, its values are augmented with the new values. +The following example configures a `MapRequestHeader`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: map_request_header_route + uri: https://example.org + filters: + - MapRequestHeader=Blue, X-Request-Red +---- + +This adds the `X-Request-Red:` header to the downstream request with updated values from the incoming HTTP request's `Blue` header. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-modifyrequestbody-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-modifyrequestbody-factory.adoc new file mode 100644 index 000000000..7c47dd8b7 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-modifyrequestbody-factory.adoc @@ -0,0 +1,44 @@ +[[the-modifyrequestbody-gatewayfilter-factory]] += The `ModifyRequestBody` `GatewayFilter` Factory + +You can use the `ModifyRequestBody` filter to modify the request body before it is sent downstream by the gateway. + +NOTE: This filter can be configured only by using the Java DSL. + +The following listing shows how to modify a request body `GatewayFilter`: + +[source,java] +---- +@Bean +public RouteLocator routes(RouteLocatorBuilder builder) { + return builder.routes() + .route("rewrite_request_obj", r -> r.host("*.rewriterequestobj.org") + .filters(f -> f.prefixPath("/httpbin") + .modifyRequestBody(String.class, Hello.class, MediaType.APPLICATION_JSON_VALUE, + (exchange, s) -> Mono.just(new Hello(s.toUpperCase())))).uri(uri)) + .build(); +} + +static class Hello { + String message; + + public Hello() { } + + public Hello(String message) { + this.message = message; + } + + public String getMessage() { + return message; + } + + public void setMessage(String message) { + this.message = message; + } +} +---- + +NOTE: If the request has no body, the `RewriteFilter` is passed `null`. `Mono.empty()` should be returned to assign a missing body in the request. + + + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-modifyresponsebody-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-modifyresponsebody-factory.adoc new file mode 100644 index 000000000..0cdaf9a67 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-modifyresponsebody-factory.adoc @@ -0,0 +1,24 @@ +[[the-modifyresponsebody-gatewayfilter-factory]] += The `ModifyResponseBody` `GatewayFilter` Factory + +You can use the `ModifyResponseBody` filter to modify the response body before it is sent back to the client. + +NOTE: This filter can be configured only by using the Java DSL. + +The following listing shows how to modify a response body `GatewayFilter`: + +[source,java] +---- +@Bean +public RouteLocator routes(RouteLocatorBuilder builder) { + return builder.routes() + .route("rewrite_response_upper", r -> r.host("*.rewriteresponseupper.org") + .filters(f -> f.prefixPath("/httpbin") + .modifyResponseBody(String.class, String.class, + (exchange, s) -> Mono.just(s.toUpperCase()))).uri(uri)) + .build(); +} +---- + +NOTE: If the response has no body, the `RewriteFilter` is passed `null`. `Mono.empty()` should be returned to assign a missing body in the response. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-prefixpath-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-prefixpath-factory.adoc new file mode 100644 index 000000000..9389317fd --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-prefixpath-factory.adoc @@ -0,0 +1,23 @@ +[[the-prefixpath-gatewayfilter-factory]] += The `PrefixPath` `GatewayFilter` Factory +:page-section-summary-toc: 1 + +The `PrefixPath` `GatewayFilter` factory takes a single `prefix` parameter. +The following example configures a `PrefixPath` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: prefixpath_route + uri: https://example.org + filters: + - PrefixPath=/mypath +---- + +This prefixes `/mypath` to the path of all matching requests. +So a request to `/hello` is sent to `/mypath/hello`. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-preservehostheader-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-preservehostheader-factory.adoc new file mode 100644 index 000000000..eaa74dc5c --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-preservehostheader-factory.adoc @@ -0,0 +1,21 @@ +[[the-preservehostheader-gatewayfilter-factory]] += The `PreserveHostHeader` `GatewayFilter` Factory +:page-section-summary-toc: 1 + +The `PreserveHostHeader` `GatewayFilter` factory has no parameters. +This filter sets a request attribute that the routing filter inspects to determine if the original host header should be sent rather than the host header determined by the HTTP client. +The following example configures a `PreserveHostHeader` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: preserve_host_route + uri: https://example.org + filters: + - PreserveHostHeader +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-redirectto-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-redirectto-factory.adoc new file mode 100644 index 000000000..715e68520 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-redirectto-factory.adoc @@ -0,0 +1,26 @@ +[[the-redirectto-gatewayfilter-factory]] += The `RedirectTo` `GatewayFilter` Factory + +The `RedirectTo` `GatewayFilter` factory takes two parameters, `status` and `url`. +The `status` parameter should be a 300 series redirect HTTP code, such as 301. +The `url` parameter should be a valid URL. +This is the value of the `Location` header. +For relative redirects, you should use `uri: no://op` as the uri of your route definition. +The following listing configures a `RedirectTo` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: prefixpath_route + uri: https://example.org + filters: + - RedirectTo=302, https://acme.org +---- + +This will send a status 302 with a `Location:https://acme.org` header to perform a redirect. + + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-removerequestheader-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-removerequestheader-factory.adoc new file mode 100644 index 000000000..3fd9940b6 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-removerequestheader-factory.adoc @@ -0,0 +1,23 @@ +[[the-removerequestheader-gatewayfilter-factory]] += The `RemoveRequestHeader` GatewayFilter Factory +:page-section-summary-toc: 1 + +The `RemoveRequestHeader` `GatewayFilter` factory takes a `name` parameter. +It is the name of the header to be removed. +The following listing configures a `RemoveRequestHeader` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: removerequestheader_route + uri: https://example.org + filters: + - RemoveRequestHeader=X-Request-Foo +---- + +This removes the `X-Request-Foo` header before it is sent downstream. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-removerequestparameter-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-removerequestparameter-factory.adoc new file mode 100644 index 000000000..6d8fd45fc --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-removerequestparameter-factory.adoc @@ -0,0 +1,24 @@ +[[the-removerequestparameter-gatewayfilter-factory]] += The `RemoveRequestParameter` `GatewayFilter` Factory +:page-section-summary-toc: 1 + +The `RemoveRequestParameter` `GatewayFilter` factory takes a `name` parameter. +It is the name of the query parameter to be removed. +The following example configures a `RemoveRequestParameter` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: removerequestparameter_route + uri: https://example.org + filters: + - RemoveRequestParameter=red +---- + +This will remove the `red` parameter before it is sent downstream. + + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-removeresponseheader-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-removeresponseheader-factory.adoc new file mode 100644 index 000000000..5ac1ebf3f --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-removeresponseheader-factory.adoc @@ -0,0 +1,26 @@ +[[the-removeresponseheader-gatewayfilter-factory]] += The `RemoveResponseHeader` `GatewayFilter` Factory + +The `RemoveResponseHeader` `GatewayFilter` factory takes a `name` parameter. +It is the name of the header to be removed. +The following listing configures a `RemoveResponseHeader` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: removeresponseheader_route + uri: https://example.org + filters: + - RemoveResponseHeader=X-Response-Foo +---- + +This will remove the `X-Response-Foo` header from the response before it is returned to the gateway client. + +To remove any kind of sensitive header, you should configure this filter for any routes for which you may want to do so. +In addition, you can configure this filter once by using `spring.cloud.gateway.default-filters` and have it applied to all routes. + + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-requestheadersize-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-requestheadersize-factory.adoc new file mode 100644 index 000000000..d6f0bb165 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-requestheadersize-factory.adoc @@ -0,0 +1,23 @@ +[[the-requestheadersize-gatewayfilter-factory]] += The `RequestHeaderSize` `GatewayFilter` Factory +:page-section-summary-toc: 1 + +The `RequestHeaderSize` `GatewayFilter` factory takes `maxSize` and `errorHeaderName` parameters. +The `maxSize` parameter is the maximum data size allowed by the request header (including key and value). The `errorHeaderName` parameter sets the name of the response header containing an error message, by default it is "errorMessage". +The following listing configures a `RequestHeaderSize` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: requestheadersize_route + uri: https://example.org + filters: + - RequestHeaderSize=1000B +---- + +This will send a status 431 if size of any request header is greater than 1000 Bytes. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-requestratelimiter-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-requestratelimiter-factory.adoc new file mode 100644 index 000000000..e4e7bcb9b --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-requestratelimiter-factory.adoc @@ -0,0 +1,120 @@ +[[the-requestratelimiter-gatewayfilter-factory]] += The `RequestRateLimiter` `GatewayFilter` Factory + +The `RequestRateLimiter` `GatewayFilter` factory uses a `RateLimiter` implementation to determine if the current request is allowed to proceed. If it is not, a status of `HTTP 429 - Too Many Requests` (by default) is returned. + +This filter takes an optional `keyResolver` parameter and parameters specific to the rate limiter (described xref:spring-cloud-gateway/gatewayfilter-factories/the-requestratelimiter-factory.adoc#key-resolver-section[later in this section]). + +`keyResolver` is a bean that implements the `KeyResolver` interface. +In configuration, reference the bean by name using SpEL. +`#{@myKeyResolver}` is a SpEL expression that references a bean named `myKeyResolver`. +The following listing shows the `KeyResolver` interface: + +.KeyResolver.java +[source,java] +---- +public interface KeyResolver { + Mono resolve(ServerWebExchange exchange); +} +---- + +[[key-resolver-section]] +The `KeyResolver` interface lets pluggable strategies derive the key for limiting requests. +In future milestone releases, there will be some `KeyResolver` implementations. + +The default implementation of `KeyResolver` is the `PrincipalNameKeyResolver`, which retrieves the `Principal` from the `ServerWebExchange` and calls `Principal.getName()`. + +By default, if the `KeyResolver` does not find a key, requests are denied. +You can adjust this behavior by setting the `spring.cloud.gateway.filter.request-rate-limiter.deny-empty-key` (`true` or `false`) and `spring.cloud.gateway.filter.request-rate-limiter.empty-key-status-code` properties. + +[NOTE] +===== +The `RequestRateLimiter` is not configurable with the "shortcut" notation. The following example below is _invalid_: + +.application.properties +---- +# INVALID SHORTCUT CONFIGURATION +spring.cloud.gateway.routes[0].filters[0]=RequestRateLimiter=2, 2, #{@userkeyresolver} +---- +===== + +[[the-redis-ratelimiter]] +== The Redis `RateLimiter` + +The Redis implementation is based on work done at https://stripe.com/blog/rate-limiters[Stripe]. +It requires the use of the `spring-boot-starter-data-redis-reactive` Spring Boot starter. + +The algorithm used is the https://en.wikipedia.org/wiki/Token_bucket[Token Bucket Algorithm]. + +The `redis-rate-limiter.replenishRate` property defines how many requests per second to allow (without any dropped requests). +This is the rate at which the token bucket is filled. + +The `redis-rate-limiter.burstCapacity` property is the maximum number of requests a user is allowed in a single second (without any dropped requests). +This is the number of tokens the token bucket can hold. +Setting this value to zero blocks all requests. + +The `redis-rate-limiter.requestedTokens` property is how many tokens a request costs. +This is the number of tokens taken from the bucket for each request and defaults to `1`. + +A steady rate is accomplished by setting the same value in `replenishRate` and `burstCapacity`. +Temporary bursts can be allowed by setting `burstCapacity` higher than `replenishRate`. +In this case, the rate limiter needs to be allowed some time between bursts (according to `replenishRate`), as two consecutive bursts results in dropped requests (`HTTP 429 - Too Many Requests`). +The following listing configures a `redis-rate-limiter`: + +Rate limits below `1 request/s` are accomplished by setting `replenishRate` to the wanted number of requests, `requestedTokens` to the timespan in seconds, and `burstCapacity` to the product of `replenishRate` and `requestedTokens`. +For example, setting `replenishRate=1`, `requestedTokens=60`, and `burstCapacity=60` results in a limit of `1 request/min`. +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: requestratelimiter_route + uri: https://example.org + filters: + - name: RequestRateLimiter + args: + redis-rate-limiter.replenishRate: 10 + redis-rate-limiter.burstCapacity: 20 + redis-rate-limiter.requestedTokens: 1 + +---- + +The following example configures a `KeyResolver` in Java: + +.Config.java +[source,java] +---- +@Bean +KeyResolver userKeyResolver() { + return exchange -> Mono.just(exchange.getRequest().getQueryParams().getFirst("user")); +} +---- + +This defines a request rate limit of 10 per user. A burst of 20 is allowed, but, in the next second, only 10 requests are available. +The `KeyResolver` is a simple one that gets the `user` request parameter +NOTE: This is not recommended for production + +You can also define a rate limiter as a bean that implements the `RateLimiter` interface. +In configuration, you can reference the bean by name using SpEL. +`#{@myRateLimiter}` is a SpEL expression that references a bean with named `myRateLimiter`. +The following listing defines a rate limiter that uses the `KeyResolver` defined in the previous listing: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: requestratelimiter_route + uri: https://example.org + filters: + - name: RequestRateLimiter + args: + rate-limiter: "#{@myRateLimiter}" + key-resolver: "#{@userKeyResolver}" + +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-requestsize-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-requestsize-factory.adoc new file mode 100644 index 000000000..ec770fa44 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-requestsize-factory.adoc @@ -0,0 +1,35 @@ +[[the-requestsize-gatewayfilter-factory]] += The `RequestSize` `GatewayFilter` Factory + +When the request size is greater than the permissible limit, the `RequestSize` `GatewayFilter` factory can restrict a request from reaching the downstream service. +The filter takes a `maxSize` parameter. +The `maxSize` is a `DataSize` type, so values can be defined as a number followed by an optional `DataUnit` suffix such as 'KB' or 'MB'. The default is 'B' for bytes. +It is the permissible size limit of the request defined in bytes. +The following listing configures a `RequestSize` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: request_size_route + uri: http://localhost:8080/upload + predicates: + - Path=/upload + filters: + - name: RequestSize + args: + maxSize: 5000000 +---- + +The `RequestSize` `GatewayFilter` factory sets the response status as `413 Payload Too Large` with an additional header `errorMessage` when the request is rejected due to size. The following example shows such an `errorMessage`: + +[source] +---- +errorMessage : Request size is larger than permissible limit. Request size is 6.0 MB where permissible limit is 5.0 MB +---- + +NOTE: The default request size is set to five MB if not provided as a filter argument in the route definition. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-retry-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-retry-factory.adoc new file mode 100644 index 000000000..5bb176415 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-retry-factory.adoc @@ -0,0 +1,86 @@ +[[the-retry-gatewayfilter-factory]] += The `Retry` `GatewayFilter` Factory + +The `Retry` `GatewayFilter` factory supports the following parameters: + +* `retries`: The number of retries that should be attempted. +* `statuses`: The HTTP status codes that should be retried, represented by using `org.springframework.http.HttpStatus`. +* `methods`: The HTTP methods that should be retried, represented by using `org.springframework.http.HttpMethod`. +* `series`: The series of status codes to be retried, represented by using `org.springframework.http.HttpStatus.Series`. +* `exceptions`: A list of thrown exceptions that should be retried. +* `backoff`: The configured exponential backoff for the retries. +Retries are performed after a backoff interval of `firstBackoff * (factor ^ n)`, where `n` is the iteration. +If `maxBackoff` is configured, the maximum backoff applied is limited to `maxBackoff`. +If `basedOnPreviousValue` is true, the backoff is calculated by using `prevBackoff * factor`. + +The following defaults are configured for `Retry` filter, if enabled: + +* `retries`: Three times +* `series`: 5XX series +* `methods`: GET method +* `exceptions`: `IOException` and `TimeoutException` +* `backoff`: disabled + +The following listing configures a Retry `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: retry_test + uri: http://localhost:8080/flakey + predicates: + - Host=*.retry.com + filters: + - name: Retry + args: + retries: 3 + statuses: BAD_GATEWAY + methods: GET,POST + backoff: + firstBackoff: 10ms + maxBackoff: 50ms + factor: 2 + basedOnPreviousValue: false +---- + +NOTE: When using the retry filter with a `forward:` prefixed URL, the target endpoint should be written carefully so that, in case of an error, it does not do anything that could result in a response being sent to the client and committed. +For example, if the target endpoint is an annotated controller, the target controller method should not return `ResponseEntity` with an error status code. +Instead, it should throw an `Exception` or signal an error (for example, through a `Mono.error(ex)` return value), which the retry filter can be configured to handle by retrying. + +WARNING: When using the retry filter with any HTTP method with a body, the body will be cached and the gateway will become memory constrained. The body is cached in a request attribute defined by `ServerWebExchangeUtils.CACHED_REQUEST_BODY_ATTR`. The type of the object is `org.springframework.core.io.buffer.DataBuffer`. + +A simplified "shortcut" notation can be added with a single `status` and `method`. + +The following two examples are equivalent: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: retry_route + uri: https://example.org + filters: + - name: Retry + args: + retries: 3 + statuses: INTERNAL_SERVER_ERROR + methods: GET + backoff: + firstBackoff: 10ms + maxBackoff: 50ms + factor: 2 + basedOnPreviousValue: false + + - id: retryshortcut_route + uri: https://example.org + filters: + - Retry=3,INTERNAL_SERVER_ERROR,GET,10ms,50ms,2,false +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-rewritelocationresponseheader-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-rewritelocationresponseheader-factory.adoc new file mode 100644 index 000000000..d9cdf8a16 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-rewritelocationresponseheader-factory.adoc @@ -0,0 +1,35 @@ +[[the-rewritelocationresponseheader-gatewayfilter-factory]] += The `RewriteLocationResponseHeader` `GatewayFilter` Factory + +The `RewriteLocationResponseHeader` `GatewayFilter` factory modifies the value of the `Location` response header, usually to get rid of backend-specific details. +It takes the `stripVersionMode`, `locationHeaderName`, `hostValue`, and `protocolsRegex` parameters. +The following listing configures a `RewriteLocationResponseHeader` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: rewritelocationresponseheader_route + uri: http://example.org + filters: + - RewriteLocationResponseHeader=AS_IN_REQUEST, Location, , +---- + +For example, for a request of `POST https://api.example.com/some/object/name`, the `Location` response header value of `https://object-service.prod.example.net/v2/some/object/id` is rewritten as `https://api.example.com/some/object/id`. + +The `stripVersionMode` parameter has the following possible values: `NEVER_STRIP`, `AS_IN_REQUEST` (default), and `ALWAYS_STRIP`. + +* `NEVER_STRIP`: The version is not stripped, even if the original request path contains no version. +* `AS_IN_REQUEST`: The version is stripped only if the original request path contains no version. +* `ALWAYS_STRIP`: The version is always stripped, even if the original request path contains version. + +The `hostValue` parameter, if provided, is used to replace the `host:port` portion of the response `Location` header. +If it is not provided, the value of the `Host` request header is used. + +The `protocolsRegex` parameter must be a valid regex `String`, against which the protocol name is matched. +If it is not matched, the filter does nothing. +The default is `http|https|ftp|ftps`. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-rewritepath-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-rewritepath-factory.adoc new file mode 100644 index 000000000..3c17efd64 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-rewritepath-factory.adoc @@ -0,0 +1,24 @@ +[[the-rewritepath-gatewayfilter-factory]] += The `RewritePath` `GatewayFilter` Factory + +The `RewritePath` `GatewayFilter` factory takes a path `regexp` parameter and a `replacement` parameter. +This uses Java regular expressions for a flexible way to rewrite the request path. +The following listing configures a `RewritePath` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: rewritepath_route + uri: https://example.org + predicates: + - Path=/red/** + filters: + - RewritePath=/red/?(?.*), /$\{segment} +---- + +For a request path of `/red/blue`, this sets the path to `/blue` before making the downstream request. Note that the `$` should be replaced with `$\` because of the YAML specification. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-rewriteresponseheader-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-rewriteresponseheader-factory.adoc new file mode 100644 index 000000000..26f0dec9b --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-rewriteresponseheader-factory.adoc @@ -0,0 +1,24 @@ +[[the-rewriteresponseheader-gatewayfilter-factory]] += The `RewriteResponseHeader` `GatewayFilter` Factory +:page-section-summary-toc: 1 + +The `RewriteResponseHeader` `GatewayFilter` factory takes `name`, `regexp`, and `replacement` parameters. +It uses Java regular expressions for a flexible way to rewrite the response header value. +The following example configures a `RewriteResponseHeader` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: rewriteresponseheader_route + uri: https://example.org + filters: + - RewriteResponseHeader=X-Response-Red, , password=[^&]+, password=*** +---- + +For a header value of `/42?user=ford&password=omg!what&flag=true`, it is set to `/42?user=ford&password=\***&flag=true` after making the downstream request. +You must use `$\` to mean `$` because of the YAML specification. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-savesession-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-savesession-factory.adoc new file mode 100644 index 000000000..ed275a4d9 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-savesession-factory.adoc @@ -0,0 +1,24 @@ +[[the-savesession-gatewayfilter-factory]] += The `SaveSession` `GatewayFilter` Factory + +The `SaveSession` `GatewayFilter` factory forces a `WebSession::save` operation _before_ forwarding the call downstream. +This is of particular use when using something like https://projects.spring.io/spring-session/[Spring Session] with a lazy data store, and you need to ensure the session state has been saved before making the forwarded call. +The following example configures a `SaveSession` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: save_session + uri: https://example.org + predicates: + - Path=/foo/** + filters: + - SaveSession +---- + +If you integrate https://projects.spring.io/spring-security/[Spring Security] with Spring Session and want to ensure security details have been forwarded to the remote process, this is critical. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-secureheaders-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-secureheaders-factory.adoc new file mode 100644 index 000000000..5b653f607 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-secureheaders-factory.adoc @@ -0,0 +1,38 @@ +[[the-secureheaders-gatewayfilter-factory]] += The `SecureHeaders` `GatewayFilter` Factory + +The `SecureHeaders` `GatewayFilter` factory adds a number of headers to the response, per the recommendation made in https://blog.appcanary.com/2017/http-security-headers.html[this blog post]. + +The following headers (shown with their default values) are added: + +* `X-Xss-Protection:1 (mode=block`) +* `Strict-Transport-Security (max-age=631138519`) +* `X-Frame-Options (DENY)` +* `X-Content-Type-Options (nosniff)` +* `Referrer-Policy (no-referrer)` +* `Content-Security-Policy (default-src 'self' https:; font-src 'self' https: data:; img-src 'self' https: data:; object-src 'none'; script-src https:; style-src 'self' https: 'unsafe-inline)'` +* `X-Download-Options (noopen)` +* `X-Permitted-Cross-Domain-Policies (none)` + +To change the default values, set the appropriate property in the `spring.cloud.gateway.filter.secure-headers` namespace. +The following properties are available: + +* `xss-protection-header` +* `strict-transport-security` +* `frame-options` +* `content-type-options` +* `referrer-policy` +* `content-security-policy` +* `download-options` +* `permitted-cross-domain-policies` + +To disable the default values set the `spring.cloud.gateway.filter.secure-headers.disable` property with comma-separated values. +The following example shows how to do so: + +[source] +---- +spring.cloud.gateway.filter.secure-headers.disable=x-frame-options,strict-transport-security +---- + +NOTE: The lowercase full name of the secure header needs to be used to disable it.. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setpath-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setpath-factory.adoc new file mode 100644 index 000000000..882e7865e --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setpath-factory.adoc @@ -0,0 +1,26 @@ +[[the-setpath-gatewayfilter-factory]] += The `SetPath` `GatewayFilter` Factory + +The `SetPath` `GatewayFilter` factory takes a path `template` parameter. +It offers a simple way to manipulate the request path by allowing templated segments of the path. +This uses the URI templates from Spring Framework. +Multiple matching segments are allowed. +The following example configures a `SetPath` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: setpath_route + uri: https://example.org + predicates: + - Path=/red/{segment} + filters: + - SetPath=/{segment} +---- + +For a request path of `/red/blue`, this sets the path to `/blue` before making the downstream request. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setrequestheader-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setrequestheader-factory.adoc new file mode 100644 index 000000000..00f7a8f62 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setrequestheader-factory.adoc @@ -0,0 +1,41 @@ +[[the-setrequestheader-gatewayfilter-factory]] += The `SetRequestHeader` `GatewayFilter` Factory + +The `SetRequestHeader` `GatewayFilter` factory takes `name` and `value` parameters. +The following listing configures a `SetRequestHeader` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: setrequestheader_route + uri: https://example.org + filters: + - SetRequestHeader=X-Request-Red, Blue +---- + +This `GatewayFilter` replaces (rather than adding) all headers with the given name. +So, if the downstream server responded with `X-Request-Red:1234`, it will be replaced with `X-Request-Red:Blue`, which is what the downstream service would receive. + +`SetRequestHeader` is aware of URI variables used to match a path or host. +URI variables may be used in the value and are expanded at runtime. +The following example configures an `SetRequestHeader` `GatewayFilter` that uses a variable: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: setrequestheader_route + uri: https://example.org + predicates: + - Host: {segment}.myhost.org + filters: + - SetRequestHeader=foo, bar-{segment} +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setrequesthostheader-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setrequesthostheader-factory.adoc new file mode 100644 index 000000000..26d500a76 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setrequesthostheader-factory.adoc @@ -0,0 +1,27 @@ +[[the-setrequesthostheader-gatewayfilter-factory]] += The `SetRequestHostHeader` `GatewayFilter` Factory + +There are certain situation when the host header may need to be overridden. In this situation, the `SetRequestHostHeader` `GatewayFilter` factory can replace the existing host header with a specified value. +The filter takes a `host` parameter. +The following listing configures a `SetRequestHostHeader` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: set_request_host_header_route + uri: http://localhost:8080/headers + predicates: + - Path=/headers + filters: + - name: SetRequestHostHeader + args: + host: example.org +---- + +The `SetRequestHostHeader` `GatewayFilter` factory replaces the value of the host header with `example.org`. + + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setresponseheader-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setresponseheader-factory.adoc new file mode 100644 index 000000000..da671fa03 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setresponseheader-factory.adoc @@ -0,0 +1,41 @@ +[[the-setresponseheader-gatewayfilter-factory]] += The `SetResponseHeader` `GatewayFilter` Factory + +The `SetResponseHeader` `GatewayFilter` factory takes `name` and `value` parameters. +The following listing configures a `SetResponseHeader` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: setresponseheader_route + uri: https://example.org + filters: + - SetResponseHeader=X-Response-Red, Blue +---- + +This GatewayFilter replaces (rather than adding) all headers with the given name. +So, if the downstream server responded with `X-Response-Red:1234`, it will be replaced with `X-Response-Red:Blue`, which is what the gateway client would receive. + +`SetResponseHeader` is aware of URI variables used to match a path or host. +URI variables may be used in the value and will be expanded at runtime. +The following example configures an `SetResponseHeader` `GatewayFilter` that uses a variable: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: setresponseheader_route + uri: https://example.org + predicates: + - Host: {segment}.myhost.org + filters: + - SetResponseHeader=foo, bar-{segment} +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setstatus-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setstatus-factory.adoc new file mode 100644 index 000000000..b437a3a2e --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-setstatus-factory.adoc @@ -0,0 +1,40 @@ +[[the-setstatus-gatewayfilter-factory]] += The `SetStatus` `GatewayFilter` Factory + +The `SetStatus` `GatewayFilter` factory takes a single parameter, `status`. +It must be a valid Spring `HttpStatus`. +It may be the integer value `404` or the string representation of the enumeration: `NOT_FOUND`. +The following listing configures a `SetStatus` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: setstatusstring_route + uri: https://example.org + filters: + - SetStatus=UNAUTHORIZED + - id: setstatusint_route + uri: https://example.org + filters: + - SetStatus=401 +---- + +In either case, the HTTP status of the response is set to 401. + +You can configure the `SetStatus` `GatewayFilter` to return the original HTTP status code from the proxied request in a header in the response. +The header is added to the response if configured with the following property: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + set-status: + original-status-header-name: original-http-status +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-stripprefix-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-stripprefix-factory.adoc new file mode 100644 index 000000000..d154f503d --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-stripprefix-factory.adoc @@ -0,0 +1,24 @@ +[[the-stripprefix-gatewayfilter-factory]] += The `StripPrefix` `GatewayFilter` Factory + +The `StripPrefix` `GatewayFilter` factory takes one parameter, `parts`. +The `parts` parameter indicates the number of parts in the path to strip from the request before sending it downstream. +The following listing configures a `StripPrefix` `GatewayFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: nameRoot + uri: https://nameservice + predicates: + - Path=/name/** + filters: + - StripPrefix=2 +---- + +When a request is made through the gateway to `/name/blue/red`, the request made to `nameservice` looks like `https://nameservice/red`. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-tokenrelay-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-tokenrelay-factory.adoc new file mode 100644 index 000000000..e395c3df3 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/gatewayfilter-factories/the-tokenrelay-factory.adoc @@ -0,0 +1,103 @@ +[[the-tokenrelay-gatewayfilter-factory]] += The `TokenRelay` `GatewayFilter` Factory + +A Token Relay is where an OAuth2 consumer acts as a Client and +forwards the incoming token to outgoing resource requests. The +consumer can be a pure Client (like an SSO application) or a Resource +Server. + +Spring Cloud Gateway can forward OAuth2 access tokens downstream to the services +it is proxying using the `TokenRelay` `GatewayFilter`. + +The `TokenRelay` `GatewayFilter` takes one optional parameter, `clientRegistrationId`. +The following example configures a `TokenRelay` `GatewayFilter`: + +.App.java +[source,java] +---- + +@Bean +public RouteLocator customRouteLocator(RouteLocatorBuilder builder) { + return builder.routes() + .route("resource", r -> r.path("/resource") + .filters(f -> f.tokenRelay("myregistrationid")) + .uri("http://localhost:9000")) + .build(); +} +---- + +or this + +.application.yaml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: resource + uri: http://localhost:9000 + predicates: + - Path=/resource + filters: + - TokenRelay=myregistrationid +---- + +The example above specifies a `clientRegistrationId`, which can be used to obtain and forward an OAuth2 access token for any available `ClientRegistration`. + +Spring Cloud Gateway can also forward the OAuth2 access token of the currently authenticated user `oauth2Login()` is used to authenticate the user. +To add this functionality to the gateway, you can omit the `clientRegistrationId` parameter like this: + +.App.java +[source,java] +---- + +@Bean +public RouteLocator customRouteLocator(RouteLocatorBuilder builder) { + return builder.routes() + .route("resource", r -> r.path("/resource") + .filters(f -> f.tokenRelay()) + .uri("http://localhost:9000")) + .build(); +} +---- + +or this + +.application.yaml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: resource + uri: http://localhost:9000 + predicates: + - Path=/resource + filters: + - TokenRelay= +---- + +and it will (in addition to logging the user in and grabbing a token) +pass the authentication token downstream to the services (in this case +`/resource`). + +To enable this for Spring Cloud Gateway add the following dependencies + +- `org.springframework.boot:spring-boot-starter-oauth2-client` + +How does it work? The {github-code}/src/main/java/org/springframework/cloud/gateway/security/TokenRelayGatewayFilterFactory.java[filter] +extracts an OAuth2 access token from the currently authenticated user for the provided `clientRegistrationId`. +If no `clientRegistrationId` is provided, the currently authenticated user's own access token (obtained during login) is used. +In either case, the extracted access token is placed in a request header for the downstream requests. + +For a full working sample see https://github.com/spring-cloud-samples/sample-gateway-oauth2login[this project]. + +NOTE: A `TokenRelayGatewayFilterFactory` bean will only be created if the proper `spring.security.oauth2.client.*` properties are set which will trigger creation of a `ReactiveClientRegistrationRepository` bean. + +NOTE: The default implementation of `ReactiveOAuth2AuthorizedClientService` used by `TokenRelayGatewayFilterFactory` +uses an in-memory data store. You will need to provide your own implementation `ReactiveOAuth2AuthorizedClientService` +if you need a more robust solution. + + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/global-filters.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/global-filters.adoc new file mode 100644 index 000000000..2dc8af910 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/global-filters.adoc @@ -0,0 +1,200 @@ +[[global-filters]] += Global Filters + +The `GlobalFilter` interface has the same signature as `GatewayFilter`. +These are special filters that are conditionally applied to all routes. + +NOTE: This interface and its usage are subject to change in future milestone releases. + +[[gateway-combined-global-filter-and-gatewayfilter-ordering]] +== Combined Global Filter and `GatewayFilter` Ordering + +When a request matches a route, the filtering web handler adds all instances of `GlobalFilter` and all route-specific instances of `GatewayFilter` to a filter chain. +This combined filter chain is sorted by the `org.springframework.core.Ordered` interface, which you can set by implementing the `getOrder()` method. + +As Spring Cloud Gateway distinguishes between "`pre`" and "`post`" phases for filter logic execution (see xref:spring-cloud-gateway/how-it-works.adoc[How it Works]), the filter with the highest precedence is the first in the "`pre`"-phase and the last in the "`post`"-phase. + +The following listing configures a filter chain: + +.ExampleConfiguration.java +[source,java] +---- +@Bean +public GlobalFilter customFilter() { + return new CustomGlobalFilter(); +} + +public class CustomGlobalFilter implements GlobalFilter, Ordered { + + @Override + public Mono filter(ServerWebExchange exchange, GatewayFilterChain chain) { + log.info("custom global filter"); + return chain.filter(exchange); + } + + @Override + public int getOrder() { + return -1; + } +} +---- + +[[the-gateway-metrics-filter]] +== The Gateway Metrics Filter + +To enable gateway metrics, add `spring-boot-starter-actuator` as a project dependency. Then, by default, the gateway metrics filter runs as long as the `spring.cloud.gateway.metrics.enabled` property is not set to `false`. +This filter adds a timer metric named `spring.cloud.gateway.requests` with the following tags: + +* `routeId`: The route ID. +* `routeUri`: The URI to which the API is routed. +* `outcome`: The outcome, as classified by link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/HttpStatus.Series.html[HttpStatus.Series]. +* `status`: The HTTP status of the request returned to the client. +* `httpStatusCode`: The HTTP Status of the request returned to the client. +* `httpMethod`: The HTTP method used for the request. + +In addition, through the `spring.cloud.gateway.metrics.tags.path.enabled` property (by default, `false`), you can activate an extra metric with the path tag: + +* `path`: The path of the request. + +These metrics are then available to be scraped from `/actuator/metrics/spring.cloud.gateway.requests` and can be easily integrated with Prometheus to create a link:images/gateway-grafana-dashboard.jpeg[Grafana] link:gateway-grafana-dashboard.json[dashboard]. + +NOTE: To enable the prometheus endpoint, add `micrometer-registry-prometheus` as a project dependency. + +[[local-cache-response-global-filter]] +== The Local Response Cache Filter + +The `LocalResponseCache` runs if associated properties are enabled: + +* `spring.cloud.gateway.global-filter.local-response-cache.enabled`: Activates the global cache for all routes +* `spring.cloud.gateway.filter.local-response-cache.enabled`: Activates the associated filter to use at route level + +This feature enables a local cache using Caffeine for all responses that meet the following criteria: + +* The request is a bodiless GET. +* The response has one of the following status codes: HTTP 200 (OK), HTTP 206 (Partial Content), or HTTP 301 (Moved Permanently). +* The HTTP `Cache-Control` header allows caching (that means it does not have any of the following values: `no-store` present in the request and `no-store` or `private` present in the response). + +It accepts two configuration parameters: + +* `spring.cloud.gateway.filter.local-response-cache.size`: Sets the maximum size of the cache to evict entries for this route (in KB, MB and GB). +* `spring.cloud.gateway.filter.local-response-cache.time-to-live` Sets the time to expire a cache entry (expressed in s for seconds, m for minutes, and h for hours). + +If none of these parameters are configured but the global filter is enabled, by default, it configures 5 minutes of time to live for the cached response. + +This filter also implements the automatic calculation of the `max-age` value in the HTTP `Cache-Control` header. +If `max-age` is present on the original response, the value is rewritten with the number of seconds set in the `timeToLive` configuration parameter. +In subsequent calls, this value is recalculated with the number of seconds left until the response expires. + +Setting `spring.cloud.gateway.global-filter.local-response-cache.enabled` to `false` deactivate the local response cache for all routes, the xref:spring-cloud-gateway/gatewayfilter-factories/local-cache-response-filter.adoc[LocalResponseCache filter] allows to use this functionality at route level. + +NOTE: To enable this feature, add `com.github.ben-manes.caffeine:caffeine` and `spring-boot-starter-cache` as project dependencies. + +WARNING: If your project creates custom `CacheManager` beans, it will either need to be marked with `@Primary` or injected using `@Qualifier`. + +[[forward-routing-filter]] +== Forward Routing Filter + +The `ForwardRoutingFilter` looks for a URI in the exchange attribute `ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR`. +If the URL has a `forward` scheme (such as `forward:///localendpoint`), it uses the Spring `DispatcherHandler` to handle the request. +The path part of the request URL is overridden with the path in the forward URL. +The unmodified original URL is appended to the list in the `ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR` attribute. + +[[the-netty-routing-filter]] +== The Netty Routing Filter + +The Netty routing filter runs if the URL located in the `ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR` exchange attribute has a `http` or `https` scheme. +It uses the Netty `HttpClient` to make the downstream proxy request. +The response is put in the `ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR` exchange attribute for use in a later filter. +(There is also an experimental `WebClientHttpRoutingFilter` that performs the same function but does not require Netty.) + +[[the-netty-write-response-filter]] +== The Netty Write Response Filter + +The `NettyWriteResponseFilter` runs if there is a Netty `HttpClientResponse` in the `ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR` exchange attribute. +It runs after all other filters have completed and writes the proxy response back to the gateway client response. +(There is also an experimental `WebClientWriteResponseFilter` that performs the same function but does not require Netty.) + +[[reactive-loadbalancer-client-filter]] +== The `ReactiveLoadBalancerClientFilter` + +The `ReactiveLoadBalancerClientFilter` looks for a URI in the exchange attribute named `ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR`. +If the URL has a `lb` scheme (such as `lb://myservice`), it uses the Spring Cloud `ReactorLoadBalancer` to resolve the name (`myservice` in this example) to an actual host and port and replaces the URI in the same attribute. +The unmodified original URL is appended to the list in the `ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR` attribute. +The filter also looks in the `ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR` attribute to see if it equals `lb`. +If so, the same rules apply. +The following listing configures a `ReactiveLoadBalancerClientFilter`: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: myRoute + uri: lb://service + predicates: + - Path=/service/** +---- + +NOTE: By default, when a service instance cannot be found by the `ReactorLoadBalancer`, a `503` is returned. +You can configure the gateway to return a `404` by setting `spring.cloud.gateway.loadbalancer.use404=true`. + +NOTE: The `isSecure` value of the `ServiceInstance` returned from the `ReactiveLoadBalancerClientFilter` overrides +the scheme specified in the request made to the Gateway. +For example, if the request comes into the Gateway over `HTTPS` but the `ServiceInstance` indicates it is not secure, the downstream request is made over `HTTP`. +The opposite situation can also apply. +However, if `GATEWAY_SCHEME_PREFIX_ATTR` is specified for the route in the Gateway configuration, the prefix is stripped and the resulting scheme from the route URL overrides the `ServiceInstance` configuration. + +TIP: Gateway supports all the LoadBalancer features. You can read more about them in the https://docs.spring.io/spring-cloud-commons/docs/current/reference/html/#spring-cloud-loadbalancer[Spring Cloud Commons documentation]. + +[[the-routetorequesturl-filter]] +== The `RouteToRequestUrl` Filter + +If there is a `Route` object in the `ServerWebExchangeUtils.GATEWAY_ROUTE_ATTR` exchange attribute, the `RouteToRequestUrlFilter` runs. +It creates a new URI, based off of the request URI but updated with the URI attribute of the `Route` object. +The new URI is placed in the `ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR` exchange attribute. + +If the URI has a scheme prefix, such as `lb:ws://serviceid`, the `lb` scheme is stripped from the URI and placed in the `ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR` for use later in the filter chain. + +[[the-websocket-routing-filter]] +== The Websocket Routing Filter + +If the URL located in the `ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR` exchange attribute has a `ws` or `wss` scheme, the websocket routing filter runs. It uses the Spring WebSocket infrastructure to forward the websocket request downstream. + +You can load-balance websockets by prefixing the URI with `lb`, such as `lb:ws://serviceid`. + +NOTE: If you use https://github.com/sockjs[SockJS] as a fallback over normal HTTP, you should configure a normal HTTP route as well as the websocket Route. + +The following listing configures a websocket routing filter: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + # SockJS route + - id: websocket_sockjs_route + uri: http://localhost:3001 + predicates: + - Path=/websocket/info/** + # Normal Websocket route + - id: websocket_route + uri: ws://localhost:3001 + predicates: + - Path=/websocket/** +---- + +[[marking-an-exchange-as-routed]] +== Marking An Exchange As Routed + +After the gateway has routed a `ServerWebExchange`, it marks that exchange as "`routed`" by adding `gatewayAlreadyRouted` +to the exchange attributes. Once a request has been marked as routed, other routing filters will not route the request again, +essentially skipping the filter. There are convenience methods that you can use to mark an exchange as routed +or check if an exchange has already been routed. + +* `ServerWebExchangeUtils.isAlreadyRouted` takes a `ServerWebExchange` object and checks if it has been "`routed`". +* `ServerWebExchangeUtils.setAlreadyRouted` takes a `ServerWebExchange` object and marks it as "`routed`". + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/glossary.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/glossary.adoc new file mode 100644 index 000000000..95cfd17ff --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/glossary.adoc @@ -0,0 +1,11 @@ +[[glossary]] += Glossary +:page-section-summary-toc: 1 + +* *Route*: The basic building block of the gateway. +It is defined by an ID, a destination URI, a collection of predicates, and a collection of filters. A route is matched if the aggregate predicate is true. +* *Predicate*: This is a https://docs.oracle.com/javase/8/docs/api/java/util/function/Predicate.html[Java 8 Function Predicate]. The input type is a https://docs.spring.io/spring/docs/5.0.x/javadoc-api/org/springframework/web/server/ServerWebExchange.html[Spring Framework `ServerWebExchange`]. +This lets you match on anything from the HTTP request, such as headers or parameters. +* *Filter*: These are instances of {github-code}/spring-cloud-gateway-server/src/main/java/org/springframework/cloud/gateway/filter/GatewayFilter.java[`GatewayFilter`] that have been constructed with a specific factory. +Here, you can modify requests and responses before or after sending the downstream request. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/how-it-works.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/how-it-works.adoc new file mode 100644 index 000000000..da60d42e4 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/how-it-works.adoc @@ -0,0 +1,15 @@ +[[gateway-how-it-works]] += How It Works +:page-section-summary-toc: 1 + +The following diagram provides a high-level overview of how Spring Cloud Gateway works: + +image::spring_cloud_gateway_diagram.png[Spring Cloud Gateway Diagram] + +Clients make requests to Spring Cloud Gateway. If the Gateway Handler Mapping determines that a request matches a route, it is sent to the Gateway Web Handler. +This handler runs the request through a filter chain that is specific to the request. +The reason the filters are divided by the dotted line is that filters can run logic both before and after the proxy request is sent. +All "`pre`" filter logic is executed. Then the proxy request is made. After the proxy request is made, the "`post`" filter logic is run. + +NOTE: URIs defined in routes without a port get default port values of 80 and 443 for the HTTP and HTTPS URIs, respectively. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/http-timeouts-configuration.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/http-timeouts-configuration.adoc new file mode 100644 index 000000000..4d1805a18 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/http-timeouts-configuration.adoc @@ -0,0 +1,75 @@ +[[http-timeouts-configuration]] += Http timeouts configuration + +Http timeouts (response and connect) can be configured for all routes and overridden for each specific route. + +[[global-timeouts]] +== Global timeouts +To configure Global http timeouts: + +`connect-timeout` must be specified in milliseconds. + +`response-timeout` must be specified as a java.time.Duration + +.global http timeouts example +[source,yaml] +---- +spring: + cloud: + gateway: + httpclient: + connect-timeout: 1000 + response-timeout: 5s +---- + +[[per-route-timeouts]] +== Per-route timeouts +To configure per-route timeouts: + +`connect-timeout` must be specified in milliseconds. + +`response-timeout` must be specified in milliseconds. + +.per-route http timeouts configuration via configuration +[source,yaml] +---- + - id: per_route_timeouts + uri: https://example.org + predicates: + - name: Path + args: + pattern: /delay/{timeout} + metadata: + response-timeout: 200 + connect-timeout: 200 +---- + +.per-route timeouts configuration using Java DSL +[source,java] +---- +import static org.springframework.cloud.gateway.support.RouteMetadataUtils.CONNECT_TIMEOUT_ATTR; +import static org.springframework.cloud.gateway.support.RouteMetadataUtils.RESPONSE_TIMEOUT_ATTR; + + @Bean + public RouteLocator customRouteLocator(RouteLocatorBuilder routeBuilder){ + return routeBuilder.routes() + .route("test1", r -> { + return r.host("*.somehost.org").and().path("/somepath") + .filters(f -> f.addRequestHeader("header1", "header-value-1")) + .uri("http://someuri") + .metadata(RESPONSE_TIMEOUT_ATTR, 200) + .metadata(CONNECT_TIMEOUT_ATTR, 200); + }) + .build(); + } +---- + +A per-route `response-timeout` with a negative value will disable the global `response-timeout` value. + +---- + - id: per_route_timeouts + uri: https://example.org + predicates: + - name: Path + args: + pattern: /delay/{timeout} + metadata: + response-timeout: -1 +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/httpheadersfilters.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/httpheadersfilters.adoc new file mode 100644 index 000000000..e2a6ac82e --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/httpheadersfilters.adoc @@ -0,0 +1,45 @@ +[[httpheadersfilters]] += HttpHeadersFilters + +`HttpHeadersFilters` are applied to the requests before sending them downstream, such as in the `NettyRoutingFilter`. + +[[forwarded-headers-filter]] +== Forwarded Headers Filter +The `Forwarded` Headers Filter creates a `Forwarded` header to send to the downstream service. It adds the `Host` header, scheme and port of the current request to any existing `Forwarded` header. + +[[removehopbyhop-headers-filter]] +== RemoveHopByHop Headers Filter +The `RemoveHopByHop` Headers Filter removes headers from forwarded requests. The default list of headers that is removed comes from the https://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-14#section-7.1.3[IETF]. + +.The default removed headers are: +* Connection +* Keep-Alive +* Proxy-Authenticate +* Proxy-Authorization +* TE +* Trailer +* Transfer-Encoding +* Upgrade + +To change this, set the `spring.cloud.gateway.filter.remove-hop-by-hop.headers` property to the list of header names to remove. + +[[xforwarded-headers-filter]] +== XForwarded Headers Filter +The `XForwarded` Headers Filter creates various `X-Forwarded-*` headers to send to the downstream service. It uses the `Host` header, scheme, port and path of the current request to create the various headers. + +Creating of individual headers can be controlled by the following boolean properties (defaults to true): + +- `spring.cloud.gateway.x-forwarded.for-enabled` +- `spring.cloud.gateway.x-forwarded.host-enabled` +- `spring.cloud.gateway.x-forwarded.port-enabled` +- `spring.cloud.gateway.x-forwarded.proto-enabled` +- `spring.cloud.gateway.x-forwarded.prefix-enabled` + +Appending multiple headers can be controlled by the following boolean properties (defaults to true): + +- `spring.cloud.gateway.x-forwarded.for-append` +- `spring.cloud.gateway.x-forwarded.host-append` +- `spring.cloud.gateway.x-forwarded.port-append` +- `spring.cloud.gateway.x-forwarded.proto-append` +- `spring.cloud.gateway.x-forwarded.prefix-append` + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/reactor-netty-access-logs.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/reactor-netty-access-logs.adoc new file mode 100644 index 000000000..1b830cff3 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/reactor-netty-access-logs.adoc @@ -0,0 +1,27 @@ +[[reactor-netty-access-logs]] += Reactor Netty Access Logs + +To enable Reactor Netty access logs, set `-Dreactor.netty.http.server.accessLogEnabled=true`. + +IMPORTANT: It must be a Java System Property, not a Spring Boot property. + +You can configure the logging system to have a separate access log file. The following example creates a Logback configuration: + +.logback.xml +[source,xml] +---- + + access_log.log + + %msg%n + + + + + + + + + +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/request-predicates-factories.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/request-predicates-factories.adoc new file mode 100644 index 000000000..d8116c12e --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/request-predicates-factories.adoc @@ -0,0 +1,376 @@ +[[gateway-request-predicates-factories]] += Route Predicate Factories + +Spring Cloud Gateway matches routes as part of the Spring WebFlux `HandlerMapping` infrastructure. +Spring Cloud Gateway includes many built-in route predicate factories. +All of these predicates match on different attributes of the HTTP request. +You can combine multiple route predicate factories with logical `and` statements. + +[[the-after-route-predicate-factory]] +== The After Route Predicate Factory + +The `After` route predicate factory takes one parameter, a `datetime` (which is a java `ZonedDateTime`). +This predicate matches requests that happen after the specified datetime. +The following example configures an after route predicate: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: after_route + uri: https://example.org + predicates: + - After=2017-01-20T17:42:47.789-07:00[America/Denver] +---- + +This route matches any request made after Jan 20, 2017 17:42 Mountain Time (Denver). + +[[the-before-route-predicate-factory]] +== The Before Route Predicate Factory + +The `Before` route predicate factory takes one parameter, a `datetime` (which is a java `ZonedDateTime`). +This predicate matches requests that happen before the specified `datetime`. +The following example configures a before route predicate: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: before_route + uri: https://example.org + predicates: + - Before=2017-01-20T17:42:47.789-07:00[America/Denver] +---- + +This route matches any request made before Jan 20, 2017 17:42 Mountain Time (Denver). + +[[the-between-route-predicate-factory]] +== The Between Route Predicate Factory + +The `Between` route predicate factory takes two parameters, `datetime1` and `datetime2` +which are java `ZonedDateTime` objects. +This predicate matches requests that happen after `datetime1` and before `datetime2`. +The `datetime2` parameter must be after `datetime1`. +The following example configures a between route predicate: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: between_route + uri: https://example.org + predicates: + - Between=2017-01-20T17:42:47.789-07:00[America/Denver], 2017-01-21T17:42:47.789-07:00[America/Denver] +---- + +This route matches any request made after Jan 20, 2017 17:42 Mountain Time (Denver) and before Jan 21, 2017 17:42 Mountain Time (Denver). +This could be useful for maintenance windows. + +[[the-cookie-route-predicate-factory]] +== The Cookie Route Predicate Factory + +The `Cookie` route predicate factory takes two parameters, the cookie `name` and a `regexp` (which is a Java regular expression). +This predicate matches cookies that have the given name and whose values match the regular expression. +The following example configures a cookie route predicate factory: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: cookie_route + uri: https://example.org + predicates: + - Cookie=chocolate, ch.p +---- + +This route matches requests that have a cookie named `chocolate` whose value matches the `ch.p` regular expression. + +[[the-header-route-predicate-factory]] +== The Header Route Predicate Factory + +The `Header` route predicate factory takes two parameters, the `header` and a `regexp` (which is a Java regular expression). +This predicate matches with a header that has the given name whose value matches the regular expression. +The following example configures a header route predicate: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: header_route + uri: https://example.org + predicates: + - Header=X-Request-Id, \d+ +---- + +This route matches if the request has a header named `X-Request-Id` whose value matches the `\d+` regular expression (that is, it has a value of one or more digits). + +[[the-host-route-predicate-factory]] +== The Host Route Predicate Factory + +The `Host` route predicate factory takes one parameter: a list of host name `patterns`. +The pattern is an Ant-style pattern with `.` as the separator. +This predicates matches the `Host` header that matches the pattern. +The following example configures a host route predicate: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: host_route + uri: https://example.org + predicates: + - Host=**.somehost.org,**.anotherhost.org +---- + +URI template variables (such as `\{sub}.myhost.org`) are supported as well. + +This route matches if the request has a `Host` header with a value of `www.somehost.org` or `beta.somehost.org` or `www.anotherhost.org`. + +This predicate extracts the URI template variables (such as `sub`, defined in the preceding example) as a map of names and values and places it in the `ServerWebExchange.getAttributes()` with a key defined in `ServerWebExchangeUtils.URI_TEMPLATE_VARIABLES_ATTRIBUTE`. +Those values are then available for use by <> + + +[[the-method-route-predicate-factory]] +== The Method Route Predicate Factory + +The `Method` Route Predicate Factory takes a `methods` argument which is one or more parameters: the HTTP methods to match. +The following example configures a method route predicate: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: method_route + uri: https://example.org + predicates: + - Method=GET,POST +---- + +This route matches if the request method was a `GET` or a `POST`. + +[[the-path-route-predicate-factory]] +== The Path Route Predicate Factory + +The `Path` Route Predicate Factory takes two parameters: a list of Spring `PathMatcher` `patterns` and an optional flag called `matchTrailingSlash` (defaults to `true`). +The following example configures a path route predicate: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: path_route + uri: https://example.org + predicates: + - Path=/red/{segment},/blue/{segment} +---- + +This route matches if the request path was, for example: `/red/1` or `/red/1/` or `/red/blue` or `/blue/green`. + +If `matchTrailingSlash` is set to `false`, then request path `/red/1/` will not be matched. + +This predicate extracts the URI template variables (such as `segment`, defined in the preceding example) as a map of names and values and places it in the `ServerWebExchange.getAttributes()` with a key defined in `ServerWebExchangeUtils.URI_TEMPLATE_VARIABLES_ATTRIBUTE`. +Those values are then available for use by <> + +A utility method (called `get`) is available to make access to these variables easier. +The following example shows how to use the `get` method: + +[source,java] +---- +Map uriVariables = ServerWebExchangeUtils.getUriTemplateVariables(exchange); + +String segment = uriVariables.get("segment"); +---- + +[[the-query-route-predicate-factory]] +== The Query Route Predicate Factory + +The `Query` route predicate factory takes two parameters: a required `param` and an optional `regexp` (which is a Java regular expression). +The following example configures a query route predicate: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: query_route + uri: https://example.org + predicates: + - Query=green +---- + +The preceding route matches if the request contained a `green` query parameter. + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: query_route + uri: https://example.org + predicates: + - Query=red, gree. +---- + +The preceding route matches if the request contained a `red` query parameter whose value matched the `gree.` regexp, so `green` and `greet` would match. + + +[[the-remoteaddr-route-predicate-factory]] +== The RemoteAddr Route Predicate Factory + +The `RemoteAddr` route predicate factory takes a list (min size 1) of `sources`, which are CIDR-notation (IPv4 or IPv6) strings, such as `192.168.0.1/16` (where `192.168.0.1` is an IP address and `16` is a subnet mask). +The following example configures a RemoteAddr route predicate: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: remoteaddr_route + uri: https://example.org + predicates: + - RemoteAddr=192.168.1.1/24 +---- + +This route matches if the remote address of the request was, for example, `192.168.1.10`. + +[[modifying-the-way-remote-addresses-are-resolved]] +=== Modifying the Way Remote Addresses Are Resolved + +By default, the RemoteAddr route predicate factory uses the remote address from the incoming request. +This may not match the actual client IP address if Spring Cloud Gateway sits behind a proxy layer. + +You can customize the way that the remote address is resolved by setting a custom `RemoteAddressResolver`. +Spring Cloud Gateway comes with one non-default remote address resolver that is based off of the https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For[X-Forwarded-For header], `XForwardedRemoteAddressResolver`. + +`XForwardedRemoteAddressResolver` has two static constructor methods, which take different approaches to security: + +* `XForwardedRemoteAddressResolver::trustAll` returns a `RemoteAddressResolver` that always takes the first IP address found in the `X-Forwarded-For` header. +This approach is vulnerable to spoofing, as a malicious client could set an initial value for the `X-Forwarded-For`, which would be accepted by the resolver. + +* `XForwardedRemoteAddressResolver::maxTrustedIndex` takes an index that correlates to the number of trusted infrastructure running in front of Spring Cloud Gateway. +If Spring Cloud Gateway is, for example only accessible through HAProxy, then a value of 1 should be used. +If two hops of trusted infrastructure are required before Spring Cloud Gateway is accessible, then a value of 2 should be used. + +Consider the following header value: + +[source] +---- +X-Forwarded-For: 0.0.0.1, 0.0.0.2, 0.0.0.3 +---- + +The following `maxTrustedIndex` values yield the following remote addresses: + +[options="header"] +|=== +|`maxTrustedIndex` | result +|[`Integer.MIN_VALUE`,0] | (invalid, `IllegalArgumentException` during initialization) +|1 | 0.0.0.3 +|2 | 0.0.0.2 +|3 | 0.0.0.1 +|[4, `Integer.MAX_VALUE`] | 0.0.0.1 +|=== + +[[gateway-route-filters]] +The following example shows how to achieve the same configuration with Java: + +.GatewayConfig.java +[source,java] +---- +RemoteAddressResolver resolver = XForwardedRemoteAddressResolver + .maxTrustedIndex(1); + +... + +.route("direct-route", + r -> r.remoteAddr("10.1.1.1", "10.10.1.1/24") + .uri("https://downstream1") +.route("proxied-route", + r -> r.remoteAddr(resolver, "10.10.1.1", "10.10.1.1/24") + .uri("https://downstream2") +) +---- + +[[the-weight-route-predicate-factory]] +== The Weight Route Predicate Factory + +The `Weight` route predicate factory takes two arguments: `group` and `weight` (an int). The weights are calculated per group. +The following example configures a weight route predicate: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: weight_high + uri: https://weighthigh.org + predicates: + - Weight=group1, 8 + - id: weight_low + uri: https://weightlow.org + predicates: + - Weight=group1, 2 +---- + +This route would forward ~80% of traffic to https://weighthigh.org and ~20% of traffic to https://weighlow.org + +[[the-xforwarded-remote-addr-route-predicate-factory]] +== The XForwarded Remote Addr Route Predicate Factory + +The `XForwarded Remote Addr` route predicate factory takes a list (min size 1) of `sources`, which are CIDR-notation (IPv4 or IPv6) strings, such as `192.168.0.1/16` (where `192.168.0.1` is an IP address and `16` is a subnet mask). + +This route predicate allows requests to be filtered based on the `X-Forwarded-For` HTTP header. + +This can be used with reverse proxies such as load balancers or web application firewalls where +the request should only be allowed if it comes from a trusted list of IP addresses used by those +reverse proxies. + + +The following example configures a XForwardedRemoteAddr route predicate: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: xforwarded_remoteaddr_route + uri: https://example.org + predicates: + - XForwardedRemoteAddr=192.168.1.1/24 +---- + +This route matches if the `X-Forwarded-For` header contains, for example, `192.168.1.10`. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/route-metadata-configuration.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/route-metadata-configuration.adoc new file mode 100644 index 000000000..6f4eb34ee --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/route-metadata-configuration.adoc @@ -0,0 +1,32 @@ +[[route-metadata-configuration]] += Route Metadata Configuration + +You can configure additional parameters for each route by using metadata, as follows: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + routes: + - id: route_with_metadata + uri: https://example.org + metadata: + optionName: "OptionValue" + compositeObject: + name: "value" + iAmNumber: 1 +---- + +You could acquire all metadata properties from an exchange, as follows: + +[source] +---- +Route route = exchange.getAttribute(GATEWAY_ROUTE_ATTR); +// get all metadata properties +route.getMetadata(); +// get a single metadata property +route.getMetadata(someKey); +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/starter.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/starter.adoc new file mode 100644 index 000000000..7bc6f3f12 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/starter.adoc @@ -0,0 +1,16 @@ +[[gateway-starter]] += How to Include Spring Cloud Gateway +:page-section-summary-toc: 1 + +To include Spring Cloud Gateway in your project, use the starter with a group ID of `org.springframework.cloud` and an artifact ID of `spring-cloud-starter-gateway`. +See the https://projects.spring.io/spring-cloud/[Spring Cloud Project page] for details on setting up your build system with the current Spring Cloud Release Train. + +If you include the starter, but you do not want the gateway to be enabled, set `spring.cloud.gateway.enabled=false`. + +IMPORTANT: Spring Cloud Gateway is built on https://spring.io/projects/spring-boot#learn[Spring Boot], https://docs.spring.io/spring/docs/current/spring-framework-reference/web-reactive.html[Spring WebFlux], and https://projectreactor.io/docs[Project Reactor]. +As a consequence, many of the familiar synchronous libraries (Spring Data and Spring Security, for example) and patterns you know may not apply when you use Spring Cloud Gateway. +If you are unfamiliar with these projects, we suggest you begin by reading their documentation to familiarize yourself with some new concepts before working with Spring Cloud Gateway. + +IMPORTANT: Spring Cloud Gateway requires the Netty runtime provided by Spring Boot and Spring Webflux. +It does not work in a traditional Servlet Container or when built as a WAR. + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/the-discoveryclient-route-definition-locator.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/the-discoveryclient-route-definition-locator.adoc new file mode 100644 index 000000000..0f92234b0 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/the-discoveryclient-route-definition-locator.adoc @@ -0,0 +1,36 @@ +[[the-discoveryclient-route-definition-locator]] += The `DiscoveryClient` Route Definition Locator + +You can configure the gateway to create routes based on services registered with a `DiscoveryClient` compatible service registry. + +To enable this, set `spring.cloud.gateway.discovery.locator.enabled=true` and make sure a `DiscoveryClient` implementation (such as Netflix Eureka, Consul, or Zookeeper) is on the classpath and enabled. + +[[configuring-predicates-and-filters-for-discoveryclient-routes]] +== Configuring Predicates and Filters For `DiscoveryClient` Routes + +By default, the gateway defines a single predicate and filter for routes created with a `DiscoveryClient`. + +The default predicate is a path predicate defined with the pattern `/serviceId/**`, where `serviceId` is +the ID of the service from the `DiscoveryClient`. + +The default filter is a rewrite path filter with the regex `/serviceId/?(?.*)` and the replacement `/$\{remaining}`. +This strips the service ID from the path before the request is sent downstream. + +If you want to customize the predicates or filters used by the `DiscoveryClient` routes, set `spring.cloud.gateway.discovery.locator.predicates[x]` and `spring.cloud.gateway.discovery.locator.filters[y]`. +When doing so, you need to make sure to include the default predicate and filter shown earlier, if you want to retain that functionality. +The following example shows what this looks like: + +.application.properties +[soure,properties] +---- +spring.cloud.gateway.discovery.locator.predicates[0].name: Path +spring.cloud.gateway.discovery.locator.predicates[0].args[pattern]: "'/'+serviceId+'/**'" +spring.cloud.gateway.discovery.locator.predicates[1].name: Host +spring.cloud.gateway.discovery.locator.predicates[1].args[pattern]: "'**.foo.com'" +spring.cloud.gateway.discovery.locator.filters[0].name: CircuitBreaker +spring.cloud.gateway.discovery.locator.filters[0].args[name]: serviceId +spring.cloud.gateway.discovery.locator.filters[1].name: RewritePath +spring.cloud.gateway.discovery.locator.filters[1].args[regexp]: "'/' + serviceId + '/?(?.*)'" +spring.cloud.gateway.discovery.locator.filters[1].args[replacement]: "'/$\{remaining}'" +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/tls-and-ssl.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/tls-and-ssl.adoc new file mode 100644 index 000000000..012f1cf36 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/tls-and-ssl.adoc @@ -0,0 +1,71 @@ +[[tls-and-ssl]] += TLS and SSL + +The gateway can listen for requests on HTTPS by following the usual Spring server configuration. +The following example shows how to do so: + +.application.yml +[source,yaml] +---- +server: + ssl: + enabled: true + key-alias: scg + key-store-password: scg1234 + key-store: classpath:scg-keystore.p12 + key-store-type: PKCS12 +---- + +You can route gateway routes to both HTTP and HTTPS backends. +If you are routing to an HTTPS backend, you can configure the gateway to trust all downstream certificates with the following configuration: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + httpclient: + ssl: + useInsecureTrustManager: true +---- + +Using an insecure trust manager is not suitable for production. +For a production deployment, you can configure the gateway with a set of known certificates that it can trust with the following configuration: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + httpclient: + ssl: + trustedX509Certificates: + - cert1.pem + - cert2.pem +---- + +If the Spring Cloud Gateway is not provisioned with trusted certificates, the default trust store is used (which you can override by setting the `javax.net.ssl.trustStore` system property). + +[[tls-handshake]] +== TLS Handshake + +The gateway maintains a client pool that it uses to route to backends. +When communicating over HTTPS, the client initiates a TLS handshake. +A number of timeouts are associated with this handshake. +You can configure these timeouts can be configured (defaults shown) as follows: + +.application.yml +[source,yaml] +---- +spring: + cloud: + gateway: + httpclient: + ssl: + handshake-timeout-millis: 10000 + close-notify-flush-timeout-millis: 3000 + close-notify-read-timeout-millis: 0 +---- + diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway/troubleshooting.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway/troubleshooting.adoc new file mode 100644 index 000000000..b8c2b5093 --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway/troubleshooting.adoc @@ -0,0 +1,25 @@ +[[troubleshooting]] += Troubleshooting +:page-section-summary-toc: 1 + +This section covers common problems that may arise when you use Spring Cloud Gateway. + +[[log-levels]] +== Log Levels + +The following loggers may contain valuable troubleshooting information at the `DEBUG` and `TRACE` levels: + +- `org.springframework.cloud.gateway` +- `org.springframework.http.server.reactive` +- `org.springframework.web.reactive` +- `org.springframework.boot.autoconfigure.web` +- `reactor.netty` +- `redisratelimiter` + +[[wiretap]] +== Wiretap + +The Reactor Netty `HttpClient` and `HttpServer` can have wiretap enabled. +When combined with setting the `reactor.netty` log level to `DEBUG` or `TRACE`, it enables the logging of information, such as headers and bodies sent and received across the wire. +To enable wiretap, set `spring.cloud.gateway.httpserver.wiretap=true` or `spring.cloud.gateway.httpclient.wiretap=true` for the `HttpServer` and `HttpClient`, respectively. + diff --git a/docs/pom.xml b/docs/pom.xml index aefdaea72..08fa07a55 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -11,20 +11,19 @@ spring-cloud-gateway-docs jar Spring Cloud Gateway Docs - Spring Cloud Docs + Spring Cloud Gateway Docs spring-cloud-gateway ${basedir}/.. spring.cloud.gateway.* - deploy none - 1.0.0 - ${maven.multiModuleProjectDirectory}/spring-cloud-gateway-server/ + 1.0.2 + ${maven.multiModuleProjectDirectory}/ .* - ${maven.multiModuleProjectDirectory}/docs/target/observability/ + ${maven.multiModuleProjectDirectory}/docs/modules/ROOT/partials/ @@ -39,6 +38,12 @@ docs + + + src/main/antora/resources/antora-resources + true + + pl.project13.maven @@ -49,8 +54,8 @@ exec-maven-plugin - generate-docs - prepare-package + generate-observability-docs + ${generate-docs.phase} java @@ -79,12 +84,12 @@ maven-dependency-plugin - org.apache.maven.plugins - maven-resources-plugin + io.spring.maven.antora + antora-component-version-maven-plugin - org.asciidoctor - asciidoctor-maven-plugin + io.spring.maven.antora + antora-maven-plugin org.apache.maven.plugins diff --git a/docs/src/main/antora/resources/antora-resources/antora.yml b/docs/src/main/antora/resources/antora-resources/antora.yml new file mode 100644 index 000000000..9148923fa --- /dev/null +++ b/docs/src/main/antora/resources/antora-resources/antora.yml @@ -0,0 +1,20 @@ +version: @antora-component.version@ +prerelease: @antora-component.prerelease@ + +asciidoc: + attributes: + attribute-missing: 'warn' + chomp: 'all' + project-root: @maven.multiModuleProjectDirectory@ + github-repo: @docs.main@ + github-raw: https://raw.githubusercontent.com/spring-cloud/@docs.main@/@github-tag@ + github-code: https://github.com/spring-cloud/@docs.main@/tree/@github-tag@ + github-issues: https://github.com/spring-cloud/@docs.main@/issues/ + github-wiki: https://github.com/spring-cloud/@docs.main@/wiki + spring-cloud-version: @project.version@ + github-tag: @github-tag@ + version-type: @version-type@ + docs-url: https://docs.spring.io/@docs.main@/docs/@project.version@ + raw-docs-url: https://raw.githubusercontent.com/spring-cloud/@docs.main@/@github-tag@ + project-version: @project.version@ + project-name: @docs.main@ diff --git a/docs/src/main/asciidoc/README.adoc b/docs/src/main/asciidoc/README.adoc index eea6e56d8..6c6ec2e54 100644 --- a/docs/src/main/asciidoc/README.adoc +++ b/docs/src/main/asciidoc/README.adoc @@ -2,9 +2,9 @@ image::https://github.com/spring-cloud/spring-cloud-gateway/workflows/Build/badg image::https://codecov.io/gh/spring-cloud/spring-cloud-gateway/branch/main/graph/badge.svg["Codecov", link="https://codecov.io/gh/spring-cloud/spring-cloud-gateway/branch/main"] -include::intro.adoc[] -== Features +[[features]] += Features * Java 17 * Spring Framework 6 @@ -17,10 +17,12 @@ include::intro.adoc[] * API or configuration driven * Supports Spring Cloud `DiscoveryClient` for configuring Routes -== Building +[[building]] += Building -include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/building.adoc[] +include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/docs/modules/ROOT/partials/contributing.adoc[] -== Contributing +[[contributing]] += Contributing include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing.adoc[] diff --git a/docs/src/main/asciidoc/_configprops.adoc b/docs/src/main/asciidoc/_configprops.adoc deleted file mode 100644 index 0eef05826..000000000 --- a/docs/src/main/asciidoc/_configprops.adoc +++ /dev/null @@ -1,154 +0,0 @@ -|=== -|Name | Default | Description - -|spring.cloud.gateway.default-filters | | List of filter definitions that are applied to every route. -|spring.cloud.gateway.discovery.locator.enabled | `+++false+++` | Flag that enables DiscoveryClient gateway integration. -|spring.cloud.gateway.discovery.locator.filters | | -|spring.cloud.gateway.discovery.locator.include-expression | `+++true+++` | SpEL expression that will evaluate whether to include a service in gateway integration or not, defaults to: true. -|spring.cloud.gateway.discovery.locator.lower-case-service-id | `+++false+++` | Option to lower case serviceId in predicates and filters, defaults to false. Useful with eureka when it automatically uppercases serviceId. so MYSERIVCE, would match /myservice/** -|spring.cloud.gateway.discovery.locator.predicates | | -|spring.cloud.gateway.discovery.locator.route-id-prefix | | The prefix for the routeId, defaults to discoveryClient.getClass().getSimpleName() + "_". Service Id will be appended to create the routeId. -|spring.cloud.gateway.discovery.locator.url-expression | `+++'lb://'+serviceId+++` | SpEL expression that create the uri for each route, defaults to: 'lb://'+serviceId. -|spring.cloud.gateway.enabled | `+++true+++` | Enables gateway functionality. -|spring.cloud.gateway.fail-on-route-definition-error | `+++true+++` | Option to fail on route definition errors, defaults to true. Otherwise, a warning is logged. -|spring.cloud.gateway.filter.add-request-header.enabled | `+++true+++` | Enables the add-request-header filter. -|spring.cloud.gateway.filter.add-request-parameter.enabled | `+++true+++` | Enables the add-request-parameter filter. -|spring.cloud.gateway.filter.add-response-header.enabled | `+++true+++` | Enables the add-response-header filter. -|spring.cloud.gateway.filter.circuit-breaker.enabled | `+++true+++` | Enables the circuit-breaker filter. -|spring.cloud.gateway.filter.dedupe-response-header.enabled | `+++true+++` | Enables the dedupe-response-header filter. -|spring.cloud.gateway.filter.fallback-headers.enabled | `+++true+++` | Enables the fallback-headers filter. -|spring.cloud.gateway.filter.hystrix.enabled | `+++true+++` | Enables the hystrix filter. -|spring.cloud.gateway.filter.json-to-grpc.enabled | `+++true+++` | Enables the JSON to gRPC filter. -|spring.cloud.gateway.filter.local-response-cache.enabled | `+++false+++` | Enables the local-response-cache filter. -|spring.cloud.gateway.filter.local-response-cache.size | `+++5m+++` | Maximum size of the cache to evict entries for this route (in KB, MB and GB). -|spring.cloud.gateway.filter.local-response-cache.time-to-live | | Time to expire a cache entry (expressed in s for seconds, m for minutes, and h for hours). -|spring.cloud.gateway.filter.map-request-header.enabled | `+++true+++` | Enables the map-request-header filter. -|spring.cloud.gateway.filter.modify-request-body.enabled | `+++true+++` | Enables the modify-request-body filter. -|spring.cloud.gateway.filter.modify-response-body.enabled | `+++true+++` | Enables the modify-response-body filter. -|spring.cloud.gateway.filter.prefix-path.enabled | `+++true+++` | Enables the prefix-path filter. -|spring.cloud.gateway.filter.preserve-host-header.enabled | `+++true+++` | Enables the preserve-host-header filter. -|spring.cloud.gateway.filter.redirect-to.enabled | `+++true+++` | Enables the redirect-to filter. -|spring.cloud.gateway.filter.remove-hop-by-hop.headers | | -|spring.cloud.gateway.filter.remove-hop-by-hop.order | `+++0+++` | -|spring.cloud.gateway.filter.remove-request-header.enabled | `+++true+++` | Enables the remove-request-header filter. -|spring.cloud.gateway.filter.remove-request-parameter.enabled | `+++true+++` | Enables the remove-request-parameter filter. -|spring.cloud.gateway.filter.remove-response-header.enabled | `+++true+++` | Enables the remove-response-header filter. -|spring.cloud.gateway.filter.request-header-size.enabled | `+++true+++` | Enables the request-header-size filter. -|spring.cloud.gateway.filter.request-header-to-request-uri.enabled | `+++true+++` | Enables the request-header-to-request-uri filter. -|spring.cloud.gateway.filter.request-rate-limiter.default-key-resolver | | -|spring.cloud.gateway.filter.request-rate-limiter.default-rate-limiter | | -|spring.cloud.gateway.filter.request-rate-limiter.enabled | `+++true+++` | Enables the request-rate-limiter filter. -|spring.cloud.gateway.filter.request-size.enabled | `+++true+++` | Enables the request-size filter. -|spring.cloud.gateway.filter.retry.enabled | `+++true+++` | Enables the retry filter. -|spring.cloud.gateway.filter.rewrite-location-response-header.enabled | `+++true+++` | Enables the rewrite-location-response-header filter. -|spring.cloud.gateway.filter.rewrite-location.enabled | `+++true+++` | Enables the rewrite-location filter. -|spring.cloud.gateway.filter.rewrite-path.enabled | `+++true+++` | Enables the rewrite-path filter. -|spring.cloud.gateway.filter.rewrite-response-header.enabled | `+++true+++` | Enables the rewrite-response-header filter. -|spring.cloud.gateway.filter.save-session.enabled | `+++true+++` | Enables the save-session filter. -|spring.cloud.gateway.filter.secure-headers.content-security-policy | `+++default-src 'self' https:; font-src 'self' https: data:; img-src 'self' https: data:; object-src 'none'; script-src https:; style-src 'self' https: 'unsafe-inline'+++` | -|spring.cloud.gateway.filter.secure-headers.content-type-options | `+++nosniff+++` | -|spring.cloud.gateway.filter.secure-headers.disable | | -|spring.cloud.gateway.filter.secure-headers.download-options | `+++noopen+++` | -|spring.cloud.gateway.filter.secure-headers.enabled | `+++true+++` | Enables the secure-headers filter. -|spring.cloud.gateway.filter.secure-headers.frame-options | `+++DENY+++` | -|spring.cloud.gateway.filter.secure-headers.permitted-cross-domain-policies | `+++none+++` | -|spring.cloud.gateway.filter.secure-headers.referrer-policy | `+++no-referrer+++` | -|spring.cloud.gateway.filter.secure-headers.strict-transport-security | `+++max-age=631138519+++` | -|spring.cloud.gateway.filter.secure-headers.xss-protection-header | `+++1 ; mode=block+++` | -|spring.cloud.gateway.filter.set-path.enabled | `+++true+++` | Enables the set-path filter. -|spring.cloud.gateway.filter.set-request-header.enabled | `+++true+++` | Enables the set-request-header filter. -|spring.cloud.gateway.filter.set-request-host-header.enabled | `+++true+++` | Enables the set-request-host-header filter. -|spring.cloud.gateway.filter.set-response-header.enabled | `+++true+++` | Enables the set-response-header filter. -|spring.cloud.gateway.filter.set-status.enabled | `+++true+++` | Enables the set-status filter. -|spring.cloud.gateway.filter.strip-prefix.enabled | `+++true+++` | Enables the strip-prefix filter. -|spring.cloud.gateway.forwarded.enabled | `+++true+++` | Enables the ForwardedHeadersFilter. -|spring.cloud.gateway.global-filter.adapt-cached-body.enabled | `+++true+++` | Enables the adapt-cached-body global filter. -|spring.cloud.gateway.global-filter.forward-path.enabled | `+++true+++` | Enables the forward-path global filter. -|spring.cloud.gateway.global-filter.forward-routing.enabled | `+++true+++` | Enables the forward-routing global filter. -|spring.cloud.gateway.global-filter.load-balancer-client.enabled | `+++true+++` | Enables the load-balancer-client global filter. -|spring.cloud.gateway.global-filter.local-response-cache.enabled | `+++true+++` | Enables the local-response-cache filter for all routes, it allows to add a specific configuration at route level using LocalResponseCache filter. -|spring.cloud.gateway.global-filter.netty-routing.enabled | `+++true+++` | Enables the netty-routing global filter. -|spring.cloud.gateway.global-filter.netty-write-response.enabled | `+++true+++` | Enables the netty-write-response global filter. -|spring.cloud.gateway.global-filter.reactive-load-balancer-client.enabled | `+++true+++` | Enables the reactive-load-balancer-client global filter. -|spring.cloud.gateway.global-filter.remove-cached-body.enabled | `+++true+++` | Enables the remove-cached-body global filter. -|spring.cloud.gateway.global-filter.route-to-request-url.enabled | `+++true+++` | Enables the route-to-request-url global filter. -|spring.cloud.gateway.global-filter.websocket-routing.enabled | `+++true+++` | Enables the websocket-routing global filter. -|spring.cloud.gateway.globalcors.add-to-simple-url-handler-mapping | `+++false+++` | If global CORS config should be added to the URL handler. -|spring.cloud.gateway.globalcors.cors-configurations | | -|spring.cloud.gateway.handler-mapping.order | `+++1+++` | The order of RoutePredicateHandlerMapping. -|spring.cloud.gateway.httpclient.compression | `+++false+++` | Enables compression for Netty HttpClient. -|spring.cloud.gateway.httpclient.connect-timeout | | The connect timeout in millis, the default is 30s. -|spring.cloud.gateway.httpclient.max-header-size | | The max response header size. -|spring.cloud.gateway.httpclient.max-initial-line-length | | The max initial line length. -|spring.cloud.gateway.httpclient.pool.acquire-timeout | | Only for type FIXED, the maximum time in millis to wait for acquiring. -|spring.cloud.gateway.httpclient.pool.eviction-interval | `+++0+++` | Perform regular eviction checks in the background at a specified interval. Disabled by default ({@link Duration#ZERO}) -|spring.cloud.gateway.httpclient.pool.max-connections | | Only for type FIXED, the maximum number of connections before starting pending acquisition on existing ones. -|spring.cloud.gateway.httpclient.pool.max-idle-time | | Time in millis after which the channel will be closed. If NULL, there is no max idle time. -|spring.cloud.gateway.httpclient.pool.max-life-time | | Duration after which the channel will be closed. If NULL, there is no max life time. -|spring.cloud.gateway.httpclient.pool.metrics | `+++false+++` | Enables channel pools metrics to be collected and registered in Micrometer. Disabled by default. -|spring.cloud.gateway.httpclient.pool.name | `+++proxy+++` | The channel pool map name, defaults to proxy. -|spring.cloud.gateway.httpclient.pool.type | | Type of pool for HttpClient to use, defaults to ELASTIC. -|spring.cloud.gateway.httpclient.proxy.host | | Hostname for proxy configuration of Netty HttpClient. -|spring.cloud.gateway.httpclient.proxy.non-proxy-hosts-pattern | | Regular expression (Java) for a configured list of hosts. that should be reached directly, bypassing the proxy -|spring.cloud.gateway.httpclient.proxy.password | | Password for proxy configuration of Netty HttpClient. -|spring.cloud.gateway.httpclient.proxy.port | | Port for proxy configuration of Netty HttpClient. -|spring.cloud.gateway.httpclient.proxy.type | | proxyType for proxy configuration of Netty HttpClient. -|spring.cloud.gateway.httpclient.proxy.username | | Username for proxy configuration of Netty HttpClient. -|spring.cloud.gateway.httpclient.response-timeout | | The response timeout. -|spring.cloud.gateway.httpclient.ssl.close-notify-flush-timeout | `+++3000ms+++` | SSL close_notify flush timeout. Default to 3000 ms. -|spring.cloud.gateway.httpclient.ssl.close-notify-read-timeout | `+++0+++` | SSL close_notify read timeout. Default to 0 ms. -|spring.cloud.gateway.httpclient.ssl.handshake-timeout | `+++10000ms+++` | SSL handshake timeout. Default to 10000 ms -|spring.cloud.gateway.httpclient.ssl.key-password | | Key password, default is same as keyStorePassword. -|spring.cloud.gateway.httpclient.ssl.key-store | | Keystore path for Netty HttpClient. -|spring.cloud.gateway.httpclient.ssl.key-store-password | | Keystore password. -|spring.cloud.gateway.httpclient.ssl.key-store-provider | | Keystore provider for Netty HttpClient, optional field. -|spring.cloud.gateway.httpclient.ssl.key-store-type | `+++JKS+++` | Keystore type for Netty HttpClient, default is JKS. -|spring.cloud.gateway.httpclient.ssl.trusted-x509-certificates | | Trusted certificates for verifying the remote endpoint's certificate. -|spring.cloud.gateway.httpclient.ssl.use-insecure-trust-manager | `+++false+++` | Installs the netty InsecureTrustManagerFactory. This is insecure and not suitable for production. -|spring.cloud.gateway.httpclient.websocket.max-frame-payload-length | | Max frame payload length. -|spring.cloud.gateway.httpclient.websocket.proxy-ping | `+++true+++` | Proxy ping frames to downstream services, defaults to true. -|spring.cloud.gateway.httpclient.wiretap | `+++false+++` | Enables wiretap debugging for Netty HttpClient. -|spring.cloud.gateway.httpserver.wiretap | `+++false+++` | Enables wiretap debugging for Netty HttpServer. -|spring.cloud.gateway.loadbalancer.use404 | `+++false+++` | -|spring.cloud.gateway.metrics.enabled | `+++false+++` | Enables the collection of metrics data. -|spring.cloud.gateway.metrics.prefix | `+++spring.cloud.gateway+++` | The prefix of all metrics emitted by gateway. -|spring.cloud.gateway.metrics.tags | | Tags map that added to metrics. -|spring.cloud.gateway.observability.enabled | `+++true+++` | If Micrometer Observability support should be turned on. -|spring.cloud.gateway.predicate.after.enabled | `+++true+++` | Enables the after predicate. -|spring.cloud.gateway.predicate.before.enabled | `+++true+++` | Enables the before predicate. -|spring.cloud.gateway.predicate.between.enabled | `+++true+++` | Enables the between predicate. -|spring.cloud.gateway.predicate.cloud-foundry-route-service.enabled | `+++true+++` | Enables the cloud-foundry-route-service predicate. -|spring.cloud.gateway.predicate.cookie.enabled | `+++true+++` | Enables the cookie predicate. -|spring.cloud.gateway.predicate.header.enabled | `+++true+++` | Enables the header predicate. -|spring.cloud.gateway.predicate.host.enabled | `+++true+++` | Enables the host predicate. -|spring.cloud.gateway.predicate.method.enabled | `+++true+++` | Enables the method predicate. -|spring.cloud.gateway.predicate.path.enabled | `+++true+++` | Enables the path predicate. -|spring.cloud.gateway.predicate.query.enabled | `+++true+++` | Enables the query predicate. -|spring.cloud.gateway.predicate.read-body.enabled | `+++true+++` | Enables the read-body predicate. -|spring.cloud.gateway.predicate.remote-addr.enabled | `+++true+++` | Enables the remote-addr predicate. -|spring.cloud.gateway.predicate.weight.enabled | `+++true+++` | Enables the weight predicate. -|spring.cloud.gateway.predicate.xforwarded-remote-addr.enabled | `+++true+++` | Enables the xforwarded-remote-addr predicate. -|spring.cloud.gateway.redis-rate-limiter.burst-capacity-header | `+++X-RateLimit-Burst-Capacity+++` | The name of the header that returns the burst capacity configuration. -|spring.cloud.gateway.redis-rate-limiter.config | | -|spring.cloud.gateway.redis-rate-limiter.include-headers | `+++true+++` | Whether or not to include headers containing rate limiter information, defaults to true. -|spring.cloud.gateway.redis-rate-limiter.remaining-header | `+++X-RateLimit-Remaining+++` | The name of the header that returns number of remaining requests during the current second. -|spring.cloud.gateway.redis-rate-limiter.replenish-rate-header | `+++X-RateLimit-Replenish-Rate+++` | The name of the header that returns the replenish rate configuration. -|spring.cloud.gateway.redis-rate-limiter.requested-tokens-header | `+++X-RateLimit-Requested-Tokens+++` | The name of the header that returns the requested tokens configuration. -|spring.cloud.gateway.restrictive-property-accessor.enabled | `+++true+++` | Restricts method and property access in SpEL. -|spring.cloud.gateway.routes | | List of Routes. -|spring.cloud.gateway.set-status.original-status-header-name | | The name of the header which contains http code of the proxied request. -|spring.cloud.gateway.streaming-media-types | | -|spring.cloud.gateway.x-forwarded.enabled | `+++true+++` | If the XForwardedHeadersFilter is enabled. -|spring.cloud.gateway.x-forwarded.for-append | `+++true+++` | If appending X-Forwarded-For as a list is enabled. -|spring.cloud.gateway.x-forwarded.for-enabled | `+++true+++` | If X-Forwarded-For is enabled. -|spring.cloud.gateway.x-forwarded.host-append | `+++true+++` | If appending X-Forwarded-Host as a list is enabled. -|spring.cloud.gateway.x-forwarded.host-enabled | `+++true+++` | If X-Forwarded-Host is enabled. -|spring.cloud.gateway.x-forwarded.order | `+++0+++` | The order of the XForwardedHeadersFilter. -|spring.cloud.gateway.x-forwarded.port-append | `+++true+++` | If appending X-Forwarded-Port as a list is enabled. -|spring.cloud.gateway.x-forwarded.port-enabled | `+++true+++` | If X-Forwarded-Port is enabled. -|spring.cloud.gateway.x-forwarded.prefix-append | `+++true+++` | If appending X-Forwarded-Prefix as a list is enabled. -|spring.cloud.gateway.x-forwarded.prefix-enabled | `+++true+++` | If X-Forwarded-Prefix is enabled. -|spring.cloud.gateway.x-forwarded.proto-append | `+++true+++` | If appending X-Forwarded-Proto as a list is enabled. -|spring.cloud.gateway.x-forwarded.proto-enabled | `+++true+++` | If X-Forwarded-Proto is enabled. - -|=== \ No newline at end of file diff --git a/docs/src/main/asciidoc/appendix.adoc b/docs/src/main/asciidoc/appendix.adoc deleted file mode 100644 index e1a317d37..000000000 --- a/docs/src/main/asciidoc/appendix.adoc +++ /dev/null @@ -1,20 +0,0 @@ -:numbered!: -[appendix] -[[common-application-properties]] -== Common application properties - -include::_attributes.adoc[] - -Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches. -This appendix provides a list of common {project-full-name} properties and references to the underlying classes that consume them. - -NOTE: Property contributions can come from additional jar files on your classpath, so you should not consider this an exhaustive list. -Also, you can define your own properties. - -include::_configprops.adoc[] - -include::{project-root}/docs/target/observability/_metrics.adoc[] - -include::{project-root}/docs/target/observability/_spans.adoc[] - -include::{project-root}/docs/target/observability/_conventions.adoc[] diff --git a/docs/src/main/asciidoc/index.adoc b/docs/src/main/asciidoc/index.adoc deleted file mode 100644 index e88e83722..000000000 --- a/docs/src/main/asciidoc/index.adoc +++ /dev/null @@ -1 +0,0 @@ -include::spring-cloud-gateway.adoc[] diff --git a/docs/src/main/asciidoc/spring-cloud-gateway.adoc b/docs/src/main/asciidoc/spring-cloud-gateway.adoc deleted file mode 100644 index c2fe94064..000000000 --- a/docs/src/main/asciidoc/spring-cloud-gateway.adoc +++ /dev/null @@ -1,3344 +0,0 @@ -= Spring Cloud Gateway -include::_attributes.adoc[] - -*{spring-cloud-version}* - -include::intro.adoc[] - -[[gateway-starter]] -== How to Include Spring Cloud Gateway - -To include Spring Cloud Gateway in your project, use the starter with a group ID of `org.springframework.cloud` and an artifact ID of `spring-cloud-starter-gateway`. -See the https://projects.spring.io/spring-cloud/[Spring Cloud Project page] for details on setting up your build system with the current Spring Cloud Release Train. - -If you include the starter, but you do not want the gateway to be enabled, set `spring.cloud.gateway.enabled=false`. - -IMPORTANT: Spring Cloud Gateway is built on https://spring.io/projects/spring-boot#learn[Spring Boot], https://docs.spring.io/spring/docs/current/spring-framework-reference/web-reactive.html[Spring WebFlux], and https://projectreactor.io/docs[Project Reactor]. -As a consequence, many of the familiar synchronous libraries (Spring Data and Spring Security, for example) and patterns you know may not apply when you use Spring Cloud Gateway. -If you are unfamiliar with these projects, we suggest you begin by reading their documentation to familiarize yourself with some new concepts before working with Spring Cloud Gateway. - -IMPORTANT: Spring Cloud Gateway requires the Netty runtime provided by Spring Boot and Spring Webflux. -It does not work in a traditional Servlet Container or when built as a WAR. - -== Glossary - -* *Route*: The basic building block of the gateway. -It is defined by an ID, a destination URI, a collection of predicates, and a collection of filters. A route is matched if the aggregate predicate is true. -* *Predicate*: This is a https://docs.oracle.com/javase/8/docs/api/java/util/function/Predicate.html[Java 8 Function Predicate]. The input type is a https://docs.spring.io/spring/docs/5.0.x/javadoc-api/org/springframework/web/server/ServerWebExchange.html[Spring Framework `ServerWebExchange`]. -This lets you match on anything from the HTTP request, such as headers or parameters. -* *Filter*: These are instances of {github-code}/spring-cloud-gateway-server/src/main/java/org/springframework/cloud/gateway/filter/GatewayFilter.java[`GatewayFilter`] that have been constructed with a specific factory. -Here, you can modify requests and responses before or after sending the downstream request. - -[[gateway-how-it-works]] -== How It Works - -The following diagram provides a high-level overview of how Spring Cloud Gateway works: - -image::spring_cloud_gateway_diagram.png[Spring Cloud Gateway Diagram] - -Clients make requests to Spring Cloud Gateway. If the Gateway Handler Mapping determines that a request matches a route, it is sent to the Gateway Web Handler. -This handler runs the request through a filter chain that is specific to the request. -The reason the filters are divided by the dotted line is that filters can run logic both before and after the proxy request is sent. -All "`pre`" filter logic is executed. Then the proxy request is made. After the proxy request is made, the "`post`" filter logic is run. - -NOTE: URIs defined in routes without a port get default port values of 80 and 443 for the HTTP and HTTPS URIs, respectively. - -== Configuring Route Predicate Factories and Gateway Filter Factories - -There are two ways to configure predicates and filters: shortcuts and fully expanded arguments. Most examples below use the shortcut way. - -The name and argument names are listed as `code` in the first sentence or two of each section. The arguments are typically listed in the order that are needed for the shortcut configuration. - -=== Shortcut Configuration - -Shortcut configuration is recognized by the filter name, followed by an equals sign (`=`), followed by argument values separated by commas (`,`). - -.application.yml -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: after_route - uri: https://example.org - predicates: - - Cookie=mycookie,mycookievalue ----- - -The previous sample defines the `Cookie` Route Predicate Factory with two arguments, the cookie name, `mycookie` and the value to match `mycookievalue`. - -=== Fully Expanded Arguments - -Fully expanded arguments appear more like standard yaml configuration with name/value pairs. Typically, there will be a `name` key and an `args` key. The `args` key is a map of key value pairs to configure the predicate or filter. - -.application.yml -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: after_route - uri: https://example.org - predicates: - - name: Cookie - args: - name: mycookie - regexp: mycookievalue ----- - -This is the full configuration of the shortcut configuration of the `Cookie` predicate shown above. - -[[gateway-request-predicates-factories]] -== Route Predicate Factories - -Spring Cloud Gateway matches routes as part of the Spring WebFlux `HandlerMapping` infrastructure. -Spring Cloud Gateway includes many built-in route predicate factories. -All of these predicates match on different attributes of the HTTP request. -You can combine multiple route predicate factories with logical `and` statements. - -=== The After Route Predicate Factory - -The `After` route predicate factory takes one parameter, a `datetime` (which is a java `ZonedDateTime`). -This predicate matches requests that happen after the specified datetime. -The following example configures an after route predicate: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: after_route - uri: https://example.org - predicates: - - After=2017-01-20T17:42:47.789-07:00[America/Denver] ----- -==== - -This route matches any request made after Jan 20, 2017 17:42 Mountain Time (Denver). - -=== The Before Route Predicate Factory - -The `Before` route predicate factory takes one parameter, a `datetime` (which is a java `ZonedDateTime`). -This predicate matches requests that happen before the specified `datetime`. -The following example configures a before route predicate: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: before_route - uri: https://example.org - predicates: - - Before=2017-01-20T17:42:47.789-07:00[America/Denver] ----- -==== - -This route matches any request made before Jan 20, 2017 17:42 Mountain Time (Denver). - -=== The Between Route Predicate Factory - -The `Between` route predicate factory takes two parameters, `datetime1` and `datetime2` -which are java `ZonedDateTime` objects. -This predicate matches requests that happen after `datetime1` and before `datetime2`. -The `datetime2` parameter must be after `datetime1`. -The following example configures a between route predicate: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: between_route - uri: https://example.org - predicates: - - Between=2017-01-20T17:42:47.789-07:00[America/Denver], 2017-01-21T17:42:47.789-07:00[America/Denver] ----- -==== - -This route matches any request made after Jan 20, 2017 17:42 Mountain Time (Denver) and before Jan 21, 2017 17:42 Mountain Time (Denver). -This could be useful for maintenance windows. - -=== The Cookie Route Predicate Factory - -The `Cookie` route predicate factory takes two parameters, the cookie `name` and a `regexp` (which is a Java regular expression). -This predicate matches cookies that have the given name and whose values match the regular expression. -The following example configures a cookie route predicate factory: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: cookie_route - uri: https://example.org - predicates: - - Cookie=chocolate, ch.p ----- -==== - -This route matches requests that have a cookie named `chocolate` whose value matches the `ch.p` regular expression. - -=== The Header Route Predicate Factory - -The `Header` route predicate factory takes two parameters, the `header` and a `regexp` (which is a Java regular expression). -This predicate matches with a header that has the given name whose value matches the regular expression. -The following example configures a header route predicate: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: header_route - uri: https://example.org - predicates: - - Header=X-Request-Id, \d+ ----- -==== - -This route matches if the request has a header named `X-Request-Id` whose value matches the `\d+` regular expression (that is, it has a value of one or more digits). - -=== The Host Route Predicate Factory - -The `Host` route predicate factory takes one parameter: a list of host name `patterns`. -The pattern is an Ant-style pattern with `.` as the separator. -This predicates matches the `Host` header that matches the pattern. -The following example configures a host route predicate: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: host_route - uri: https://example.org - predicates: - - Host=**.somehost.org,**.anotherhost.org ----- -==== - -URI template variables (such as `{sub}.myhost.org`) are supported as well. - -This route matches if the request has a `Host` header with a value of `www.somehost.org` or `beta.somehost.org` or `www.anotherhost.org`. - -This predicate extracts the URI template variables (such as `sub`, defined in the preceding example) as a map of names and values and places it in the `ServerWebExchange.getAttributes()` with a key defined in `ServerWebExchangeUtils.URI_TEMPLATE_VARIABLES_ATTRIBUTE`. -Those values are then available for use by <> - - -=== The Method Route Predicate Factory - -The `Method` Route Predicate Factory takes a `methods` argument which is one or more parameters: the HTTP methods to match. -The following example configures a method route predicate: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: method_route - uri: https://example.org - predicates: - - Method=GET,POST ----- -==== - -This route matches if the request method was a `GET` or a `POST`. - -=== The Path Route Predicate Factory - -The `Path` Route Predicate Factory takes two parameters: a list of Spring `PathMatcher` `patterns` and an optional flag called `matchTrailingSlash` (defaults to `true`). -The following example configures a path route predicate: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: path_route - uri: https://example.org - predicates: - - Path=/red/{segment},/blue/{segment} ----- -==== - -This route matches if the request path was, for example: `/red/1` or `/red/1/` or `/red/blue` or `/blue/green`. - -If `matchTrailingSlash` is set to `false`, then request path `/red/1/` will not be matched. - -This predicate extracts the URI template variables (such as `segment`, defined in the preceding example) as a map of names and values and places it in the `ServerWebExchange.getAttributes()` with a key defined in `ServerWebExchangeUtils.URI_TEMPLATE_VARIABLES_ATTRIBUTE`. -Those values are then available for use by <> - -A utility method (called `get`) is available to make access to these variables easier. -The following example shows how to use the `get` method: - -==== -[source,java] ----- -Map uriVariables = ServerWebExchangeUtils.getUriTemplateVariables(exchange); - -String segment = uriVariables.get("segment"); ----- -==== - -=== The Query Route Predicate Factory - -The `Query` route predicate factory takes two parameters: a required `param` and an optional `regexp` (which is a Java regular expression). -The following example configures a query route predicate: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: query_route - uri: https://example.org - predicates: - - Query=green ----- -==== - -The preceding route matches if the request contained a `green` query parameter. - -.application.yml -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: query_route - uri: https://example.org - predicates: - - Query=red, gree. ----- - -The preceding route matches if the request contained a `red` query parameter whose value matched the `gree.` regexp, so `green` and `greet` would match. - - -=== The RemoteAddr Route Predicate Factory - -The `RemoteAddr` route predicate factory takes a list (min size 1) of `sources`, which are CIDR-notation (IPv4 or IPv6) strings, such as `192.168.0.1/16` (where `192.168.0.1` is an IP address and `16` is a subnet mask). -The following example configures a RemoteAddr route predicate: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: remoteaddr_route - uri: https://example.org - predicates: - - RemoteAddr=192.168.1.1/24 ----- -==== - -This route matches if the remote address of the request was, for example, `192.168.1.10`. - -==== Modifying the Way Remote Addresses Are Resolved - -By default, the RemoteAddr route predicate factory uses the remote address from the incoming request. -This may not match the actual client IP address if Spring Cloud Gateway sits behind a proxy layer. - -You can customize the way that the remote address is resolved by setting a custom `RemoteAddressResolver`. -Spring Cloud Gateway comes with one non-default remote address resolver that is based off of the https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For[X-Forwarded-For header], `XForwardedRemoteAddressResolver`. - -`XForwardedRemoteAddressResolver` has two static constructor methods, which take different approaches to security: - -* `XForwardedRemoteAddressResolver::trustAll` returns a `RemoteAddressResolver` that always takes the first IP address found in the `X-Forwarded-For` header. -This approach is vulnerable to spoofing, as a malicious client could set an initial value for the `X-Forwarded-For`, which would be accepted by the resolver. - -* `XForwardedRemoteAddressResolver::maxTrustedIndex` takes an index that correlates to the number of trusted infrastructure running in front of Spring Cloud Gateway. -If Spring Cloud Gateway is, for example only accessible through HAProxy, then a value of 1 should be used. -If two hops of trusted infrastructure are required before Spring Cloud Gateway is accessible, then a value of 2 should be used. - -Consider the following header value: - -==== -[source] ----- -X-Forwarded-For: 0.0.0.1, 0.0.0.2, 0.0.0.3 ----- -==== - -The following `maxTrustedIndex` values yield the following remote addresses: - -[options="header"] -|=== -|`maxTrustedIndex` | result -|[`Integer.MIN_VALUE`,0] | (invalid, `IllegalArgumentException` during initialization) -|1 | 0.0.0.3 -|2 | 0.0.0.2 -|3 | 0.0.0.1 -|[4, `Integer.MAX_VALUE`] | 0.0.0.1 -|=== -[[gateway-route-filters]] - -The following example shows how to achieve the same configuration with Java: - -.GatewayConfig.java -==== -[source,java] ----- -RemoteAddressResolver resolver = XForwardedRemoteAddressResolver - .maxTrustedIndex(1); - -... - -.route("direct-route", - r -> r.remoteAddr("10.1.1.1", "10.10.1.1/24") - .uri("https://downstream1") -.route("proxied-route", - r -> r.remoteAddr(resolver, "10.10.1.1", "10.10.1.1/24") - .uri("https://downstream2") -) ----- -==== - -=== The Weight Route Predicate Factory - -The `Weight` route predicate factory takes two arguments: `group` and `weight` (an int). The weights are calculated per group. -The following example configures a weight route predicate: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: weight_high - uri: https://weighthigh.org - predicates: - - Weight=group1, 8 - - id: weight_low - uri: https://weightlow.org - predicates: - - Weight=group1, 2 ----- -==== - -This route would forward ~80% of traffic to https://weighthigh.org and ~20% of traffic to https://weighlow.org - -=== The XForwarded Remote Addr Route Predicate Factory - -The `XForwarded Remote Addr` route predicate factory takes a list (min size 1) of `sources`, which are CIDR-notation (IPv4 or IPv6) strings, such as `192.168.0.1/16` (where `192.168.0.1` is an IP address and `16` is a subnet mask). - -This route predicate allows requests to be filtered based on the `X-Forwarded-For` HTTP header. - -This can be used with reverse proxies such as load balancers or web application firewalls where -the request should only be allowed if it comes from a trusted list of IP addresses used by those -reverse proxies. - - -The following example configures a XForwardedRemoteAddr route predicate: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: xforwarded_remoteaddr_route - uri: https://example.org - predicates: - - XForwardedRemoteAddr=192.168.1.1/24 ----- -==== - -This route matches if the `X-Forwarded-For` header contains, for example, `192.168.1.10`. - -== `GatewayFilter` Factories - -Route filters allow the modification of the incoming HTTP request or outgoing HTTP response in some manner. -Route filters are scoped to a particular route. -Spring Cloud Gateway includes many built-in GatewayFilter Factories. - -NOTE: For more detailed examples of how to use any of the following filters, take a look at the https://github.com/spring-cloud/spring-cloud-gateway/tree/master/spring-cloud-gateway-server/src/test/java/org/springframework/cloud/gateway/filter/factory[unit tests]. - -=== The `AddRequestHeader` `GatewayFilter` Factory - -The `AddRequestHeader` `GatewayFilter` factory takes a `name` and `value` parameter. -The following example configures an `AddRequestHeader` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: add_request_header_route - uri: https://example.org - filters: - - AddRequestHeader=X-Request-red, blue ----- -==== - -This listing adds `X-Request-red:blue` header to the downstream request's headers for all matching requests. - -`AddRequestHeader` is aware of the URI variables used to match a path or host. -URI variables may be used in the value and are expanded at runtime. -The following example configures an `AddRequestHeader` `GatewayFilter` that uses a variable: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: add_request_header_route - uri: https://example.org - predicates: - - Path=/red/{segment} - filters: - - AddRequestHeader=X-Request-Red, Blue-{segment} ----- -==== - -=== The `AddRequestHeadersIfNotPresent` `GatewayFilter` Factory - -The `AddRequestHeadersIfNotPresent` `GatewayFilter` factory takes a collection of `name` and `value` pairs separated by colon. -The following example configures an `AddRequestHeadersIfNotPresent` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: add_request_headers_route - uri: https://example.org - filters: - - AddRequestHeadersIfNotPresent=X-Request-Color-1:blue,X-Request-Color-2:green ----- -==== - -This listing adds 2 headers `X-Request-Color-1:blue` and `X-Request-Color-2:green` to the downstream request's headers for all matching requests. -This is similar to how `AddRequestHeader` works, but unlike `AddRequestHeader` it will do it only if the header is not already there. -Otherwise, the original value in the client request is sent. - -Additionally, to set a multi-valued header, use the header name multiple times like `AddRequestHeadersIfNotPresent=X-Request-Color-1:blue,X-Request-Color-1:green`. - -`AddRequestHeadersIfNotPresent` also supports URI variables used to match a path or host. -URI variables may be used in the value and are expanded at runtime. -The following example configures an `AddRequestHeadersIfNotPresent` `GatewayFilter` that uses a variable: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: add_request_header_route - uri: https://example.org - predicates: - - Path=/red/{segment} - filters: - - AddRequestHeadersIfNotPresent=X-Request-Red:Blue-{segment} ----- -==== - -=== The `AddRequestParameter` `GatewayFilter` Factory - -The `AddRequestParameter` `GatewayFilter` Factory takes a `name` and `value` parameter. -The following example configures an `AddRequestParameter` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: add_request_parameter_route - uri: https://example.org - filters: - - AddRequestParameter=red, blue ----- -==== - -This will add `red=blue` to the downstream request's query string for all matching requests. - -`AddRequestParameter` is aware of the URI variables used to match a path or host. -URI variables may be used in the value and are expanded at runtime. -The following example configures an `AddRequestParameter` `GatewayFilter` that uses a variable: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: add_request_parameter_route - uri: https://example.org - predicates: - - Host: {segment}.myhost.org - filters: - - AddRequestParameter=foo, bar-{segment} ----- -==== - -=== The `AddResponseHeader` `GatewayFilter` Factory - -The `AddResponseHeader` `GatewayFilter` Factory takes a `name` and `value` parameter. -The following example configures an `AddResponseHeader` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: add_response_header_route - uri: https://example.org - filters: - - AddResponseHeader=X-Response-Red, Blue ----- -==== - -This adds `X-Response-Red:Blue` header to the downstream response's headers for all matching requests. - -`AddResponseHeader` is aware of URI variables used to match a path or host. -URI variables may be used in the value and are expanded at runtime. -The following example configures an `AddResponseHeader` `GatewayFilter` that uses a variable: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: add_response_header_route - uri: https://example.org - predicates: - - Host: {segment}.myhost.org - filters: - - AddResponseHeader=foo, bar-{segment} ----- -==== - - -[[spring-cloud-circuitbreaker-filter-factory]] -=== The `CircuitBreaker` `GatewayFilter` Factory - -The Spring Cloud CircuitBreaker GatewayFilter factory uses the Spring Cloud CircuitBreaker APIs to wrap Gateway routes in -a circuit breaker. Spring Cloud CircuitBreaker supports multiple libraries that can be used with Spring Cloud Gateway. Spring Cloud supports Resilience4J out of the box. - -To enable the Spring Cloud CircuitBreaker filter, you need to place `spring-cloud-starter-circuitbreaker-reactor-resilience4j` on the classpath. -The following example configures a Spring Cloud CircuitBreaker `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: circuitbreaker_route - uri: https://example.org - filters: - - CircuitBreaker=myCircuitBreaker ----- -==== - -To configure the circuit breaker, see the configuration for the underlying circuit breaker implementation you are using. - -* https://cloud.spring.io/spring-cloud-circuitbreaker/reference/html/spring-cloud-circuitbreaker.html[Resilience4J Documentation] - -The Spring Cloud CircuitBreaker filter can also accept an optional `fallbackUri` parameter. -Currently, only `forward:` schemed URIs are supported. -If the fallback is called, the request is forwarded to the controller matched by the URI. -The following example configures such a fallback: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: circuitbreaker_route - uri: lb://backing-service:8088 - predicates: - - Path=/consumingServiceEndpoint - filters: - - name: CircuitBreaker - args: - name: myCircuitBreaker - fallbackUri: forward:/inCaseOfFailureUseThis - - RewritePath=/consumingServiceEndpoint, /backingServiceEndpoint ----- -==== - -The following listing does the same thing in Java: - -.Application.java -==== -[source,java] ----- -@Bean -public RouteLocator routes(RouteLocatorBuilder builder) { - return builder.routes() - .route("circuitbreaker_route", r -> r.path("/consumingServiceEndpoint") - .filters(f -> f.circuitBreaker(c -> c.name("myCircuitBreaker").fallbackUri("forward:/inCaseOfFailureUseThis")) - .rewritePath("/consumingServiceEndpoint", "/backingServiceEndpoint")).uri("lb://backing-service:8088") - .build(); -} ----- -==== - -This example forwards to the `/inCaseofFailureUseThis` URI when the circuit breaker fallback is called. -Note that this example also demonstrates the (optional) Spring Cloud LoadBalancer load-balancing (defined by the `lb` prefix on the destination URI). - -CircuitBreaker also supports URI variables in the `fallbackUri`. -This allows more complex routing options, like forwarding sections of the original host or url path using https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/util/pattern/PathPattern.html[PathPattern expression]. - -In the example below the call `consumingServiceEndpoint/users/1` will be redirected to `inCaseOfFailureUseThis/users/1`. - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: circuitbreaker_route - uri: lb://backing-service:8088 - predicates: - - Path=/consumingServiceEndpoint/{*segments} - filters: - - name: CircuitBreaker - args: - name: myCircuitBreaker - fallbackUri: forward:/inCaseOfFailureUseThis/{segments} ----- -==== - -The primary scenario is to use the `fallbackUri` to define an internal controller or handler within the gateway application. -However, you can also reroute the request to a controller or handler in an external application, as follows: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: ingredients - uri: lb://ingredients - predicates: - - Path=//ingredients/** - filters: - - name: CircuitBreaker - args: - name: fetchIngredients - fallbackUri: forward:/fallback - - id: ingredients-fallback - uri: http://localhost:9994 - predicates: - - Path=/fallback ----- -==== - -In this example, there is no `fallback` endpoint or handler in the gateway application. -However, there is one in another application, registered under `http://localhost:9994`. - -In case of the request being forwarded to fallback, the Spring Cloud CircuitBreaker Gateway filter also provides the `Throwable` that has caused it. -It is added to the `ServerWebExchange` as the `ServerWebExchangeUtils.CIRCUITBREAKER_EXECUTION_EXCEPTION_ATTR` attribute that can be used when handling the fallback within the gateway application. - -For the external controller/handler scenario, headers can be added with exception details. -You can find more information on doing so in the <>. - -[[circuit-breaker-status-codes]] -==== Tripping The Circuit Breaker On Status Codes - -In some cases you might want to trip a circuit breaker based on the status code -returned from the route it wraps. The circuit breaker config object takes a list of -status codes that if returned will cause the circuit breaker to be tripped. When setting the -status codes you want to trip the circuit breaker you can either use an integer with the status code -value or the String representation of the `HttpStatus` enumeration. - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: circuitbreaker_route - uri: lb://backing-service:8088 - predicates: - - Path=/consumingServiceEndpoint - filters: - - name: CircuitBreaker - args: - name: myCircuitBreaker - fallbackUri: forward:/inCaseOfFailureUseThis - statusCodes: - - 500 - - "NOT_FOUND" ----- -==== - -.Application.java -==== -[source,java] ----- -@Bean -public RouteLocator routes(RouteLocatorBuilder builder) { - return builder.routes() - .route("circuitbreaker_route", r -> r.path("/consumingServiceEndpoint") - .filters(f -> f.circuitBreaker(c -> c.name("myCircuitBreaker").fallbackUri("forward:/inCaseOfFailureUseThis").addStatusCode("INTERNAL_SERVER_ERROR")) - .rewritePath("/consumingServiceEndpoint", "/backingServiceEndpoint")).uri("lb://backing-service:8088") - .build(); -} ----- -==== - -=== The `CacheRequestBody` `GatewayFilter` Factory -Some situations necessitate reading the request body. Since the request can be read only once, we need to cache the request body. -You can use the `CacheRequestBody` filter to cache the request body before sending it downstream and getting the body from `exchange` attribute. - -The following listing shows how to cache the request body `GatewayFilter`: - -==== -[source,java] ----- -@Bean -public RouteLocator routes(RouteLocatorBuilder builder) { - return builder.routes() - .route("cache_request_body_route", r -> r.path("/downstream/**") - .filters(f -> f.prefixPath("/httpbin") - .cacheRequestBody(String.class).uri(uri)) - .build(); -} ----- -==== - - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: cache_request_body_route - uri: lb://downstream - predicates: - - Path=/downstream/** - filters: - - name: CacheRequestBody - args: - bodyClass: java.lang.String ----- -==== -`CacheRequestBody` extracts the request body and converts it to a body class (such as `java.lang.String`, defined in the preceding example). -`CacheRequestBody` then places it in the attributes available from `ServerWebExchange.getAttributes()`, with a key defined in `ServerWebExchangeUtils.CACHED_REQUEST_BODY_ATTR`. - -NOTE: This filter works only with HTTP (including HTTPS) requests. - -=== The `DedupeResponseHeader` `GatewayFilter` Factory - -The `DedupeResponseHeader` GatewayFilter factory takes a `name` parameter and an optional `strategy` parameter. `name` can contain a space-separated list of header names. -The following example configures a `DedupeResponseHeader` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: dedupe_response_header_route - uri: https://example.org - filters: - - DedupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin ----- -==== - -This removes duplicate values of `Access-Control-Allow-Credentials` and `Access-Control-Allow-Origin` response headers in cases when both the gateway CORS logic and the downstream logic add them. - -The `DedupeResponseHeader` filter also accepts an optional `strategy` parameter. -The accepted values are `RETAIN_FIRST` (default), `RETAIN_LAST`, and `RETAIN_UNIQUE`. - - -[[fallback-headers]] -=== The `FallbackHeaders` `GatewayFilter` Factory - -The `FallbackHeaders` factory lets you add Spring Cloud CircuitBreaker execution exception details in the headers of a request forwarded to a `fallbackUri` in an external application, as in the following scenario: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: ingredients - uri: lb://ingredients - predicates: - - Path=//ingredients/** - filters: - - name: CircuitBreaker - args: - name: fetchIngredients - fallbackUri: forward:/fallback - - id: ingredients-fallback - uri: http://localhost:9994 - predicates: - - Path=/fallback - filters: - - name: FallbackHeaders - args: - executionExceptionTypeHeaderName: Test-Header ----- -==== - -In this example, after an execution exception occurs while running the circuit breaker, the request is forwarded to the `fallback` endpoint or handler in an application running on `localhost:9994`. -The headers with the exception type, message and (if available) root cause exception type and message are added to that request by the `FallbackHeaders` filter. - -You can overwrite the names of the headers in the configuration by setting the values of the following arguments (shown with their default values): - -* `executionExceptionTypeHeaderName` (`"Execution-Exception-Type"`) -* `executionExceptionMessageHeaderName` (`"Execution-Exception-Message"`) -* `rootCauseExceptionTypeHeaderName` (`"Root-Cause-Exception-Type"`) -* `rootCauseExceptionMessageHeaderName` (`"Root-Cause-Exception-Message"`) - -For more information on circuit breakers and the gateway see the <>. - -=== The `JsonToGrpc` `GatewayFilter` Factory - -The JSONToGRPCFilter GatewayFilter Factory converts a JSON payload to a gRPC request. - -The filter takes the following arguments: - -* `protoDescriptor`: Proto descriptor file. - -This file can be generated using `protoc` and specifying the `--descriptor_set_out` flag: - -[source,bash] ----- -protoc --proto_path=src/main/resources/proto/ \ ---descriptor_set_out=src/main/resources/proto/hello.pb \ -src/main/resources/proto/hello.proto ----- - -* `protoFile`: Proto definition file. - -* `service`: Short name of the service that handles the request. - -* `method`: Method name in the service that handles the request. - -NOTE: `streaming` is not supported. - - -*application.yml.* - -[source,java] ----- -@Bean -public RouteLocator routes(RouteLocatorBuilder builder) { - return builder.routes() - .route("json-grpc", r -> r.path("/json/hello").filters(f -> { - String protoDescriptor = "file:src/main/proto/hello.pb"; - String protoFile = "file:src/main/proto/hello.proto"; - String service = "HelloService"; - String method = "hello"; - return f.jsonToGRPC(protoDescriptor, protoFile, service, method); - }).uri(uri)) ----- - -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: json-grpc - uri: https://localhost:6565/testhello - predicates: - - Path=/json/** - filters: - - name: JsonToGrpc - args: - protoDescriptor: file:proto/hello.pb - protoFile: file:proto/hello.proto - service: HelloService - method: hello - ----- - -When a request is made through the gateway to `/json/hello`, the request is transformed by using the definition provided in `hello.proto`, sent to `HelloService/hello`, and the response back is transformed to JSON. - -By default, it creates a `NettyChannel` by using the default `TrustManagerFactory`. However, you can customize this `TrustManager` by creating a bean of type `GrpcSslConfigurer`: - -[source,java] ----- - -@Configuration -public class GRPCLocalConfiguration { - @Bean - public GRPCSSLContext sslContext() { - TrustManager trustManager = trustAllCerts(); - return new GRPCSSLContext(trustManager); - } -} ----- - -[[local-cache-response-filter]] -=== The `LocalResponseCache` `GatewayFilter` Factory - -This filter allows caching the response body and headers to follow these rules: - -* It can only cache bodiless GET requests. -* It caches the response only for one of the following status codes: HTTP 200 (OK), HTTP 206 (Partial Content), or HTTP 301 (Moved Permanently). -* Response data is not cached if `Cache-Control` header does not allow it (`no-store` present in the request or `no-store` or `private` present in the response). -* If the response is already cached and a new request is performed with no-cache value in `Cache-Control` header, it returns a bodiless response with 304 (Not Modified). - -This filter configures the local response cache per route and is available only if the `spring.cloud.gateway.filter.local-response-cache.enabled` property is enabled. And a <> is also available as feature. - -It accepts the first parameter to override the time to expire a cache entry (expressed in `s` for seconds, `m` for minutes, and `h` for hours) and a second parameter to set the maximum size of the cache to evict entries for this route (`KB`, `MB`, or `GB`). - -The following listing shows how to add local response cache `GatewayFilter`: - -==== -[source,java] ----- -@Bean -public RouteLocator routes(RouteLocatorBuilder builder) { - return builder.routes() - .route("rewrite_response_upper", r -> r.host("*.rewriteresponseupper.org") - .filters(f -> f.prefixPath("/httpbin") - .localResponseCache(Duration.ofMinutes(30), "500MB") - ).uri(uri)) - .build(); -} ----- - -or this - -.application.yaml -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: resource - uri: http://localhost:9000 - predicates: - - Path=/resource - filters: - - LocalResponseCache=30m,500MB ----- -==== - -NOTE: This filter also automatically calculates the `max-age` value in the HTTP `Cache-Control` header. -Only if `max-age` is present on the original response is the value rewritten with the number of seconds set in the `timeToLive` configuration parameter. -In consecutive calls, this value is recalculated with the number of seconds left until the response expires. - -NOTE: To enable this feature, add `com.github.ben-manes.caffeine:caffeine` and `spring-boot-starter-cache` as project dependencies. - -WARNING: If your project creates custom `CacheManager` beans, it will either need to be marked with `@Primary` or injected using `@Qualifier`. - - -=== The `MapRequestHeader` `GatewayFilter` Factory - -The `MapRequestHeader` `GatewayFilter` factory takes `fromHeader` and `toHeader` parameters. -It creates a new named header (`toHeader`), and the value is extracted out of an existing named header (`fromHeader`) from the incoming http request. -If the input header does not exist, the filter has no impact. -If the new named header already exists, its values are augmented with the new values. -The following example configures a `MapRequestHeader`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: map_request_header_route - uri: https://example.org - filters: - - MapRequestHeader=Blue, X-Request-Red ----- -==== - -This adds the `X-Request-Red:` header to the downstream request with updated values from the incoming HTTP request's `Blue` header. - -=== The `ModifyRequestBody` `GatewayFilter` Factory - -You can use the `ModifyRequestBody` filter to modify the request body before it is sent downstream by the gateway. - -NOTE: This filter can be configured only by using the Java DSL. - -The following listing shows how to modify a request body `GatewayFilter`: - -==== -[source,java] ----- -@Bean -public RouteLocator routes(RouteLocatorBuilder builder) { - return builder.routes() - .route("rewrite_request_obj", r -> r.host("*.rewriterequestobj.org") - .filters(f -> f.prefixPath("/httpbin") - .modifyRequestBody(String.class, Hello.class, MediaType.APPLICATION_JSON_VALUE, - (exchange, s) -> Mono.just(new Hello(s.toUpperCase())))).uri(uri)) - .build(); -} - -static class Hello { - String message; - - public Hello() { } - - public Hello(String message) { - this.message = message; - } - - public String getMessage() { - return message; - } - - public void setMessage(String message) { - this.message = message; - } -} ----- - -NOTE: If the request has no body, the `RewriteFilter` is passed `null`. `Mono.empty()` should be returned to assign a missing body in the request. - -==== - - -=== The `ModifyResponseBody` `GatewayFilter` Factory - -You can use the `ModifyResponseBody` filter to modify the response body before it is sent back to the client. - -NOTE: This filter can be configured only by using the Java DSL. - -The following listing shows how to modify a response body `GatewayFilter`: - -==== -[source,java] ----- -@Bean -public RouteLocator routes(RouteLocatorBuilder builder) { - return builder.routes() - .route("rewrite_response_upper", r -> r.host("*.rewriteresponseupper.org") - .filters(f -> f.prefixPath("/httpbin") - .modifyResponseBody(String.class, String.class, - (exchange, s) -> Mono.just(s.toUpperCase()))).uri(uri)) - .build(); -} ----- - -NOTE: If the response has no body, the `RewriteFilter` is passed `null`. `Mono.empty()` should be returned to assign a missing body in the response. -==== - -=== The `PrefixPath` `GatewayFilter` Factory - -The `PrefixPath` `GatewayFilter` factory takes a single `prefix` parameter. -The following example configures a `PrefixPath` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: prefixpath_route - uri: https://example.org - filters: - - PrefixPath=/mypath ----- -==== - -This prefixes `/mypath` to the path of all matching requests. -So a request to `/hello` is sent to `/mypath/hello`. - -=== The `PreserveHostHeader` `GatewayFilter` Factory - -The `PreserveHostHeader` `GatewayFilter` factory has no parameters. -This filter sets a request attribute that the routing filter inspects to determine if the original host header should be sent rather than the host header determined by the HTTP client. -The following example configures a `PreserveHostHeader` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: preserve_host_route - uri: https://example.org - filters: - - PreserveHostHeader ----- -==== - -=== The `RedirectTo` `GatewayFilter` Factory - -The `RedirectTo` `GatewayFilter` factory takes two parameters, `status` and `url`. -The `status` parameter should be a 300 series redirect HTTP code, such as 301. -The `url` parameter should be a valid URL. -This is the value of the `Location` header. -For relative redirects, you should use `uri: no://op` as the uri of your route definition. -The following listing configures a `RedirectTo` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: prefixpath_route - uri: https://example.org - filters: - - RedirectTo=302, https://acme.org ----- -==== - -This will send a status 302 with a `Location:https://acme.org` header to perform a redirect. - - -=== `RemoveJsonAttributesResponseBody` `GatewayFilter` Factory - -The `RemoveJsonAttributesResponseBody` `GatewayFilter` factory takes a collection of `attribute names` to search for, an optional last parameter from the list can be a boolean to remove the attributes just at root level (that's the default value if not present at the end of the parameter configuration, `false`) or recursively (`true`). -It provides a convenient method to apply a transformation to JSON body content by deleting attributes from it. - -The following example configures an `RemoveJsonAttributesResponseBody` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: removejsonattributes_route - uri: https://example.org - filters: - - RemoveJsonAttributesResponseBody=id,color ----- -==== - -This removes attributes "id" and "color" from the JSON content body at root level. - -The following example configures an `RemoveJsonAttributesResponseBody` `GatewayFilter` that uses the optional last parameter: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: removejsonattributes_recursively_route - uri: https://example.org - predicates: - - Path=/red/{segment} - filters: - - RemoveJsonAttributesResponseBody=id,color,true ----- -==== - -This removes attributes "id" and "color" from the JSON content body at any level. - -=== The `RemoveRequestHeader` GatewayFilter Factory - -The `RemoveRequestHeader` `GatewayFilter` factory takes a `name` parameter. -It is the name of the header to be removed. -The following listing configures a `RemoveRequestHeader` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: removerequestheader_route - uri: https://example.org - filters: - - RemoveRequestHeader=X-Request-Foo ----- -==== - -This removes the `X-Request-Foo` header before it is sent downstream. - -=== The `RemoveRequestParameter` `GatewayFilter` Factory - -The `RemoveRequestParameter` `GatewayFilter` factory takes a `name` parameter. -It is the name of the query parameter to be removed. -The following example configures a `RemoveRequestParameter` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: removerequestparameter_route - uri: https://example.org - filters: - - RemoveRequestParameter=red ----- -==== - -This will remove the `red` parameter before it is sent downstream. - - -=== The `RemoveResponseHeader` `GatewayFilter` Factory - -The `RemoveResponseHeader` `GatewayFilter` factory takes a `name` parameter. -It is the name of the header to be removed. -The following listing configures a `RemoveResponseHeader` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: removeresponseheader_route - uri: https://example.org - filters: - - RemoveResponseHeader=X-Response-Foo ----- -==== - -This will remove the `X-Response-Foo` header from the response before it is returned to the gateway client. - -To remove any kind of sensitive header, you should configure this filter for any routes for which you may want to do so. -In addition, you can configure this filter once by using `spring.cloud.gateway.default-filters` and have it applied to all routes. - - -=== The `RequestHeaderSize` `GatewayFilter` Factory - -The `RequestHeaderSize` `GatewayFilter` factory takes `maxSize` and `errorHeaderName` parameters. -The `maxSize` parameter is the maximum data size allowed by the request header (including key and value). The `errorHeaderName` parameter sets the name of the response header containing an error message, by default it is "errorMessage". -The following listing configures a `RequestHeaderSize` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: requestheadersize_route - uri: https://example.org - filters: - - RequestHeaderSize=1000B ----- -==== - -This will send a status 431 if size of any request header is greater than 1000 Bytes. - -=== The `RequestRateLimiter` `GatewayFilter` Factory - -The `RequestRateLimiter` `GatewayFilter` factory uses a `RateLimiter` implementation to determine if the current request is allowed to proceed. If it is not, a status of `HTTP 429 - Too Many Requests` (by default) is returned. - -This filter takes an optional `keyResolver` parameter and parameters specific to the rate limiter (described <>). - -`keyResolver` is a bean that implements the `KeyResolver` interface. -In configuration, reference the bean by name using SpEL. -`#{@myKeyResolver}` is a SpEL expression that references a bean named `myKeyResolver`. -The following listing shows the `KeyResolver` interface: - -.KeyResolver.java -==== -[source,java] ----- -public interface KeyResolver { - Mono resolve(ServerWebExchange exchange); -} ----- -==== - -[[key-resolver-section]] -The `KeyResolver` interface lets pluggable strategies derive the key for limiting requests. -In future milestone releases, there will be some `KeyResolver` implementations. - -The default implementation of `KeyResolver` is the `PrincipalNameKeyResolver`, which retrieves the `Principal` from the `ServerWebExchange` and calls `Principal.getName()`. - -By default, if the `KeyResolver` does not find a key, requests are denied. -You can adjust this behavior by setting the `spring.cloud.gateway.filter.request-rate-limiter.deny-empty-key` (`true` or `false`) and `spring.cloud.gateway.filter.request-rate-limiter.empty-key-status-code` properties. - -[NOTE] -===== -The `RequestRateLimiter` is not configurable with the "shortcut" notation. The following example below is _invalid_: - -.application.properties -==== ----- -# INVALID SHORTCUT CONFIGURATION -spring.cloud.gateway.routes[0].filters[0]=RequestRateLimiter=2, 2, #{@userkeyresolver} ----- -==== -===== - -==== The Redis `RateLimiter` - -The Redis implementation is based on work done at https://stripe.com/blog/rate-limiters[Stripe]. -It requires the use of the `spring-boot-starter-data-redis-reactive` Spring Boot starter. - -The algorithm used is the https://en.wikipedia.org/wiki/Token_bucket[Token Bucket Algorithm]. - -The `redis-rate-limiter.replenishRate` property defines how many requests per second to allow (without any dropped requests). -This is the rate at which the token bucket is filled. - -The `redis-rate-limiter.burstCapacity` property is the maximum number of requests a user is allowed in a single second (without any dropped requests). -This is the number of tokens the token bucket can hold. -Setting this value to zero blocks all requests. - -The `redis-rate-limiter.requestedTokens` property is how many tokens a request costs. -This is the number of tokens taken from the bucket for each request and defaults to `1`. - -A steady rate is accomplished by setting the same value in `replenishRate` and `burstCapacity`. -Temporary bursts can be allowed by setting `burstCapacity` higher than `replenishRate`. -In this case, the rate limiter needs to be allowed some time between bursts (according to `replenishRate`), as two consecutive bursts results in dropped requests (`HTTP 429 - Too Many Requests`). -The following listing configures a `redis-rate-limiter`: - -Rate limits below `1 request/s` are accomplished by setting `replenishRate` to the wanted number of requests, `requestedTokens` to the timespan in seconds, and `burstCapacity` to the product of `replenishRate` and `requestedTokens`. -For example, setting `replenishRate=1`, `requestedTokens=60`, and `burstCapacity=60` results in a limit of `1 request/min`. -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: requestratelimiter_route - uri: https://example.org - filters: - - name: RequestRateLimiter - args: - redis-rate-limiter.replenishRate: 10 - redis-rate-limiter.burstCapacity: 20 - redis-rate-limiter.requestedTokens: 1 - ----- -==== - -The following example configures a `KeyResolver` in Java: - -.Config.java -==== -[source,java] ----- -@Bean -KeyResolver userKeyResolver() { - return exchange -> Mono.just(exchange.getRequest().getQueryParams().getFirst("user")); -} ----- -==== - -This defines a request rate limit of 10 per user. A burst of 20 is allowed, but, in the next second, only 10 requests are available. -The `KeyResolver` is a simple one that gets the `user` request parameter -NOTE: This is not recommended for production - -You can also define a rate limiter as a bean that implements the `RateLimiter` interface. -In configuration, you can reference the bean by name using SpEL. -`#{@myRateLimiter}` is a SpEL expression that references a bean with named `myRateLimiter`. -The following listing defines a rate limiter that uses the `KeyResolver` defined in the previous listing: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: requestratelimiter_route - uri: https://example.org - filters: - - name: RequestRateLimiter - args: - rate-limiter: "#{@myRateLimiter}" - key-resolver: "#{@userKeyResolver}" - ----- -==== - -=== The `RewriteLocationResponseHeader` `GatewayFilter` Factory - -The `RewriteLocationResponseHeader` `GatewayFilter` factory modifies the value of the `Location` response header, usually to get rid of backend-specific details. -It takes the `stripVersionMode`, `locationHeaderName`, `hostValue`, and `protocolsRegex` parameters. -The following listing configures a `RewriteLocationResponseHeader` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: rewritelocationresponseheader_route - uri: http://example.org - filters: - - RewriteLocationResponseHeader=AS_IN_REQUEST, Location, , ----- -==== - -For example, for a request of `POST https://api.example.com/some/object/name`, the `Location` response header value of `https://object-service.prod.example.net/v2/some/object/id` is rewritten as `https://api.example.com/some/object/id`. - -The `stripVersionMode` parameter has the following possible values: `NEVER_STRIP`, `AS_IN_REQUEST` (default), and `ALWAYS_STRIP`. - -* `NEVER_STRIP`: The version is not stripped, even if the original request path contains no version. -* `AS_IN_REQUEST`: The version is stripped only if the original request path contains no version. -* `ALWAYS_STRIP`: The version is always stripped, even if the original request path contains version. - -The `hostValue` parameter, if provided, is used to replace the `host:port` portion of the response `Location` header. -If it is not provided, the value of the `Host` request header is used. - -The `protocolsRegex` parameter must be a valid regex `String`, against which the protocol name is matched. -If it is not matched, the filter does nothing. -The default is `http|https|ftp|ftps`. - -=== The `RewritePath` `GatewayFilter` Factory - -The `RewritePath` `GatewayFilter` factory takes a path `regexp` parameter and a `replacement` parameter. -This uses Java regular expressions for a flexible way to rewrite the request path. -The following listing configures a `RewritePath` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: rewritepath_route - uri: https://example.org - predicates: - - Path=/red/** - filters: - - RewritePath=/red/?(?.*), /$\{segment} ----- -==== - -For a request path of `/red/blue`, this sets the path to `/blue` before making the downstream request. Note that the `$` should be replaced with `$\` because of the YAML specification. - -=== The `RewriteResponseHeader` `GatewayFilter` Factory - -The `RewriteResponseHeader` `GatewayFilter` factory takes `name`, `regexp`, and `replacement` parameters. -It uses Java regular expressions for a flexible way to rewrite the response header value. -The following example configures a `RewriteResponseHeader` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: rewriteresponseheader_route - uri: https://example.org - filters: - - RewriteResponseHeader=X-Response-Red, , password=[^&]+, password=*** ----- -==== - -For a header value of `/42?user=ford&password=omg!what&flag=true`, it is set to `/42?user=ford&password=\***&flag=true` after making the downstream request. -You must use `$\` to mean `$` because of the YAML specification. - -=== The `SaveSession` `GatewayFilter` Factory - -The `SaveSession` `GatewayFilter` factory forces a `WebSession::save` operation _before_ forwarding the call downstream. -This is of particular use when using something like https://projects.spring.io/spring-session/[Spring Session] with a lazy data store, and you need to ensure the session state has been saved before making the forwarded call. -The following example configures a `SaveSession` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: save_session - uri: https://example.org - predicates: - - Path=/foo/** - filters: - - SaveSession ----- -==== - -If you integrate https://projects.spring.io/spring-security/[Spring Security] with Spring Session and want to ensure security details have been forwarded to the remote process, this is critical. - -=== The `SecureHeaders` `GatewayFilter` Factory - -The `SecureHeaders` `GatewayFilter` factory adds a number of headers to the response, per the recommendation made in https://blog.appcanary.com/2017/http-security-headers.html[this blog post]. - -The following headers (shown with their default values) are added: - -* `X-Xss-Protection:1 (mode=block`) -* `Strict-Transport-Security (max-age=631138519`) -* `X-Frame-Options (DENY)` -* `X-Content-Type-Options (nosniff)` -* `Referrer-Policy (no-referrer)` -* `Content-Security-Policy (default-src 'self' https:; font-src 'self' https: data:; img-src 'self' https: data:; object-src 'none'; script-src https:; style-src 'self' https: 'unsafe-inline)'` -* `X-Download-Options (noopen)` -* `X-Permitted-Cross-Domain-Policies (none)` - -To change the default values, set the appropriate property in the `spring.cloud.gateway.filter.secure-headers` namespace. -The following properties are available: - -* `xss-protection-header` -* `strict-transport-security` -* `frame-options` -* `content-type-options` -* `referrer-policy` -* `content-security-policy` -* `download-options` -* `permitted-cross-domain-policies` - -To disable the default values set the `spring.cloud.gateway.filter.secure-headers.disable` property with comma-separated values. -The following example shows how to do so: - -==== -[source] ----- -spring.cloud.gateway.filter.secure-headers.disable=x-frame-options,strict-transport-security ----- -==== - -NOTE: The lowercase full name of the secure header needs to be used to disable it.. - -=== The `SetPath` `GatewayFilter` Factory - -The `SetPath` `GatewayFilter` factory takes a path `template` parameter. -It offers a simple way to manipulate the request path by allowing templated segments of the path. -This uses the URI templates from Spring Framework. -Multiple matching segments are allowed. -The following example configures a `SetPath` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: setpath_route - uri: https://example.org - predicates: - - Path=/red/{segment} - filters: - - SetPath=/{segment} ----- -==== - -For a request path of `/red/blue`, this sets the path to `/blue` before making the downstream request. - -=== The `SetRequestHeader` `GatewayFilter` Factory - -The `SetRequestHeader` `GatewayFilter` factory takes `name` and `value` parameters. -The following listing configures a `SetRequestHeader` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: setrequestheader_route - uri: https://example.org - filters: - - SetRequestHeader=X-Request-Red, Blue ----- -==== - -This `GatewayFilter` replaces (rather than adding) all headers with the given name. -So, if the downstream server responded with `X-Request-Red:1234`, it will be replaced with `X-Request-Red:Blue`, which is what the downstream service would receive. - -`SetRequestHeader` is aware of URI variables used to match a path or host. -URI variables may be used in the value and are expanded at runtime. -The following example configures an `SetRequestHeader` `GatewayFilter` that uses a variable: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: setrequestheader_route - uri: https://example.org - predicates: - - Host: {segment}.myhost.org - filters: - - SetRequestHeader=foo, bar-{segment} ----- -==== - -=== The `SetResponseHeader` `GatewayFilter` Factory - -The `SetResponseHeader` `GatewayFilter` factory takes `name` and `value` parameters. -The following listing configures a `SetResponseHeader` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: setresponseheader_route - uri: https://example.org - filters: - - SetResponseHeader=X-Response-Red, Blue ----- -==== - -This GatewayFilter replaces (rather than adding) all headers with the given name. -So, if the downstream server responded with `X-Response-Red:1234`, it will be replaced with `X-Response-Red:Blue`, which is what the gateway client would receive. - -`SetResponseHeader` is aware of URI variables used to match a path or host. -URI variables may be used in the value and will be expanded at runtime. -The following example configures an `SetResponseHeader` `GatewayFilter` that uses a variable: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: setresponseheader_route - uri: https://example.org - predicates: - - Host: {segment}.myhost.org - filters: - - SetResponseHeader=foo, bar-{segment} ----- -==== - -=== The `SetStatus` `GatewayFilter` Factory - -The `SetStatus` `GatewayFilter` factory takes a single parameter, `status`. -It must be a valid Spring `HttpStatus`. -It may be the integer value `404` or the string representation of the enumeration: `NOT_FOUND`. -The following listing configures a `SetStatus` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: setstatusstring_route - uri: https://example.org - filters: - - SetStatus=UNAUTHORIZED - - id: setstatusint_route - uri: https://example.org - filters: - - SetStatus=401 ----- -==== - -In either case, the HTTP status of the response is set to 401. - -You can configure the `SetStatus` `GatewayFilter` to return the original HTTP status code from the proxied request in a header in the response. -The header is added to the response if configured with the following property: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - set-status: - original-status-header-name: original-http-status ----- -==== - -=== The `StripPrefix` `GatewayFilter` Factory - -The `StripPrefix` `GatewayFilter` factory takes one parameter, `parts`. -The `parts` parameter indicates the number of parts in the path to strip from the request before sending it downstream. -The following listing configures a `StripPrefix` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: nameRoot - uri: https://nameservice - predicates: - - Path=/name/** - filters: - - StripPrefix=2 ----- -==== - -When a request is made through the gateway to `/name/blue/red`, the request made to `nameservice` looks like `https://nameservice/red`. - -=== The `Retry` `GatewayFilter` Factory - -The `Retry` `GatewayFilter` factory supports the following parameters: - -* `retries`: The number of retries that should be attempted. -* `statuses`: The HTTP status codes that should be retried, represented by using `org.springframework.http.HttpStatus`. -* `methods`: The HTTP methods that should be retried, represented by using `org.springframework.http.HttpMethod`. -* `series`: The series of status codes to be retried, represented by using `org.springframework.http.HttpStatus.Series`. -* `exceptions`: A list of thrown exceptions that should be retried. -* `backoff`: The configured exponential backoff for the retries. -Retries are performed after a backoff interval of `firstBackoff * (factor ^ n)`, where `n` is the iteration. -If `maxBackoff` is configured, the maximum backoff applied is limited to `maxBackoff`. -If `basedOnPreviousValue` is true, the backoff is calculated by using `prevBackoff * factor`. - -The following defaults are configured for `Retry` filter, if enabled: - -* `retries`: Three times -* `series`: 5XX series -* `methods`: GET method -* `exceptions`: `IOException` and `TimeoutException` -* `backoff`: disabled - -The following listing configures a Retry `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: retry_test - uri: http://localhost:8080/flakey - predicates: - - Host=*.retry.com - filters: - - name: Retry - args: - retries: 3 - statuses: BAD_GATEWAY - methods: GET,POST - backoff: - firstBackoff: 10ms - maxBackoff: 50ms - factor: 2 - basedOnPreviousValue: false ----- -==== - -NOTE: When using the retry filter with a `forward:` prefixed URL, the target endpoint should be written carefully so that, in case of an error, it does not do anything that could result in a response being sent to the client and committed. -For example, if the target endpoint is an annotated controller, the target controller method should not return `ResponseEntity` with an error status code. -Instead, it should throw an `Exception` or signal an error (for example, through a `Mono.error(ex)` return value), which the retry filter can be configured to handle by retrying. - -WARNING: When using the retry filter with any HTTP method with a body, the body will be cached and the gateway will become memory constrained. The body is cached in a request attribute defined by `ServerWebExchangeUtils.CACHED_REQUEST_BODY_ATTR`. The type of the object is `org.springframework.core.io.buffer.DataBuffer`. - -A simplified "shortcut" notation can be added with a single `status` and `method`. - -The following two examples are equivalent: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: retry_route - uri: https://example.org - filters: - - name: Retry - args: - retries: 3 - statuses: INTERNAL_SERVER_ERROR - methods: GET - backoff: - firstBackoff: 10ms - maxBackoff: 50ms - factor: 2 - basedOnPreviousValue: false - - - id: retryshortcut_route - uri: https://example.org - filters: - - Retry=3,INTERNAL_SERVER_ERROR,GET,10ms,50ms,2,false ----- -==== - -=== The `RequestSize` `GatewayFilter` Factory - -When the request size is greater than the permissible limit, the `RequestSize` `GatewayFilter` factory can restrict a request from reaching the downstream service. -The filter takes a `maxSize` parameter. -The `maxSize` is a `DataSize` type, so values can be defined as a number followed by an optional `DataUnit` suffix such as 'KB' or 'MB'. The default is 'B' for bytes. -It is the permissible size limit of the request defined in bytes. -The following listing configures a `RequestSize` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: request_size_route - uri: http://localhost:8080/upload - predicates: - - Path=/upload - filters: - - name: RequestSize - args: - maxSize: 5000000 ----- -==== - -The `RequestSize` `GatewayFilter` factory sets the response status as `413 Payload Too Large` with an additional header `errorMessage` when the request is rejected due to size. The following example shows such an `errorMessage`: - -==== -[source] ----- -errorMessage : Request size is larger than permissible limit. Request size is 6.0 MB where permissible limit is 5.0 MB ----- -==== - -NOTE: The default request size is set to five MB if not provided as a filter argument in the route definition. - -=== The `SetRequestHostHeader` `GatewayFilter` Factory - -There are certain situation when the host header may need to be overridden. In this situation, the `SetRequestHostHeader` `GatewayFilter` factory can replace the existing host header with a specified value. -The filter takes a `host` parameter. -The following listing configures a `SetRequestHostHeader` `GatewayFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: set_request_host_header_route - uri: http://localhost:8080/headers - predicates: - - Path=/headers - filters: - - name: SetRequestHostHeader - args: - host: example.org ----- -==== - -The `SetRequestHostHeader` `GatewayFilter` factory replaces the value of the host header with `example.org`. - - -=== The `TokenRelay` `GatewayFilter` Factory - -A Token Relay is where an OAuth2 consumer acts as a Client and -forwards the incoming token to outgoing resource requests. The -consumer can be a pure Client (like an SSO application) or a Resource -Server. - -Spring Cloud Gateway can forward OAuth2 access tokens downstream to the services -it is proxying using the `TokenRelay` `GatewayFilter`. - -The `TokenRelay` `GatewayFilter` takes one optional parameter, `clientRegistrationId`. -The following example configures a `TokenRelay` `GatewayFilter`: - -.App.java -[source,java] ----- - -@Bean -public RouteLocator customRouteLocator(RouteLocatorBuilder builder) { - return builder.routes() - .route("resource", r -> r.path("/resource") - .filters(f -> f.tokenRelay("myregistrationid")) - .uri("http://localhost:9000")) - .build(); -} ----- - -or this - -.application.yaml -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: resource - uri: http://localhost:9000 - predicates: - - Path=/resource - filters: - - TokenRelay=myregistrationid ----- - -The example above specifies a `clientRegistrationId`, which can be used to obtain and forward an OAuth2 access token for any available `ClientRegistration`. - -Spring Cloud Gateway can also forward the OAuth2 access token of the currently authenticated user `oauth2Login()` is used to authenticate the user. -To add this functionality to the gateway, you can omit the `clientRegistrationId` parameter like this: - -.App.java -[source,java] ----- - -@Bean -public RouteLocator customRouteLocator(RouteLocatorBuilder builder) { - return builder.routes() - .route("resource", r -> r.path("/resource") - .filters(f -> f.tokenRelay()) - .uri("http://localhost:9000")) - .build(); -} ----- - -or this - -.application.yaml -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: resource - uri: http://localhost:9000 - predicates: - - Path=/resource - filters: - - TokenRelay= ----- - -and it will (in addition to logging the user in and grabbing a token) -pass the authentication token downstream to the services (in this case -`/resource`). - -To enable this for Spring Cloud Gateway add the following dependencies - -- `org.springframework.boot:spring-boot-starter-oauth2-client` - -How does it work? The {github-code}/src/main/java/org/springframework/cloud/gateway/security/TokenRelayGatewayFilterFactory.java[filter] -extracts an OAuth2 access token from the currently authenticated user for the provided `clientRegistrationId`. -If no `clientRegistrationId` is provided, the currently authenticated user's own access token (obtained during login) is used. -In either case, the extracted access token is placed in a request header for the downstream requests. - -For a full working sample see https://github.com/spring-cloud-samples/sample-gateway-oauth2login[this project]. - -NOTE: A `TokenRelayGatewayFilterFactory` bean will only be created if the proper `spring.security.oauth2.client.*` properties are set which will trigger creation of a `ReactiveClientRegistrationRepository` bean. - -NOTE: The default implementation of `ReactiveOAuth2AuthorizedClientService` used by `TokenRelayGatewayFilterFactory` -uses an in-memory data store. You will need to provide your own implementation `ReactiveOAuth2AuthorizedClientService` -if you need a more robust solution. - - -=== Default Filters - -To add a filter and apply it to all routes, you can use `spring.cloud.gateway.default-filters`. -This property takes a list of filters. -The following listing defines a set of default filters: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - default-filters: - - AddResponseHeader=X-Response-Default-Red, Default-Blue - - PrefixPath=/httpbin ----- -==== - -== Global Filters - -The `GlobalFilter` interface has the same signature as `GatewayFilter`. -These are special filters that are conditionally applied to all routes. - -NOTE: This interface and its usage are subject to change in future milestone releases. - -[[gateway-combined-global-filter-and-gatewayfilter-ordering]] -=== Combined Global Filter and `GatewayFilter` Ordering - -When a request matches a route, the filtering web handler adds all instances of `GlobalFilter` and all route-specific instances of `GatewayFilter` to a filter chain. -This combined filter chain is sorted by the `org.springframework.core.Ordered` interface, which you can set by implementing the `getOrder()` method. - -As Spring Cloud Gateway distinguishes between "`pre`" and "`post`" phases for filter logic execution (see <>), the filter with the highest precedence is the first in the "`pre`"-phase and the last in the "`post`"-phase. - -The following listing configures a filter chain: - -.ExampleConfiguration.java -==== -[source,java] ----- -@Bean -public GlobalFilter customFilter() { - return new CustomGlobalFilter(); -} - -public class CustomGlobalFilter implements GlobalFilter, Ordered { - - @Override - public Mono filter(ServerWebExchange exchange, GatewayFilterChain chain) { - log.info("custom global filter"); - return chain.filter(exchange); - } - - @Override - public int getOrder() { - return -1; - } -} ----- -==== - -=== The Gateway Metrics Filter - -To enable gateway metrics, add `spring-boot-starter-actuator` as a project dependency. Then, by default, the gateway metrics filter runs as long as the `spring.cloud.gateway.metrics.enabled` property is not set to `false`. -This filter adds a timer metric named `spring.cloud.gateway.requests` with the following tags: - -* `routeId`: The route ID. -* `routeUri`: The URI to which the API is routed. -* `outcome`: The outcome, as classified by link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/HttpStatus.Series.html[HttpStatus.Series]. -* `status`: The HTTP status of the request returned to the client. -* `httpStatusCode`: The HTTP Status of the request returned to the client. -* `httpMethod`: The HTTP method used for the request. - -In addition, through the `spring.cloud.gateway.metrics.tags.path.enabled` property (by default, `false`), you can activate an extra metric with the path tag: - -* `path`: The path of the request. - -These metrics are then available to be scraped from `/actuator/metrics/spring.cloud.gateway.requests` and can be easily integrated with Prometheus to create a link:images/gateway-grafana-dashboard.jpeg[Grafana] link:gateway-grafana-dashboard.json[dashboard]. - -NOTE: To enable the prometheus endpoint, add `micrometer-registry-prometheus` as a project dependency. - -[[local-cache-response-global-filter]] -=== The Local Response Cache Filter - -The `LocalResponseCache` runs if associated properties are enabled: - -* `spring.cloud.gateway.global-filter.local-response-cache.enabled`: Activates the global cache for all routes -* `spring.cloud.gateway.filter.local-response-cache.enabled`: Activates the associated filter to use at route level - -This feature enables a local cache using Caffeine for all responses that meet the following criteria: - -* The request is a bodiless GET. -* The response has one of the following status codes: HTTP 200 (OK), HTTP 206 (Partial Content), or HTTP 301 (Moved Permanently). -* The HTTP `Cache-Control` header allows caching (that means it does not have any of the following values: `no-store` present in the request and `no-store` or `private` present in the response). - -It accepts two configuration parameters: - -* `spring.cloud.gateway.filter.local-response-cache.size`: Sets the maximum size of the cache to evict entries for this route (in KB, MB and GB). -* `spring.cloud.gateway.filter.local-response-cache.time-to-live` Sets the time to expire a cache entry (expressed in s for seconds, m for minutes, and h for hours). - -If none of these parameters are configured but the global filter is enabled, by default, it configures 5 minutes of time to live for the cached response. - -This filter also implements the automatic calculation of the `max-age` value in the HTTP `Cache-Control` header. -If `max-age` is present on the original response, the value is rewritten with the number of seconds set in the `timeToLive` configuration parameter. -In subsequent calls, this value is recalculated with the number of seconds left until the response expires. - -Setting `spring.cloud.gateway.global-filter.local-response-cache.enabled` to `false` deactivate the local response cache for all routes, the <> allows to use this functionality at route level. - -NOTE: To enable this feature, add `com.github.ben-manes.caffeine:caffeine` and `spring-boot-starter-cache` as project dependencies. - -WARNING: If your project creates custom `CacheManager` beans, it will either need to be marked with `@Primary` or injected using `@Qualifier`. - -=== Forward Routing Filter - -The `ForwardRoutingFilter` looks for a URI in the exchange attribute `ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR`. -If the URL has a `forward` scheme (such as `forward:///localendpoint`), it uses the Spring `DispatcherHandler` to handle the request. -The path part of the request URL is overridden with the path in the forward URL. -The unmodified original URL is appended to the list in the `ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR` attribute. - -=== The Netty Routing Filter - -The Netty routing filter runs if the URL located in the `ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR` exchange attribute has a `http` or `https` scheme. -It uses the Netty `HttpClient` to make the downstream proxy request. -The response is put in the `ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR` exchange attribute for use in a later filter. -(There is also an experimental `WebClientHttpRoutingFilter` that performs the same function but does not require Netty.) - -=== The Netty Write Response Filter - -The `NettyWriteResponseFilter` runs if there is a Netty `HttpClientResponse` in the `ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR` exchange attribute. -It runs after all other filters have completed and writes the proxy response back to the gateway client response. -(There is also an experimental `WebClientWriteResponseFilter` that performs the same function but does not require Netty.) - -[[reactive-loadbalancer-client-filter]] -=== The `ReactiveLoadBalancerClientFilter` - -The `ReactiveLoadBalancerClientFilter` looks for a URI in the exchange attribute named `ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR`. -If the URL has a `lb` scheme (such as `lb://myservice`), it uses the Spring Cloud `ReactorLoadBalancer` to resolve the name (`myservice` in this example) to an actual host and port and replaces the URI in the same attribute. -The unmodified original URL is appended to the list in the `ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR` attribute. -The filter also looks in the `ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR` attribute to see if it equals `lb`. -If so, the same rules apply. -The following listing configures a `ReactiveLoadBalancerClientFilter`: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: myRoute - uri: lb://service - predicates: - - Path=/service/** ----- -==== - -NOTE: By default, when a service instance cannot be found by the `ReactorLoadBalancer`, a `503` is returned. -You can configure the gateway to return a `404` by setting `spring.cloud.gateway.loadbalancer.use404=true`. - -NOTE: The `isSecure` value of the `ServiceInstance` returned from the `ReactiveLoadBalancerClientFilter` overrides -the scheme specified in the request made to the Gateway. -For example, if the request comes into the Gateway over `HTTPS` but the `ServiceInstance` indicates it is not secure, the downstream request is made over `HTTP`. -The opposite situation can also apply. -However, if `GATEWAY_SCHEME_PREFIX_ATTR` is specified for the route in the Gateway configuration, the prefix is stripped and the resulting scheme from the route URL overrides the `ServiceInstance` configuration. - -TIP: Gateway supports all the LoadBalancer features. You can read more about them in the https://docs.spring.io/spring-cloud-commons/docs/current/reference/html/#spring-cloud-loadbalancer[Spring Cloud Commons documentation]. - -=== The `RouteToRequestUrl` Filter - -If there is a `Route` object in the `ServerWebExchangeUtils.GATEWAY_ROUTE_ATTR` exchange attribute, the `RouteToRequestUrlFilter` runs. -It creates a new URI, based off of the request URI but updated with the URI attribute of the `Route` object. -The new URI is placed in the `ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR` exchange attribute. - -If the URI has a scheme prefix, such as `lb:ws://serviceid`, the `lb` scheme is stripped from the URI and placed in the `ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR` for use later in the filter chain. - -=== The Websocket Routing Filter - -If the URL located in the `ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR` exchange attribute has a `ws` or `wss` scheme, the websocket routing filter runs. It uses the Spring WebSocket infrastructure to forward the websocket request downstream. - -You can load-balance websockets by prefixing the URI with `lb`, such as `lb:ws://serviceid`. - -NOTE: If you use https://github.com/sockjs[SockJS] as a fallback over normal HTTP, you should configure a normal HTTP route as well as the websocket Route. - -The following listing configures a websocket routing filter: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - # SockJS route - - id: websocket_sockjs_route - uri: http://localhost:3001 - predicates: - - Path=/websocket/info/** - # Normal Websocket route - - id: websocket_route - uri: ws://localhost:3001 - predicates: - - Path=/websocket/** ----- -==== - -=== Marking An Exchange As Routed - -After the gateway has routed a `ServerWebExchange`, it marks that exchange as "`routed`" by adding `gatewayAlreadyRouted` -to the exchange attributes. Once a request has been marked as routed, other routing filters will not route the request again, -essentially skipping the filter. There are convenience methods that you can use to mark an exchange as routed -or check if an exchange has already been routed. - -* `ServerWebExchangeUtils.isAlreadyRouted` takes a `ServerWebExchange` object and checks if it has been "`routed`". -* `ServerWebExchangeUtils.setAlreadyRouted` takes a `ServerWebExchange` object and marks it as "`routed`". - -== HttpHeadersFilters - -`HttpHeadersFilters` are applied to the requests before sending them downstream, such as in the `NettyRoutingFilter`. - -=== Forwarded Headers Filter -The `Forwarded` Headers Filter creates a `Forwarded` header to send to the downstream service. It adds the `Host` header, scheme and port of the current request to any existing `Forwarded` header. - -=== RemoveHopByHop Headers Filter -The `RemoveHopByHop` Headers Filter removes headers from forwarded requests. The default list of headers that is removed comes from the https://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-14#section-7.1.3[IETF]. - -.The default removed headers are: -* Connection -* Keep-Alive -* Proxy-Authenticate -* Proxy-Authorization -* TE -* Trailer -* Transfer-Encoding -* Upgrade - -To change this, set the `spring.cloud.gateway.filter.remove-hop-by-hop.headers` property to the list of header names to remove. - -=== XForwarded Headers Filter -The `XForwarded` Headers Filter creates various `X-Forwarded-*` headers to send to the downstream service. It uses the `Host` header, scheme, port and path of the current request to create the various headers. - -Creating of individual headers can be controlled by the following boolean properties (defaults to true): - -- `spring.cloud.gateway.x-forwarded.for-enabled` -- `spring.cloud.gateway.x-forwarded.host-enabled` -- `spring.cloud.gateway.x-forwarded.port-enabled` -- `spring.cloud.gateway.x-forwarded.proto-enabled` -- `spring.cloud.gateway.x-forwarded.prefix-enabled` - -Appending multiple headers can be controlled by the following boolean properties (defaults to true): - -- `spring.cloud.gateway.x-forwarded.for-append` -- `spring.cloud.gateway.x-forwarded.host-append` -- `spring.cloud.gateway.x-forwarded.port-append` -- `spring.cloud.gateway.x-forwarded.proto-append` -- `spring.cloud.gateway.x-forwarded.prefix-append` - -== TLS and SSL - -The gateway can listen for requests on HTTPS by following the usual Spring server configuration. -The following example shows how to do so: - -.application.yml -==== -[source,yaml] ----- -server: - ssl: - enabled: true - key-alias: scg - key-store-password: scg1234 - key-store: classpath:scg-keystore.p12 - key-store-type: PKCS12 ----- -==== - -You can route gateway routes to both HTTP and HTTPS backends. -If you are routing to an HTTPS backend, you can configure the gateway to trust all downstream certificates with the following configuration: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - httpclient: - ssl: - useInsecureTrustManager: true ----- -==== - -Using an insecure trust manager is not suitable for production. -For a production deployment, you can configure the gateway with a set of known certificates that it can trust with the following configuration: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - httpclient: - ssl: - trustedX509Certificates: - - cert1.pem - - cert2.pem ----- -==== - -If the Spring Cloud Gateway is not provisioned with trusted certificates, the default trust store is used (which you can override by setting the `javax.net.ssl.trustStore` system property). - -=== TLS Handshake - -The gateway maintains a client pool that it uses to route to backends. -When communicating over HTTPS, the client initiates a TLS handshake. -A number of timeouts are associated with this handshake. -You can configure these timeouts can be configured (defaults shown) as follows: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - httpclient: - ssl: - handshake-timeout-millis: 10000 - close-notify-flush-timeout-millis: 3000 - close-notify-read-timeout-millis: 0 ----- -==== - -== Configuration - -Configuration for Spring Cloud Gateway is driven by a collection of `RouteDefinitionLocator` instances. -The following listing shows the definition of the `RouteDefinitionLocator` interface: - -.RouteDefinitionLocator.java -==== -[source,java] ----- -public interface RouteDefinitionLocator { - Flux getRouteDefinitions(); -} ----- -==== - -By default, a `PropertiesRouteDefinitionLocator` loads properties by using Spring Boot's `@ConfigurationProperties` mechanism. - -The earlier configuration examples all use a shortcut notation that uses positional arguments rather than named ones. -The following two examples are equivalent: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: setstatus_route - uri: https://example.org - filters: - - name: SetStatus - args: - status: 401 - - id: setstatusshortcut_route - uri: https://example.org - filters: - - SetStatus=401 ----- -==== - -For some usages of the gateway, properties are adequate, but some production use cases benefit from loading configuration from an external source, such as a database. Future milestone versions will have `RouteDefinitionLocator` implementations based off of Spring Data Repositories, such as Redis, MongoDB, and Cassandra. - -=== RouteDefinition Metrics - -To enable `RouteDefinition` metrics, add spring-boot-starter-actuator as a project dependency. Then, by default, the metrics will be available as long as the property `spring.cloud.gateway.metrics.enabled` is set to `true`. A gauge metric named `spring.cloud.gateway.routes.count` will be added, whose value is the number of `RouteDefinitions`. This metric will be available from `/actuator/metrics/spring.cloud.gateway.routes.count`. - -== Route Metadata Configuration - -You can configure additional parameters for each route by using metadata, as follows: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: route_with_metadata - uri: https://example.org - metadata: - optionName: "OptionValue" - compositeObject: - name: "value" - iAmNumber: 1 ----- -==== - -You could acquire all metadata properties from an exchange, as follows: - -==== -[source] ----- -Route route = exchange.getAttribute(GATEWAY_ROUTE_ATTR); -// get all metadata properties -route.getMetadata(); -// get a single metadata property -route.getMetadata(someKey); ----- -==== - -== Http timeouts configuration - -Http timeouts (response and connect) can be configured for all routes and overridden for each specific route. - -=== Global timeouts -To configure Global http timeouts: + -`connect-timeout` must be specified in milliseconds. + -`response-timeout` must be specified as a java.time.Duration - -.global http timeouts example -[source,yaml] ----- -spring: - cloud: - gateway: - httpclient: - connect-timeout: 1000 - response-timeout: 5s ----- - -=== Per-route timeouts -To configure per-route timeouts: + -`connect-timeout` must be specified in milliseconds. + -`response-timeout` must be specified in milliseconds. - -.per-route http timeouts configuration via configuration -[source,yaml] ----- - - id: per_route_timeouts - uri: https://example.org - predicates: - - name: Path - args: - pattern: /delay/{timeout} - metadata: - response-timeout: 200 - connect-timeout: 200 ----- - -.per-route timeouts configuration using Java DSL -[source,java] ----- -import static org.springframework.cloud.gateway.support.RouteMetadataUtils.CONNECT_TIMEOUT_ATTR; -import static org.springframework.cloud.gateway.support.RouteMetadataUtils.RESPONSE_TIMEOUT_ATTR; - - @Bean - public RouteLocator customRouteLocator(RouteLocatorBuilder routeBuilder){ - return routeBuilder.routes() - .route("test1", r -> { - return r.host("*.somehost.org").and().path("/somepath") - .filters(f -> f.addRequestHeader("header1", "header-value-1")) - .uri("http://someuri") - .metadata(RESPONSE_TIMEOUT_ATTR, 200) - .metadata(CONNECT_TIMEOUT_ATTR, 200); - }) - .build(); - } ----- - -A per-route `response-timeout` with a negative value will disable the global `response-timeout` value. - ----- - - id: per_route_timeouts - uri: https://example.org - predicates: - - name: Path - args: - pattern: /delay/{timeout} - metadata: - response-timeout: -1 ----- - -== Fluent Java Routes API - -To allow for simple configuration in Java, the `RouteLocatorBuilder` bean includes a fluent API. -The following listing shows how it works: - -.GatewaySampleApplication.java -==== -[source,java] ----- -// static imports from GatewayFilters and RoutePredicates -@Bean -public RouteLocator customRouteLocator(RouteLocatorBuilder builder, ThrottleGatewayFilterFactory throttle) { - return builder.routes() - .route(r -> r.host("**.abc.org").and().path("/image/png") - .filters(f -> - f.addResponseHeader("X-TestHeader", "foobar")) - .uri("http://httpbin.org:80") - ) - .route(r -> r.path("/image/webp") - .filters(f -> - f.addResponseHeader("X-AnotherHeader", "baz")) - .uri("http://httpbin.org:80") - .metadata("key", "value") - ) - .route(r -> r.order(-1) - .host("**.throttle.org").and().path("/get") - .filters(f -> f.filter(throttle.apply(1, - 1, - 10, - TimeUnit.SECONDS))) - .uri("http://httpbin.org:80") - .metadata("key", "value") - ) - .build(); -} ----- -==== - -This style also allows for more custom predicate assertions. -The predicates defined by `RouteDefinitionLocator` beans are combined using logical `and`. -By using the fluent Java API, you can use the `and()`, `or()`, and `negate()` operators on the `Predicate` class. - -== The `DiscoveryClient` Route Definition Locator - -You can configure the gateway to create routes based on services registered with a `DiscoveryClient` compatible service registry. - -To enable this, set `spring.cloud.gateway.discovery.locator.enabled=true` and make sure a `DiscoveryClient` implementation (such as Netflix Eureka, Consul, or Zookeeper) is on the classpath and enabled. - -=== Configuring Predicates and Filters For `DiscoveryClient` Routes - -By default, the gateway defines a single predicate and filter for routes created with a `DiscoveryClient`. - -The default predicate is a path predicate defined with the pattern `/serviceId/**`, where `serviceId` is -the ID of the service from the `DiscoveryClient`. - -The default filter is a rewrite path filter with the regex `/serviceId/?(?.*)` and the replacement `/${remaining}`. -This strips the service ID from the path before the request is sent downstream. - -If you want to customize the predicates or filters used by the `DiscoveryClient` routes, set `spring.cloud.gateway.discovery.locator.predicates[x]` and `spring.cloud.gateway.discovery.locator.filters[y]`. -When doing so, you need to make sure to include the default predicate and filter shown earlier, if you want to retain that functionality. -The following example shows what this looks like: - -.application.properties -==== -[soure,properties] ----- -spring.cloud.gateway.discovery.locator.predicates[0].name: Path -spring.cloud.gateway.discovery.locator.predicates[0].args[pattern]: "'/'+serviceId+'/**'" -spring.cloud.gateway.discovery.locator.predicates[1].name: Host -spring.cloud.gateway.discovery.locator.predicates[1].args[pattern]: "'**.foo.com'" -spring.cloud.gateway.discovery.locator.filters[0].name: CircuitBreaker -spring.cloud.gateway.discovery.locator.filters[0].args[name]: serviceId -spring.cloud.gateway.discovery.locator.filters[1].name: RewritePath -spring.cloud.gateway.discovery.locator.filters[1].args[regexp]: "'/' + serviceId + '/?(?.*)'" -spring.cloud.gateway.discovery.locator.filters[1].args[replacement]: "'/${remaining}'" ----- -==== - -== Reactor Netty Access Logs - -To enable Reactor Netty access logs, set `-Dreactor.netty.http.server.accessLogEnabled=true`. - -IMPORTANT: It must be a Java System Property, not a Spring Boot property. - -You can configure the logging system to have a separate access log file. The following example creates a Logback configuration: - -.logback.xml -==== -[source,xml] ----- - - access_log.log - - %msg%n - - - - - - - - - ----- -==== - -== CORS Configuration -:cors-configuration-docs-uri: https://docs.spring.io/spring/docs/5.0.x/javadoc-api/org/springframework/web/cors/CorsConfiguration.html - -You can configure the gateway to control CORS behavior globally or per route. -Both offer the same possibilities. - -=== Global CORS Configuration - -The "`global`" CORS configuration is a map of URL patterns to {cors-configuration-docs-uri}[Spring Framework `CorsConfiguration`]. -The following example configures CORS: - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - globalcors: - cors-configurations: - '[/**]': - allowedOrigins: "https://docs.spring.io" - allowedMethods: - - GET ----- -==== - -In the preceding example, CORS requests are allowed from requests that originate from `docs.spring.io` for all GET requested paths. - -To provide the same CORS configuration to requests that are not handled by some gateway route predicate, set the `spring.cloud.gateway.globalcors.add-to-simple-url-handler-mapping` property to `true`. -This is useful when you try to support CORS preflight requests and your route predicate does not evaluate to `true` because the HTTP method is `options`. - -=== Route CORS Configuration - -The "`route`" configuration allows applying CORS directly to a route as metadata with key `cors`. -Like in the case of global configuration, the properties belong to {cors-configuration-docs-uri}[Spring Framework `CorsConfiguration`]. - -NOTE: If no `Path` predicate is present in the route '/**' will be applied. - -.application.yml -==== -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - - id: cors_route - uri: https://example.org - predicates: - - Path=/service/** - metadata: - cors - allowedOrigins: '*' - allowedMethods: - - GET - - POST - allowedHeaders: '*' - maxAge: 30 ----- -==== - -== Actuator API - -The `/gateway` actuator endpoint lets you monitor and interact with a Spring Cloud Gateway application. -To be remotely accessible, the endpoint has to be https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.html#production-ready-endpoints-enabling-endpoints[enabled] and https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.html#production-ready-endpoints-exposing-endpoints[exposed over HTTP or JMX] in the application properties. -The following listing shows how to do so: - -.application.properties -==== -[source,properties] ----- -management.endpoint.gateway.enabled=true # default value -management.endpoints.web.exposure.include=gateway ----- -==== - -=== Verbose Actuator Format - -A new, more verbose format has been added to Spring Cloud Gateway. -It adds more detail to each route, letting you view the predicates and filters associated with each route along with any configuration that is available. -The following example configures `/actuator/gateway/routes`: - -==== -[source,json] ----- -[ - { - "predicate": "(Hosts: [**.addrequestheader.org] && Paths: [/headers], match trailing slash: true)", - "route_id": "add_request_header_test", - "filters": [ - "[[AddResponseHeader X-Response-Default-Foo = 'Default-Bar'], order = 1]", - "[[AddRequestHeader X-Request-Foo = 'Bar'], order = 1]", - "[[PrefixPath prefix = '/httpbin'], order = 2]" - ], - "uri": "lb://testservice", - "order": 0 - } -] ----- -==== - -This feature is enabled by default. To disable it, set the following property: - -.application.properties -==== -[source,properties] ----- -spring.cloud.gateway.actuator.verbose.enabled=false ----- -==== - -This will default to `true` in a future release. - -=== Retrieving Route Filters - -This section details how to retrieve route filters, including: - -* <> -* <> - -[[gateway-global-filters]] -==== Global Filters - -To retrieve the <> applied to all routes, make a `GET` request to `/actuator/gateway/globalfilters`. The resulting response is similar to the following: - -==== ----- -{ - "org.springframework.cloud.gateway.filter.ReactiveLoadBalancerClientFilter@77856cc5": 10100, - "org.springframework.cloud.gateway.filter.RouteToRequestUrlFilter@4f6fd101": 10000, - "org.springframework.cloud.gateway.filter.NettyWriteResponseFilter@32d22650": -1, - "org.springframework.cloud.gateway.filter.ForwardRoutingFilter@106459d9": 2147483647, - "org.springframework.cloud.gateway.filter.NettyRoutingFilter@1fbd5e0": 2147483647, - "org.springframework.cloud.gateway.filter.ForwardPathFilter@33a71d23": 0, - "org.springframework.cloud.gateway.filter.AdaptCachedBodyGlobalFilter@135064ea": 2147483637, - "org.springframework.cloud.gateway.filter.WebsocketRoutingFilter@23c05889": 2147483646 -} ----- -==== - -The response contains the details of the global filters that are in place. -For each global filter, there is a string representation of the filter object (for example, `org.springframework.cloud.gateway.filter.ReactiveLoadBalancerClientFilter@77856cc5`) and the corresponding <> in the filter chain. - -[[gateway-route-filters]] -==== Route Filters -To retrieve the <> applied to routes, make a `GET` request to `/actuator/gateway/routefilters`. -The resulting response is similar to the following: - -==== ----- -{ - "[AddRequestHeaderGatewayFilterFactory@570ed9c configClass = AbstractNameValueGatewayFilterFactory.NameValueConfig]": null, - "[SecureHeadersGatewayFilterFactory@fceab5d configClass = Object]": null, - "[SaveSessionGatewayFilterFactory@4449b273 configClass = Object]": null -} ----- -==== - -The response contains the details of the `GatewayFilter` factories applied to any particular route. -For each factory there is a string representation of the corresponding object (for example, `[SecureHeadersGatewayFilterFactory@fceab5d configClass = Object]`). -Note that the `null` value is due to an incomplete implementation of the endpoint controller, because it tries to set the order of the object in the filter chain, which does not apply to a `GatewayFilter` factory object. - -=== Refreshing the Route Cache - -To clear the routes cache, make a `POST` request to `/actuator/gateway/refresh`. -The request returns a 200 without a response body. - -To clear the routes with specific metadata values, add the Query parameter `metadata` specifying the `key:value` pairs that the routes to be cleared should match. -If an error is produced during the asynchronous refresh, the refresh will not modify the existing routes. - -Sending `POST` request to `/actuator/gateway/refresh?metadata=group:group-1` will only refresh the routes whose `group` metadata is `group-1`: `first_route` and `third_route`. -==== -[source,json] ----- -[{ - "route_id": "first_route", - "route_object": { - "predicate": "...", - }, - "metadata": { "group": "group-1" } -}, -{ - "route_id": "second_route", - "route_object": { - "predicate": "...", - }, - "metadata": { "group": "group-2" } -}, -{ - "route_id": "third_route", - "route_object": { - "predicate": "...", - }, - "metadata": { "group": "group-1" } -}] ----- -==== - -=== Retrieving the Routes Defined in the Gateway - -To retrieve the routes defined in the gateway, make a `GET` request to `/actuator/gateway/routes`. -The resulting response is similar to the following: - -==== ----- -[{ - "route_id": "first_route", - "route_object": { - "predicate": "org.springframework.cloud.gateway.handler.predicate.PathRoutePredicateFactory$$Lambda$432/1736826640@1e9d7e7d", - "filters": [ - "OrderedGatewayFilter{delegate=org.springframework.cloud.gateway.filter.factory.PreserveHostHeaderGatewayFilterFactory$$Lambda$436/674480275@6631ef72, order=0}" - ] - }, - "order": 0 -}, -{ - "route_id": "second_route", - "route_object": { - "predicate": "org.springframework.cloud.gateway.handler.predicate.PathRoutePredicateFactory$$Lambda$432/1736826640@cd8d298", - "filters": [] - }, - "order": 0 -}] ----- -==== - -The response contains the details of all the routes defined in the gateway. -The following table describes the structure of each element (each is a route) of the response: - -[cols="3,2,4"] -|=== -| Path | Type | Description - -|`route_id` -| String -| The route ID. - -|`route_object.predicate` -| Object -| The route predicate. - -|`route_object.filters` -| Array -| The <> applied to the route. - -|`order` -| Number -| The route order. - -|=== - -[[gateway-retrieving-information-about-a-particular-route]] -=== Retrieving Information about a Particular Route - -To retrieve information about a single route, make a `GET` request to `/actuator/gateway/routes/{id}` (for example, `/actuator/gateway/routes/first_route`). -The resulting response is similar to the following: - -==== ----- -{ - "id": "first_route", - "predicates": [{ - "name": "Path", - "args": {"_genkey_0":"/first"} - }], - "filters": [], - "uri": "https://www.uri-destination.org", - "order": 0 -} ----- -==== - -The following table describes the structure of the response: - -[cols="3,2,4"] -|=== -| Path | Type | Description - -|`id` -| String -| The route ID. - -|`predicates` -| Array -| The collection of route predicates. Each item defines the name and the arguments of a given predicate. - -|`filters` -| Array -| The collection of filters applied to the route. - -|`uri` -| String -| The destination URI of the route. - -|`order` -| Number -| The route order. - -|=== - -=== Creating and Deleting a Particular Route Definition - -To create a route definition, make a `POST` request to `/gateway/routes/{id_route_to_create}` with a JSON body that specifies the fields of the route (see <>). - -To delete a route definition, make a `DELETE` request to `/gateway/routes/{id_route_to_delete}`. - -=== Creating multiple Route Definitions - -To create multiple route definitions in a single request, make a `POST` request to `/gateway/routes` with a JSON body that specifies the fields of the route, including the route id (see <>). - -The route definitions will be discarded if any route raises an error during the creation of the routes. - -=== Recap: The List of All endpoints - -The following table below summarizes the Spring Cloud Gateway actuator endpoints (note that each endpoint has `/actuator/gateway` as the base-path): - -[cols="2,2,5"] -|=== -| ID | HTTP Method | Description - -|`globalfilters` -|GET -| Displays the list of global filters applied to the routes. - -|`routefilters` -|GET -| Displays the list of `GatewayFilter` factories applied to a particular route. - -|`refresh` -|POST -| Clears the routes cache. - -|`routes` -|GET -| Displays the list of routes defined in the gateway. - -|`routes/{id}` -|GET -| Displays information about a particular route. - -|`routes/{id}` -|POST -| Adds a new route to the gateway. - -|`routes/{id}` -|DELETE -| Removes an existing route from the gateway. - -|=== - -=== Sharing Routes between multiple Gateway instances -Spring Cloud Gateway offers two `RouteDefinitionRepository` implementations. The first one is the -`InMemoryRouteDefinitionRepository` which only lives within the memory of one Gateway instance. -This type of Repository is not suited to populate Routes across multiple Gateway instances. - -In order to share Routes across a cluster of Spring Cloud Gateway instances, `RedisRouteDefinitionRepository` can be used. -To enable this kind of repository, the following property has to set to true: `spring.cloud.gateway.redis-route-definition-repository.enabled` -Likewise to the RedisRateLimiter Filter Factory it requires the use of the spring-boot-starter-data-redis-reactive Spring Boot starter. - -[[troubleshooting]] -== Troubleshooting - -This section covers common problems that may arise when you use Spring Cloud Gateway. - -=== Log Levels - -The following loggers may contain valuable troubleshooting information at the `DEBUG` and `TRACE` levels: - -- `org.springframework.cloud.gateway` -- `org.springframework.http.server.reactive` -- `org.springframework.web.reactive` -- `org.springframework.boot.autoconfigure.web` -- `reactor.netty` -- `redisratelimiter` - -=== Wiretap - -The Reactor Netty `HttpClient` and `HttpServer` can have wiretap enabled. -When combined with setting the `reactor.netty` log level to `DEBUG` or `TRACE`, it enables the logging of information, such as headers and bodies sent and received across the wire. -To enable wiretap, set `spring.cloud.gateway.httpserver.wiretap=true` or `spring.cloud.gateway.httpclient.wiretap=true` for the `HttpServer` and `HttpClient`, respectively. - -== Developer Guide - -These are basic guides to writing some custom components of the gateway. - -=== Writing Custom Route Predicate Factories - - -In order to write a Route Predicate you will need to implement `RoutePredicateFactory` as a bean. There is an abstract class called `AbstractRoutePredicateFactory` which you can extend. - -.MyRoutePredicateFactory.java -[source,java] ----- -@Component -public class MyRoutePredicateFactory extends AbstractRoutePredicateFactory { - - public MyRoutePredicateFactory() { - super(Config.class); - } - - @Override - public Predicate apply(Config config) { - // grab configuration from Config object - return exchange -> { - //grab the request - ServerHttpRequest request = exchange.getRequest(); - //take information from the request to see if it - //matches configuration. - return matches(config, request); - }; - } - - public static class Config { - //Put the configuration properties for your filter here - } - -} ----- -=== Writing Custom GatewayFilter Factories - -To write a `GatewayFilter`, you must implement `GatewayFilterFactory` as a bean. -You can extend an abstract class called `AbstractGatewayFilterFactory`. -The following examples show how to do so: - -.PreGatewayFilterFactory.java -==== -[source,java] ----- -@Component -public class PreGatewayFilterFactory extends AbstractGatewayFilterFactory { - - public PreGatewayFilterFactory() { - super(Config.class); - } - - @Override - public GatewayFilter apply(Config config) { - // grab configuration from Config object - return (exchange, chain) -> { - //If you want to build a "pre" filter you need to manipulate the - //request before calling chain.filter - ServerHttpRequest.Builder builder = exchange.getRequest().mutate(); - //use builder to manipulate the request - return chain.filter(exchange.mutate().request(builder.build()).build()); - }; - } - - public static class Config { - //Put the configuration properties for your filter here - } - -} ----- - -.PostGatewayFilterFactory.java -[source,java] ----- -@Component -public class PostGatewayFilterFactory extends AbstractGatewayFilterFactory { - - public PostGatewayFilterFactory() { - super(Config.class); - } - - @Override - public GatewayFilter apply(Config config) { - // grab configuration from Config object - return (exchange, chain) -> { - return chain.filter(exchange).then(Mono.fromRunnable(() -> { - ServerHttpResponse response = exchange.getResponse(); - //Manipulate the response in some way - })); - }; - } - - public static class Config { - //Put the configuration properties for your filter here - } - -} ----- -==== - -==== Naming Custom Filters And References In Configuration - -Custom filters class names should end in `GatewayFilterFactory`. - -For example, to reference a filter named `Something` in configuration files, the filter -must be in a class named `SomethingGatewayFilterFactory`. - -WARNING: It is possible to create a gateway filter named without the -`GatewayFilterFactory` suffix, such as `class AnotherThing`. This filter could be -referenced as `AnotherThing` in configuration files. This is **not** a supported naming -convention and this syntax may be removed in future releases. Please update the filter -name to be compliant. - -=== Writing Custom Global Filters - -To write a custom global filter, you must implement `GlobalFilter` interface as a bean. -This applies the filter to all requests. - -The following examples show how to set up global pre- and post-filters, respectively: - -==== -[source,java] ----- -@Bean -public GlobalFilter customGlobalFilter() { - return (exchange, chain) -> exchange.getPrincipal() - .map(Principal::getName) - .defaultIfEmpty("Default User") - .map(userName -> { - //adds header to proxied request - exchange.getRequest().mutate().header("CUSTOM-REQUEST-HEADER", userName).build(); - return exchange; - }) - .flatMap(chain::filter); -} - -@Bean -public GlobalFilter customGlobalPostFilter() { - return (exchange, chain) -> chain.filter(exchange) - .then(Mono.just(exchange)) - .map(serverWebExchange -> { - //adds header to response - serverWebExchange.getResponse().getHeaders().set("CUSTOM-RESPONSE-HEADER", - HttpStatus.OK.equals(serverWebExchange.getResponse().getStatusCode()) ? "It worked": "It did not work"); - return serverWebExchange; - }) - .then(); -} ----- -==== - -== Building a Simple Gateway by Using Spring MVC or Webflux - -WARNING: The following describes an alternative style gateway. None of the prior documentation applies to what follows. - -Spring Cloud Gateway provides a utility object called `ProxyExchange`. -You can use it inside a regular Spring web handler as a method parameter. -It supports basic downstream HTTP exchanges through methods that mirror the HTTP verbs. -With MVC, it also supports forwarding to a local handler through the `forward()` method. -To use the `ProxyExchange`, include the right module in your classpath (either `spring-cloud-gateway-mvc` or `spring-cloud-gateway-webflux`). - -The following MVC example proxies a request to `/test` downstream to a remote server: - -==== -[source,java] ----- -@RestController -@SpringBootApplication -public class GatewaySampleApplication { - - @Value("${remote.home}") - private URI home; - - @GetMapping("/test") - public ResponseEntity proxy(ProxyExchange proxy) throws Exception { - return proxy.uri(home.toString() + "/image/png").get(); - } - -} ----- -==== - -The following example does the same thing with Webflux: - -==== -[source,java] ----- -@RestController -@SpringBootApplication -public class GatewaySampleApplication { - - @Value("${remote.home}") - private URI home; - - @GetMapping("/test") - public Mono> proxy(ProxyExchange proxy) throws Exception { - return proxy.uri(home.toString() + "/image/png").get(); - } - -} ----- -==== - -Convenience methods on the `ProxyExchange` enable the handler method to discover and enhance the URI path of the incoming request. -For example, you might want to extract the trailing elements of a path to pass them downstream: - -==== -[source,java] ----- -@GetMapping("/proxy/path/**") -public ResponseEntity proxyPath(ProxyExchange proxy) throws Exception { - String path = proxy.path("/proxy/path/"); - return proxy.uri(home.toString() + "/foos/" + path).get(); -} ----- -==== - -All the features of Spring MVC and Webflux are available to gateway handler methods. -As a result, you can inject request headers and query parameters, for instance, and you can constrain the incoming requests with declarations in the mapping annotation. -See the documentation for `@RequestMapping` in Spring MVC for more details of those features. - -You can add headers to the downstream response by using the `header()` methods on `ProxyExchange`. - -You can also manipulate response headers (and anything else you like in the response) by adding a mapper to the `get()` method (and other methods). -The mapper is a `Function` that takes the incoming `ResponseEntity` and converts it to an outgoing one. - -First-class support is provided for "`sensitive`" headers (by default, `cookie` and `authorization`), which are not passed downstream, and for "`proxy`" (`x-forwarded-*`) headers. - -== AOT and Native Image Support - -Since `4.0.0`, Spring Cloud Gateway supports Spring AOT transformations and native images. - -TIP: If you're using load-balanced routes, you need to explicitly define your `LoadBalancerClient` service IDs. You can do so by using the `value` or `name` attributes of the `@LoadBalancerClient` annotation or as values of the `spring.cloud.loadbalancer.eager-load.clients` property. - -== Configuration properties - -To see the list of all Spring Cloud Gateway related configuration properties, see link:appendix.html[the appendix].