apache/apisix-control-plane

The Control-Plane for APISIX

APISIX-CONTROL-PLANE

What is apisix-control-plane

apisix-control-plane is an implementation of providing a control plane for DPs (Data Plane) like Apache APISIX or other gateways. with a yaml configuration capability, We can use yaml to define the behavior of any DP.

Why do we need to implement a control-plane

For now, we have a default implementation for Apache APISIX.

As we know, Apache APISIX is a high-performance gateway. When using APISIX we need to inform APISIX of some proxy rules, and distribute these rules to APISIX modules. We can call it control-plane, similar to pilot in istio. Of course, the distribution configuration is only the most basic function of the control plane.

We know that APISIX already has Admin API, so why do we need to implement a control-plane?

First of all, Apache APISIX Admin API is a way to define a single object, such as a single object such as route / service / upstream / consumer, although it is also possible to completely define a route through a huge route object, and the upstream object is embedded in the route, But any minor changes will trigger the reconstruction of the route. Rebuilding the route is definitely not a good idea and reduce performance.

In fact, leaving aside the Admin API, what we need is a description method that can completely define the rules while maintaining the legibility of the Admin API. Therefore, we have discussion here, and we have implemented a version of the basic functions according to this data structure, I hope everyone puts forward their views. We can also submit a PR to modify this document.

Secondly, Apache APISIX Admin API uses id associations to strongly bind objects to express the relationship between objects. For example, the route object uses service_id and upstream_id to bind the relationship with service and upstream respectively.

This kind of representation, like the well-known relational database, is easier to understand and reduces redundant configurations. But it also brings some other problems. For example, rely on verification. When we want to bind an upstream_id to a route, we must first create the upstream, and then bind the generated upstream_id to the route. This process corresponds to two Admin APIs, and there is no transaction management.

We hope that the emergence of control-plane can solve the above two problems.

1. Use yaml declarative definition method to define complete rules.
2. Block DP implementation details, describe object relationships in a unified way.

Of course, with control-plane we can do more.

For example, based on gitops configuration version management, it is also more convenient to use yaml to define APISIX in k8s.

Realize the prototype of cross-cluster synchronization configuration through the control panel. In the future, we can also enrich the functions of the control plane and simplify management under the cluster mode of multi-platform hybrid deployment (k8s/vm). We can also shield specific implementations of APISIX and provide configuration functions for more types of gateways.

Feature support

1. Support the declarative definition of yaml.
2. Use the memory database to synchronize the gateway status.
3. Diff capabilities based on memory objects.
4. Sync / update the APISIX configuration.
5. Support incremental synchronization.
6. Support transaction processing.

We created apache/apisix-control-plane to provide the basic implementation of the above features.

We also plan to support the following features

1. Support multiple DP configuration.
2. Support pull/push two synchronization strategies.
3. Support multi-DP hybrid cluster.
4. Support migration between DPs.

Everyone is welcome to participate in discussions and contributions.

apisix-control-plane's Issues

Feat: Data plane supports kong

CI: add tools to check ASF headers in code files

Feat: Support the feature of directly pushing the configuration to the gateway

Feat: Data plane supports envoy

test: add some test for Conversion from mem object to APISIX object

Feat: Supplementary unit test

CI failed when run lint

Feat: Add plugin schema checking for APISIX DP

[DISCUSS] adding control-plane to apisix-website

Should we add/list control plane to apisix-website?

Feat: add object dependency checking for APISIX DP

Feat: Add selector logic

feat:Use curl to encapsulate the Admin API into a script

Use curl to encapsulate the Admin API into a script.
Encapsulated into several functions.
For example:
add monitor, add route, add backend, etc. several functions.
It can be called by script name plus parameters.

feat: Minimal runnable version about yaml declarative definition

Feat: Support configuration migration between DPs

Feat: Distinguish development and deployment configuration files

Feat: Supplement e2e test

[DISCUSS] Support the yaml configuration ability for APISIX

Currently, 4 types are defined, namely

