Vulcand REST API Documentation Release 2.0 Vulcand Inc Nov 07, 2018 Contents 1 Quick Start 3 1.1 Example: setting up Vulcand.......................................4 2 User Manual 5 2.1 Glossary.................................................5 2.2 Configuration...............................................7 2.3 TLS.................................................... 25 2.4 Metrics.................................................. 30 2.5 Logging.................................................. 31 2.6 Process management........................................... 32 2.7 Installation................................................ 33 3 Middlewares 35 3.1 Middlewares............................................... 35 3.2 Middleware Chains............................................ 35 3.3 Vbundle................................................. 36 4 API Reference 43 4.1 Status................................................... 43 4.2 Log severity............................................... 43 4.3 Host.................................................... 44 4.4 Listener.................................................. 45 4.5 Backend................................................. 46 4.6 Server................................................... 47 4.7 Frontend................................................. 48 4.8 Rate limit................................................. 50 4.9 Connection limit............................................. 51 i ii Vulcand REST API Documentation, Release 2.0 Vulcand is a reverse proxy for HTTP API management and microservices. It is inspired by Hystrix. It uses Etcd as a configuration backend, so changes to configuration take effect immediately without restarting the service. Warning: Status: Under active development. Used at Mailgun on moderate workloads. Contents 1 Vulcand REST API Documentation, Release 2.0 2 Contents CHAPTER 1 Quick Start Vulcand uses Etcd as a configuration backend. See Etcd getting started guide for instructions. The easiest way to install Vulcand is to pull the trusted build from the hub.docker.com and launch it in the container: # download ,!vulcand from the trusted build docker pull ,!mailgun/vulcand:v0.8.0-beta.2 # launch vulcand in a container docker run - ,!p 8182:8182 -p 8181:8181 mailgun/ ,!vulcand:v0.8.0-beta.2 /go/ ,!bin/vulcand --apiInterface=0.0.0. ,!0 --etcd=http://172.17.42.1:4001 You can check if Vulcand is running by check- ing the logs of the container: # check out ,!the output from the container: docker logs $(docker ps| grep ,!vulcand| awk '{ print $1 }' ) Dec 25 20:22:24. ,!002: WARN PID:1[supervisor. ,!go:350] No frontends found That was Vulcand complaining that there are no frontends specified 3 Vulcand REST API Documentation, Release 2.0 1.1 Example: setting up Vulcand # Upsert ,!backend and add a server to it etcdctl set /vulcand/backends/ ,!b1/backend '{"Type": "http"}' etcdctl set /vulcand/ ,!backends/b1/servers/srv1' ,!{"URL": "http://localhost:5000"}' # Upsert a frontend connected to ,!backend "b1" that matches path / etcdctl set ,!/vulcand/frontends/f1/frontend ,!'{"Type": "http", "BackendId ,!": "b1", "Route": "Path(`/`)"}' # Upsert ,!backend and add a server to it vctl backend upsert -id b1 vctl server upsert -b b1 -id ,!srv1 -url http://localhost:5000 # Upsert a frontend connected to ,!backend "b1" that matches path / vctl frontend upsert ,!-id f1 -b b1 -route 'Path("/")' # Upsert ,!backend and add a server to it curl -X POST -H "Content- ,!Type: application/json" http:/ ,!/localhost:8182/v2/backends\ -d '{"Backend ,!": {"Id":"b1", "Type":"http"}}' curl -X POST ,!-H "Content-Type: application/ ,!json" http://localhost:8182/ ,!v2/backends/b1/servers\ -d '{"Server": {"Id":"srv1", ,! "URL":"http://localhost:5000"}}' # Upsert a frontend connected to ,!backend "b1" that matches path / curl -X POST -H "Content- ,!Type: application/json" http:/ ,!/localhost:8182/v2/frontends\ -d '{"Frontend": {"Id":"f1 ,!", "Type": "http", "BackendId": ,!"b1", "Route": "Path(\"/\")"}}' 4 Chapter 1. Quick Start CHAPTER 2 User Manual 2.1 Glossary Familiarizing with the glossary would help to understand the rest of this guide. 2.1.1 Host Hostname is defined by incoming Host header. E.g. curl http://example.com/alice generates the fol- lowing request: GET /alice HTTP/1.1 User-Agent: curl/7.35.0 Host: example.com Vulcand hosts contain associated information and settings, such as SNI options and TLS certificates. 2.1.2 Listener Listener is a dynamic socket that can be attached or detached to Vulcand without restart. Vulcand can have multiple http and https listeners attached to it, providing service on multiple interfaces and protocols. 2.1.3 Frontend Frontends match the requests and forward it to the backends. Each frontend defines a route - a special expression that matches the request, e.g. Path("/v1/path"). Frontends are linked to backend and Vulcand will use the servers from this backend to serve the request. 5 Vulcand REST API Documentation, Release 2.0 2.1.4 Backend Backend is a collection of servers, they control connection pools to servers and transport options, such as connection, read and write timeouts. 2.1.5 Server Server is a final destination of the incoming request, each server is defined by URL <schema>:// <host>:<port>, e.g. http://localhost:5000. 2.1.6 Middleware Vulcand supports pluggable middlewares. Middlewares can intercept or transform the request to any frontend. Exam- ples of the supported middlewares are rate limits and connection limits. You can add or remove middlewares using command line, API or directly via backends. 2.1.7 Circuit Breaker Circuit breakers are special type of middlewares that observe various metrics for a particular frontend and can activate failover scenario whenever the condition matches e.g. error rate exceeds the threshold. 2.1.8 Secret storage Vulcand supports secret storage - running process acts like encryption/decryption service every time it reads and writes sensitive data, e.g. TLS certificates to the backend. To use this feature, users generate sealKey using command line utility and pass this key to the process for encryption and decryption of the data in the backends. 2.1.9 Failover Predicates Sometimes it is handy to retry the request on error. The good question is what constitutes an error? Sometimes it’s a read/write timeout, and somethimes it’s a special error code. Failover predicates are expressions that define when the request can be failed over, e.g. IsNetworkError() && Attempts <= 2 IsNetworkError() # failover on network error Attempts()<=1 # allows only 1 failover attempt RequestMethod()== "GET" # failover for GET requests only ResponseCode()== 408 # failover on 408 HTTP response code Warning: if you omit Attempts, failover will max out after 10 attempts. 2.1.10 Route Route is a simple routing language for matching http requests with Go syntax: Method("POST") && Path("/ path"), here are a couple of examples: 6 Chapter 2. User Manual Vulcand REST API Documentation, Release 2.0 Host("<user>.example.com") // Match by host with trie syntax HostRegexp(".*.example.com") // Match by host with regexp syntax Path("/v1/users/<user>") // Match by path with trie syntax Method("POST")&& Path("/v1/users") // Match by method and path with trie syntax PathRegexp("/v1/users/.*") // Match by path with ,!regexp syntax MethodRegexp("DELETE|GET")&& PathRegexp("/v1/users/. *") // Match by method and ,!path with regexp syntax Header("Content-Type", "application/<subtype>") // trie-based matcher for ,!headers HeaderRegexp("Content-Type", "application/.*") // regexp based matcher ,!for headers 2.2 Configuration Vulcand can be configured via Etcd, API or command line tool - vctl. You can switch between different configuration examples using the samples switch. 2.2.1 Backends and servers Backend is a collection of servers. Vulcand load-balances requests within the backend and keeps the connection pool to every server. Fron- tends using the same backend will share the con- nections. Adding and removing servers to the backend will change the traffic in real-time, removing the backend will lead to graceful drain off of the connections. # Upsert ,!backend and add a server to it etcdctl set /vulcand/backends/ ,!b1/backend '{"Type": "http"}' etcdctl set /vulcand/ ,!backends/b1/servers/srv1' ,!{"URL": "http://localhost:5000"}' # Upsert ,!backend and add a server to it vctl backend upsert -id b1 vctl server upsert -b b1 -id ,!srv1 -url http://localhost:5000 # Upsert ,!backend and add a server to it curl -X POST -H "Content- ,!Type: application/json" http:/ ,!/localhost:8182/v2/backends\ (continues on next page) 2.2. Configuration 7 Vulcand REST API Documentation, Release 2.0 (continued from previous page) -d '{"Backend ,!": {"Id":"b1", "Type":"http"}}' curl -X POST ,!-H "Content-Type: application/ ,!json" http://localhost:8182/ ,!v2/backends/b1/servers\ -d '{"Server": {"Id":"srv1", ,! "URL":"http://localhost:5000"}}' Backend settings Backends define the configuration options to the servers, such as the amount of idle connections and timeouts. Backend options are represented as JSON dictionary. { "Timeouts":{ "Read": "1s", / ,!/ Socket read timeout (before we ,!receive the first reply header) "Dial": ,! "2s", // Socket connect timeout "TLSHandshake ,!": "3s", // TLS handshake timeout }, "KeepAlive":{ "Period": ,! "4s", // Keepalive ,!period for idle connections "MaxIdleConnsPerHost ,!":3, // How many idle ,!connections will be kept per host } } You can update the settings at any time, that will initiate graceful reload of the underlying settings in