Skip to content

Latest commit

 

History

History
634 lines (442 loc) · 10.1 KB

api.rst

File metadata and controls

634 lines (442 loc) · 10.1 KB
Raw

API Reference

Vulcan's HTTP API is the best way to configure one or several instances of Vulcan at the same time. Essentially it's a tiny wrapper around the backend. Multiple Vulcand instances listening to the same prefix would detect changes simultaneously and reload configuration.

Status

Status endpoint is handy when you need to integrate Vulcand with another load balancer that can poll Vulcand to route the traffic based on the healthcheck response.

Check status

GET /v2/status

Returns: 200 OK

{
   "Status": "ok"
}

Log severity

Log severity endpoint allows to change the logging severity for a running instance

Get severity

GET /v2/log/severity

Returns: 200 OK

{
   "Severity": "WARN"
}

Set severity

PUT 'multipart/form-data' /v2/log/severity
Parameter Description
severity Severity - WARN, INFO or ERROR

Returns: 200 OK

{
   "Message": "Severity has been updated to INFO"
}

Host

Get hosts

GET /v2/hosts

Example response:

{
  "Hosts":[
     {
        "Name":"localhost",
        "Settings":{
           "KeyPair":null,
           "Default":false
        }
     }
  ]
}

Upsert host

POST 'application/json' /v2/hosts

Add a host to the proxy.

{
"Host": {
 "Name": "localhost",                              // hostname
 "Settings": {                                     // settings are optional
   "KeyPair": {"Cert": "base64", Key: "base64"},   // base64 encoded key-pair certificate
   "Default": false ,                              // default host for SNI
 }
}

}

Example responses:

{
 "Name": "localhost",
 "Settings": {
   "KeyPair": null,
   "Default": false
 }
}

Delete host

DELETE /v2/hosts/<name>

Delete a host.

Listener

Upsert listener

POST 'application/json' /v2/listeners

Upsert listener

{
 "Listener": {
  "Id": "l1",
  "Protocol": "https", // http or https
  "Address":
    {
       "Network":"tcp", // unix or tcp
       "Address":"localhost:8184"
    }
 }
}

Example response:

{
  "Id": "12",
  "Protocol": "https",
  "Address":
    {
       "Network":"tcp",
       "Address":"localhost:8184"
    }
}

Delete listener

DELETE /v2/listeners/<listener-id>

Delete a listener

Backend

Get backends

GET /v2/backends

Retrieve the existing upstreams. Example response:

{
 "Backends": [
   {
     "Id": "b1",
     "Type": "http",
     "Settings": {
       "Timeouts": {
         "Read": "",
         "Dial": "",
         "TLSHandshake": ""
       },
       "KeepAlive": {
         "Period": "",
         "MaxIdleConnsPerHost": 0
       }
     }
   }
 ]
}

Upsert backend

POST 'application/json' /v2/backends
{
"Backend": {
  "Id": "b1",
  "Type": "http",
  "Settings": {
    "Timeouts": {
      "Read": "5s",
      "Dial": "5s",
      "TLSHandshake": "10s"
    },
    "KeepAlive": {
      "Period": "30s",
      "MaxIdleConnsPerHost": 12
    }
  }
 }
}

Example response:

{
 "Id": "b1",
 "Type": "http",
 "Settings": {
   "Timeouts": {
     "Read": "5s",
     "Dial": "5s",
     "TLSHandshake": "10s"
   },
   "KeepAlive": {
     "Period": "30s",
     "MaxIdleConnsPerHost": 12
   }
 }
}

Delete backend

DELETE /v2/backends/<id>

Server

Get servers

GET /v2/backends/<id>/servers

Retrieve the servers of the backend. Example response:

{
 "Servers": [
   {
     "Id": "srv1",
     "URL": "http://localhost:5000"
   },
   {
     "Id": "srv2",
     "URL": "http://localhost:5003"
   }
 ]
}

Get server

GET /v2/backends/<id>/servers/<server-id>

Retrieve the particular server with id server-id

Upsert server

POST /v2/backends/<id>/servers

Upsert server to the backend

{
 "Server": {
   "Id": "srv1",
   "URL": "http://localhost:5000"
 }
}

Example response:

{
  "Id": "e4",
  "Url": "http://localhost:5004",
  "Stats": null
}

Delete server

DELETE /v2/backends/<id>/servers/<server-id>

