You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by ju...@apache.org on 2022/11/09 02:32:03 UTC
[apisix-website] branch master updated: blog: Add Geo-routing with Apache APISIX post (#1394)
This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-website.git
The following commit(s) were added to refs/heads/master by this push:
new 47c5aea19dd blog: Add Geo-routing with Apache APISIX post (#1394)
47c5aea19dd is described below
commit 47c5aea19dd9aedd8ba0e85b90c569697c269362
Author: Nicolas Frankel <ni...@frankel.ch>
AuthorDate: Wed Nov 9 03:31:57 2022 +0100
blog: Add Geo-routing with Apache APISIX post (#1394)
---
blog/en/blog/2022/11/09/georouting-apisix.md | 236 +++++++++++++++++++++++++++
1 file changed, 236 insertions(+)
diff --git a/blog/en/blog/2022/11/09/georouting-apisix.md b/blog/en/blog/2022/11/09/georouting-apisix.md
new file mode 100644
index 00000000000..e105fb9eab3
--- /dev/null
+++ b/blog/en/blog/2022/11/09/georouting-apisix.md
@@ -0,0 +1,236 @@
+---
+title: Geo-routing with Apache APISIX
+authors:
+ - name: Nicolas Fränkel
+ title: Author
+ url: https://github.com/nfrankel
+ image_url: https://avatars.githubusercontent.com/u/752258
+keywords:
+ - Georouting
+ - GeoIP
+ - Nginx
+description: Apache APISIX, the Apache-led API Gateway, comes out of the box with many plugins to implement your use case. Sometimes, however, the plugin you're looking for is not available. While creating your own is always possible, it's sometimes necessary. Today, I'll show you how to route users according to their location without writing a single line of Lua code.
+tags: [Case Studies]
+image: https://repository-images.githubusercontent.com/560493734/4073382d-d3de-42b8-aa58-d0a139978768
+---
+
+> Apache APISIX, the Apache-led API Gateway, comes out of the box with many plugins to implement your use case. Sometimes, however, the plugin you're looking for is not available. While creating your own is always possible, it's sometimes necessary. Today, I'll show you how to route users according to their location without writing a single line of Lua code.
+
+<!--truncate-->
+
+<head>
+ <link rel="canonical" href="https://blog.frankel.ch/georouting-apisix/" />
+</head>
+
+## Why geo-routing?
+
+Geo-routing is to forward HTTP requests based on a user's physical location, inferred from their IP. There are many reasons to do that, and here is a couple of them.
+
+Note that I'll use the country as the location-dependent factor, but any smaller or bigger scale works. It's the scale I'm most familiar with - and probably the most useful.
+
+First, most applications are not meant to be geo-dependent. The app your team has just developed probably only makes sense in a single country, if not a single region. In this case, geo-routing will never be a problem.
+
+However, some apps do grow along with the business. When it happens, the need for [internationalization and localization](https://en.wikipedia.org/wiki/Internationalization_and_localization) appears. It's the app's responsibility to handle such geo-dependent factors. <abbr title="internationalization">i18n</abbr> should be handled natively by the tech stack, _e.g._, in [Java](https://docs.oracle.com/javase/8/docs/technotes/guides/intl/index.html). <abbr title="localization">l10n</abbr> i [...]
+
+Issues arise when business rules diverge from country to country, chiefly because of laws. Other reasons include a partnership. Imagine an e-commerce shop that has branches in many countries. You may choose the delivery partner, but depending on the country, available partners are different. While keeping a single codebase is always a wise choice, even the best design can only slow down the chaos from many business rules. At one point, splitting the God app into multiple country-dependen [...]
+
+Sometimes, you don't even have a choice. A country decides you have to store your database on their territory, so you cannot share it anymore and have to split both storage and app. I witnessed it first-hand with Russia in 2015: we had to deploy a custom version of our e-commerce application just for Russia.
+
+Finally, you may also want to deploy a new app version for a single country only. In this case, you should monitor not (only) technical metrics but business ones over time. Then you'll decide whether to expand the new version to other countries based on them or work more on the latest version before deploying further.
+
+## Setting up Apache APISIX for geo-routing
+
+Though I'm a developer by trade (and passion!), I'm pragmatic. I'm convinced that every line of code I don't write is a line I don't need to maintain. Apache APISIX doesn't offer geo-routing, but it's built on top of Nginx. The latter provides a [geo-routing](http://nginx.org/en/docs/http/ngx_http_geoip_module.html) feature, albeit not by default.
+
+The following instructions are based on Docker to allow everybody to follow them regardless of their platform.
+
+We need several steps to set up geo-routing on Apache APISIX:
+
+1. Create a custom Docker image
+ * Add the required library module
+ * Add its dependencies
+2. Configure Apache APISIX
+3. Enjoy!
+
+Nginx geo-routing requires the `ngx_http_geoip_module` module. But if we try to install it via a package manager, it also installs `nginx`, which conflicts with the `nginx` instance embedded in Apache APISIX. As we only need the library, we can get it from the relevant Docker image:
+
+```Dockerfile
+FROM nginx:1.21.4 as geoiplib
+
+FROM apache/apisix:2.15.0-debian
+
+COPY --from=geoiplib /usr/lib/nginx/modules/ngx_http_geoip_module.so \ #1
+ /usr/local/apisix/modules/ngx_http_geoip_module.so
+```
+
+Copy the library from the `nginx` image to the `apache/apisix` one
+
+The regular package install installs all the dependencies, even the ones we don't want. Because we only copy the library, we need to install the dependencies manually. It's straightforward:
+
+```Dockerfile
+RUN apt-get update \
+ && apt-get install -y libgeoip1
+```
+
+Nginx offers two ways to activate a module: via the command line or dynamically in the `nginx.conf` configuration file. The former is impossible since we're not in control, so the latter is our only option. To update the Nginx config file with the module at startup time, Apache APISIX offers a hook in its config file:
+
+```yaml
+nginx_config:
+ main_configuration_snippet: |
+ load_module "modules/ngx_http_geoip_module.so";
+```
+
+The above will generate the following:
+
+```
+# Configuration File - Nginx Server Configs
+# This is a read-only file, do not try to modify it.
+master_process on;
+
+worker_processes auto;
+worker_cpu_affinity auto;
+
+# main configuration snippet starts
+load_module "modules/ngx_http_geoip_module.so";
+
+...
+```
+
+The [GeoIP module](http://nginx.org/en/docs/http/ngx_http_geoip_module.html) relies on the [Maxmind GeoIP database](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data). We installed it implicitly in the previous step; we have to configure the module to point to it:
+
+```yaml
+nginx_config:
+ http_configuration_snippet: |
+ geoip_country /usr/share/GeoIP/GeoIP.dat;
+```
+
+From this point on, every request going through Apache APISIX is geo-located. It translates as Nginx adding additional variables. As per the documentation:
+
+>The following variables are available when using this database:
+>
+>`$geoip_country_code`
+> two-letter country code, for example, `"RU"`, `"US"`.
+>`$geoip_country_code3`
+> three-letter country code, for example, `"RUS"`, `"USA"`.
+>`$geoip_country_name`
+> country name, for example, `"Russian Federation"`, `"United States"`.
+>
+> -- [Module ngx_http_geoip_module](http://nginx.org/en/docs/http/ngx_http_geoip_module.html)
+
+## Testing geo-routing
+
+You may believe that the above works - and it does, but I'd like to prove it.
+
+I've created a [dedicated project](https://github.com/ajavageek/apisix-georouting) whose architecture is simple:
+
+* Apache APISIX configured as above
+* Two upstreams, one in English and one in French
+
+```yaml
+upstreams:
+ - id: 1
+ type: roundrobin
+ nodes:
+ "english:8082": 1
+ - id: 2
+ type: roundrobin
+ nodes:
+ "french:8081": 1
+routes:
+ - uri: /
+ upstream_id: 1
+ - uri: /
+ upstream_id: 2
+#END
+```
+
+With this snippet, every user accesses the English upstream. I intend to direct users located in France to the French upstream and the rest to the English one. For this, we need to configure the second route:
+
+```yaml
+routes:
+ - uri: /
+ upstream_id: 2
+ vars: [["geoip_country_code", "==", "FR"]] #1
+ priority: 5 #2
+```
+
+1. The magic happens here; see below.
+2. By default, route matching rules are evaluated in arbitrary order. We need this rule to be evaluated first. So we increase the priority - the default is 10.
+
+Most Apache APISIX users are used to matching on routes, methods, and domains, but there's [more to it](https://apisix.apache.org/docs/apisix/admin-api/#uri-request-parameters). One can match on Nginx variables, as shown above. In our case, the route matches if the `geoip_country_code` variable is equal to `"FR"`.
+
+Note that `vars` values readability over power. Use the `filter_func(vars)` attribute if you need more complex logic.
+
+We can still not test our feature at this point, as we would need to change our IP address. Fortunately, it's possible to cheat (a bit), and the cheat is helpful in other scenarios. Imagine that Apache APISIX is not directly exposed to the Internet but sits behind a reverse proxy. There might be multiple reasons for this: "history", a single RP pointing to multiple gateways under the responsibility of different teams, etc.
+
+In this case, the client IP would be the RP's proxy. To propagate the original client IP, the agreed-upon method is to add an `X-Forwarded-For` request HTTP header:
+
+>The X-Forwarded-For (XFF) request header is a de-facto standard header for identifying the originating IP address of a client connecting to a web server through a proxy server.
+>
+>When a client connects directly to a server, the client's IP address is sent to the server (and is often written to server access logs). But if a client connection passes through any forward or reverse proxies, the server only sees the final proxy's IP address, which is often of little use. That's especially true if the final proxy is a load balancer which is part of the same installation as the server. So, to provide a more-useful client IP address to the server, the `X-Forwarded-For` [...]
+>
+> -- [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)
+
+The Nginx module offers this configuration but restricts it to an IP range. For testing, we configure it to _any_ IP; in production, we should set it to the RP IP.
+
+```yaml
+nginx_config:
+ http:
+ geoip_proxy 0.0.0.0/0;
+```
+
+We can finally test the setup:
+
+```bash
+curl localhost:9080
+```
+
+```
+{
+ "lang": "en",
+ "message": "Welcome to Apache APISIX"
+}
+```
+
+```bash
+curl -H "X-Forwarded-For: 212.27.48.10" localhost:9080 #1
+```
+
+1. `212.27.48.10` is a French IP address
+
+```
+{
+ "lang": "fr",
+ "message": "Bienvenue à Apache APISIX"
+}
+```
+
+## Bonus: logs and monitoring
+
+It's straightforward to use the new variable in the Apisix logs. I'd advise it for two reasons:
+
+* At the beginning to make sure everything is ok
+* In the long run, to monitor traffic, _e.g._, send it to Elasticsearch and display it on a Kibana dashboard
+
+Just configure it accordingly:
+
+```yaml
+nginx_config:
+ http:
+ access_log_format: "$remote_addr - $remote_user [$time_local][$geoip_country_code] $http_host \"$request\" $status $body_bytes_sent $request_time \"$http_referer\" \"$http_user_agent\" $upstream_addr $upstream_status $upstream_response_time"
+```
+
+Keep the default log variables and add the country code
+
+## Conclusion
+
+Geo-routing is a requirement for successful apps and businesses. Apache APISIX doesn't provide it out-of-the-box. In this post, I showed how it could still be straightforward to set it up using the power of Nginx.
+
+You can find the source code for this post on GitHub.
+
+**To go further:**
+
+* [Module ngx_http_geoip_module](http://nginx.org/en/docs/http/ngx_http_geoip_module.html)
+* [Converting Static Modules to Dynamic Modules](https://www.nginx.com/resources/wiki/extending/converting/)
+* [Customize Nginx configuration](https://apisix.apache.org/docs/apisix/customize-nginx-configuration/)
+* [GeoIP Update](https://github.com/maxmind/geoipupdate)