Apache APIs IX integrates with Consul KV, and the service discovery capability is upgraded again

background information

Consul is a service grid solution. Consul KV, one of its cores, is a distributed key value database, which is mainly used to store configuration parameters and metadata, and also allows users to store index objects.

In the microservice architecture mode, when the upstream service changes due to capacity expansion and hardware failure, the maintenance cost will increase sharply by manually writing the configuration and maintaining the upstream service information. In this regard, Apache apisid provides the function of service discovery registry to dynamically obtain the latest service instance information, so as to reduce the maintenance cost of users.

At present, Apache apisik borrows the consumer contributed by the community_ KV module, which supports the service discovery registry based on Consul KV.

Working principle of plug-in

Apache APISIX uses the consumption of Consul KV distributed key value storage capability_ KV module decouples service providers and consumers, and realizes the two core functions of service discovery registry.

  1. Service registration: the service provider registers the service with the registry.
  2. Service discovery: service consumers find the routing information of service providers through the registry.

On this basis, Apache apisid will be more flexible to adapt to the existing micro service architecture and better meet the needs of users.

How to use

The test environments in this paper are built in Docker using Docker compose.

  1. Download Apache APIs IX.
# Pull the Git warehouse of apisik docker
git clone https://github.com/apache/apisix-docker.git 
  1. Create Consul folders and profiles.
# Create a consumption folder
mkdir -p ~/docker-things/consul/ && cd "$_" 
# create profile
touch docker-compose.yml server1.json
  1. Modify docker compose YML file.
version: '3.8'

    image: consul:1.9.3
    container_name: consul-server1
    restart: always
      - ./server1.json:/consul/config/server1.json:ro
      - apisix
      - '8500:8500'
    command: 'agent -bootstrap-expect=1'

    external: true
    name: example_apisix
  1. Modify Server1 JSON file.
  "node_name": "consul-server1",
  "server": true,
  "addresses": {
    "http": ""
  1. Configuration file in Apache apisix_conf/config.yaml adds relevant configuration information of consult.
# config.yml
# ...other config
      - "http://consul-server1:8500"
    prefix: "upstreams"
  1. Start Apache APIs IX and consult.
# Enter the example and consult folders, and start apifix and consult successively
docker-compose up -d
  1. Register the test service with consult. example contains two Web services, which you can test directly.
# Check docker - compose. For example YML can see two Web services
$ cat docker-compose.yml | grep web
# output
  - ./upstream/web1.conf:/etc/nginx/nginx.conf
  - ./upstream/web2.conf:/etc/nginx/nginx.conf
  1. Confirm the IP address of the Web service.
$ sudo docker inspect -f='{{.Name}} - {{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $(sudo docker ps -aq) | grep web
# output
/example-web1-1 -
/example-web2-1 -
  1. Request the HTTP API of Consul in the terminal to register the test service.
# Register with the corresponding IP
curl \
  -X PUT \
  -d ' {"weight": 1, "max_fails": 2, "fail_timeout": 1}' \
curl \
  -X PUT \
  -d ' {"weight": 1, "max_fails": 2, "fail_timeout": 1}' \

The path after / v1/kv / is formed in the format of {Prefix}/{Service Name}/{IP}:{Port}.

{prefix} is the prefix written when Consul is configured in apisex, {Service Name} and {IP}:{Port} need to be determined by the user according to the upstream service.

The format of data is {"weight": < num >, "max_failures": < num >, "fail_timeout": < num >}.

  1. Check whether the test service is registered successfully.
$ curl ""

If the following message is returned, the registration is successful.

# Output of successful registration

Create a route and enable Consul for it

Use the Admin API provided by Apache APIs IX to add Consul to the route.

Before adding, you need to determine X-API-KEY and upstream service_ Name two data.

  • X-API-KEY: the access Token of Admin API. In this example, we can use the default edd1c9f034335f136f87ad84b625c8f1.
  • upstream.service_name: the name of the upstream Service, which specifies the Service in a registry that will be bound to a route. When using consult, it needs to be set as the URL when registering the test Service, and remove the last {IP}:{Port}. We can also obtain the URL of the Service through the Memory Dump API provided by Apache apisik, and confirm whether the upstream Service can be found normally.
$ curl | jq
# output
  "services": {
    # This key is the required URL
    "http://consul-server1:8500/v1/kv/upstreams/webpages/": [
        "port": 80,
        "host": "",
        "weight": 1
        "port": 80,
        "host": "",
        "weight": 1
  "config": {
    # ...configs

Add route

Here, the request route with the URL of / consumer / * is assigned to http://consul-server1:8500/v1/kv/upstreams/webpages/ . At the same time, discovery_type must be set to consumption_ KV to start the corresponding module.

curl -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X POST -d '
    "uri": "/consul/*",    
    "upstream": {        
        "service_name": "http://consul-server1:8500/v1/kv/upstreams/webpages/",        
        "type": "roundrobin",
        "discovery_type": "consul_kv"    

Test configuration results

It can be seen from the request result that the new route in Apache APISIX can find the correct service address through Consul and request to two nodes according to the load balancing policy.

# First request
curl -s
# output
hello web1%

# Second request
curl -s
# output
hello web2%

# Note: it is also possible that web1 or web2 is requested twice.
#      This is caused by the load balancing feature, and you can try to make more requests.
#      If you are interested in load balancing, you can https://en.wikipedia.org/wiki/Load_balancing_(computing) 
#      Learn more in.


The first half of this paper introduces how Apache apisid cooperates with consol to realize the service discovery registry based on consol kV to solve the problem of service information management and maintenance.

The latter part focuses on how to use Apache APIs IX with Consul in Docker. Of course, the application in the actual scenario also requires readers to make a specific analysis according to the business use scenario and the existing system architecture.

For more instructions on using the consult registry in Apache APIs IX, see Official documents Found in. If you have other questions, you can Discussions Initiate a discussion or communicate through a mailing list.

Keywords: gateway consul apisix

Added by yusiyuseff on Tue, 08 Mar 2022 06:20:13 +0200