Delete a server.

Frontend

Get frontends

GET /v2/frontends

Retrieve the frontends. Example response:

{
 "Frontends": [
   {
     "Id": "f1",
     "Route": "Path(`/`)",
     "Type": "http",
     "BackendId": "b1",
     "Settings": {
       "Limits": {
         "MaxMemBodyBytes": 0,
         "MaxBodyBytes": 0
       },
       "FailoverPredicate": "",
       "Hostname": "",
       "TrustForwardHeader": false
     }
   }
 ]
}

Get frontend

GET /v2/frontends/<frontend-id>

Retrieve the particular frontend with id frontend-id

{
 "Id": "f1",
 "Route": "Path(`/`)",
 "Type": "http",
 "BackendId": "b1",
 "Settings": {
   "Limits": {
     "MaxMemBodyBytes": 0,
     "MaxBodyBytes": 0
   },
   "FailoverPredicate": "",
   "Hostname": "",
   "TrustForwardHeader": false
 }
}

Upsert frontend

POST 'application/json' /v2/frontends

Add a frontend to the host. Params:

{
 "Frontend": {
   "Id": "f1",
   "Route": "Path(`\/`)",
   "Type": "http",
   "BackendId": "b1",
   "Settings": {
     "Limits": {
       "MaxMemBodyBytes": 0,
       "MaxBodyBytes": 0
     },
     "FailoverPredicate": "",
     "Hostname": "",
     "TrustForwardHeader": false
   }
 }
}

Example response:

{
 "Id": "f1",
 "Route": "Path(`/`)",
 "Type": "http",
 "BackendId": "b1",
 "Settings": {
   "Limits": {
     "MaxMemBodyBytes": 0,
     "MaxBodyBytes": 0
   },
   "FailoverPredicate": "",
   "Hostname": "",
   "TrustForwardHeader": false
 }
}

Delete frontend

DELETE /v2/frontends/<frontend-id>

Delete a frontend.

Rate limit

Get rate limit

GET /v2/frontends/<frontend-id>/middlewares/<middleware-id>

Retrieve the particular rate of frontend with id frontend-id and rate id rate-id Example response:

{
  "Id": "rl1",
  "Priority": 0,
  "Type": "ratelimit",
  "Middleware": {
    "PeriodSeconds": 1,
    "Burst": 3,
    "Variable": "client.ip",
    "Requests": 1
  }
}

Upsert rate limit

POST 'application/json' /v2/frontends/middlewares

Add a rate limit to the frontend, will take effect immediately.

{
 "Middleware": {
   "Id": "rl1",
   "Priority": 0,
   "Type": "ratelimit",
   "Middleware": {
     "PeriodSeconds": 1,
     "Burst": 3,
     "Variable": "client.ip",
     "Requests": 1
   }
 }
}

Json parameters explained:

Parameter Description
Id Optional rate id, will be generated if omitted
Requests Required amount of allowed requests
PeriodSeconds Required period in seconds for counting the requests
Burst Required allowed burst of the requests (additional requests exceeding the rate)
Variable Variable for rate limiting e.g. client.ip or request.header.My-Header

Delete a rate limit

DELETE /v2/frontends/<frontend-id>/middlewares/<middleware-id>

Deletes rate limit from the frontend.

Connection limit

Get connection limit

GET /v2/frontends/<frontend-id>/middlewares/<conn-id>

Retrieve the particular connection limit of frontend with id frontend-id and connection limit id conn-id. Example response:

{
  "Id": "cl1",
  "Priority": 0,
  "Type": "connlimit",
  "Middleware": {
    "Connections": 3,
    "Variable": "client.ip"
  }
}

Upsert connection limit

POST 'application/json' /v2/frontends/<frontend>/middlewares

Upsert a connection limit to the frontend. Example response:

{
 "Middleware": {
  "Id": "cl1",
  "Priority": 0,
  "Type": "connlimit",
  "Middleware": {
    "Connections": 3,
    "Variable": "client.ip"
  }
 }
}

JSON parameters explained

Parameter Description
Id Optional limit id, will be generated if omitted.|
Connections Required maximum amount of allowed simultaneous connections|
Variable Variable for limiting e.g. client.ip or request.header.My-Header

Delete connection limit

DELETE /v2/frontends/<frontend-id>/middlewares/<conn-id>

Delete a connection limit from the frontend.