1.Gateway
2.Traffic distribution rules
3.Define the target service
4.Plug-in extension

Gateway

For edge traffic, extract the host separately and define a Gateway type

kind:Gateway
name: baidu-gw
servers:
 - port:
     number: 80
     name: http
     protocol: HTTP
   hosts:
   - "a.domain.com"
   - "b.domain.com"

object/field	describition
Gateway	the type for Edge traffic
Gateway.servers	Define edge traffic service list
Gateway.servers.port	the port for service
Gateway.servers.port.protocol	Specify protocol
Gateway.servers.hosts	List of domain names that a certain service can accept

Define traffic distribution rules

kind: Rule
name: xxx-rules
hosts:
- "domain.com"
gateways:
- baidu-gw
http:
- route:
 - destination:
     port: 28002
     host: baidu-server
     subset: baidu-v1
     weight: 10
 label：
    app: baidu
    version: v1
  match: 
  - headers:
     product_id:
       exact: v1
- route:
  - destination:
       port: 28002
       host: baidu-server
       subset: v2
  label:
    app: baidu
    version: v2

object/field	describition
Rule	the rule type for traffic
Rule.hosts	Specify the list of accepted hosts
Rule.gateways	Specify which gateway it belongs to, receive traffic from the edge gateway
Rule.http	Specify the HTTP protocol (similar to other protocols)
Rule.http.route	define route
Rule.http.match	Conditions for hitting the route
Rule.http.route.destination	Target service definition

Define the target service

kind: destinations
name: baidu-dest
host: baidu-server
subsets: 
- name: baidu-v1 
  ips：
  - 127.0.0.1
  - 127.0.0.2
- name: v2
  selector:
    labels:
      tag: v2

object/field	describition
destinations	Target service
destinations.host	Target service internal host
destinations.subsets	Target service collection

Plug-in extension

The logic of the plugin itself is not defined here, only known plugins will be referenced here

kind：Plugin 
selector：     
  labels：
     app: baidu
sort:
- name: limit-count
  conf:
      max：100
- name: prometheus
  conf:
     ...schema..

A complete demo

1. Use APISIX Admin API

curl -XPUT http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -d '
{
    "desc": "test_route",
    "uris": [
        "/*"
    ],
    vars:[
        ["arg_name", "==", "json"],
        ["arg_age", ">", "18"]
    ],
    "hosts": [
        "baidu.com"
    ],
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:8080": 10
        },
        "timeout": {
            "connect": 6000,
            "send": 6000,
            "read": 6000
        },
        "enable_websocket": false
    },
    "plugins":{
    	"prometheus":{},
    	"proxy-rewrite":{
    		"uri": "/test/home.html",
            "scheme": "http",
            "host": "baidu.com",
            "headers": {
                "X-Api-Version": "v1",
                "X-Api-Engine": "apisix",
                "X-Api-useless": ""
            }
    	}
    }
}'

2. Use YAML

kind:Gateway
name: baidu-gw
servers:
 - port:
     number: 80
     name: http
     protocol: HTTP
   hosts:
   - "baidu.com"

-----------------

kind: Rule
name: baidu-rules
hosts:
- "baidu.com"
gateways:
- baidu-gw
http:
- route:
  - destination:
       port: 8080
       host: baidu-server
       subset: baidu-v1
    label：
      app: baidu
      version: v1
  match: 
  - args:
     name:
       exact: "json"
     age:
       Greater: 18
  - uri:
      prefix: "/"
-------------------

kind: destinations
name: baidu-dest
host: baidu-server
subsets: 
- name: baidu-v1 
  ips：
  - 127.0.0.1

-------------------

kind：Plugin 
selector：     
  labels：
     app: baidu
sort:
- name: proxy-rewrite
  conf:
    uri: "/test/home.html"
    scheme: "http"
    host: "baidu.com"
    headers: 
      X-Api-Version: "v1"
      X-Api-Engine: "apisix"
      X-Api-useless: ""
- name: prometheus