3ca172f380
Cleaned up the documentation and reformatted the parameter list of listener creation to be made out of links. Added some comments to the resource declarations in resource.cc to prevent the order of them from being altered.
450 lines
13 KiB
Markdown
450 lines
13 KiB
Markdown
# Service Resource
|
|
|
|
A service resource represents a service inside MaxScale. A service is a
|
|
collection of network listeners, filters, a router and a set of backend servers.
|
|
|
|
## Resource Operations
|
|
|
|
### Get a service
|
|
|
|
Get a single service. The _:name_ in the URI must be a valid service name with
|
|
all whitespace replaced with hyphens. The service names are case-insensitive.
|
|
|
|
```
|
|
GET /v1/services/:name
|
|
```
|
|
|
|
#### Response
|
|
|
|
`Status: 200 OK`
|
|
|
|
```javascript
|
|
{
|
|
"links": {
|
|
"self": "http://localhost:8989/v1/services/Read-Connection-Router"
|
|
},
|
|
"data": {
|
|
"id": "Read-Connection-Router",
|
|
"type": "services",
|
|
"attributes": {
|
|
"router": "readconnroute",
|
|
"state": "Started",
|
|
"router_diagnostics": {
|
|
"connections": 0,
|
|
"current_connections": 1,
|
|
"queries": 0
|
|
},
|
|
"started": "Mon May 22 12:54:05 2017",
|
|
"total_connections": 1,
|
|
"connections": 1,
|
|
"parameters": { // Service parameters
|
|
"router_options": "master",
|
|
"user": "maxuser",
|
|
"password": "maxpwd",
|
|
"enable_root_user": false,
|
|
"max_retry_interval": 3600,
|
|
"max_connections": 0,
|
|
"connection_timeout": 0,
|
|
"auth_all_servers": false,
|
|
"strip_db_esc": true,
|
|
"localhost_match_wildcard_host": true,
|
|
"version_string": "",
|
|
"log_auth_warnings": true,
|
|
"retry_on_failure": true
|
|
},
|
|
"listeners": [ // Listeners that point to this service
|
|
{
|
|
"attributes": {
|
|
"parameters": {
|
|
"port": 4008,
|
|
"protocol": "MySQLClient",
|
|
"authenticator": "MySQLAuth"
|
|
}
|
|
},
|
|
"id": "Read-Connection-Listener",
|
|
"type": "listeners"
|
|
}
|
|
]
|
|
},
|
|
"relationships": {
|
|
"servers": {
|
|
"links": {
|
|
"self": "http://localhost:8989/v1/servers/"
|
|
},
|
|
"data": [ // List of servers that this service uses
|
|
{
|
|
"id": "server1",
|
|
"type": "servers"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"links": {
|
|
"self": "http://localhost:8989/v1/services/Read-Connection-Router"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Get all services
|
|
|
|
Get all services.
|
|
|
|
```
|
|
GET /v1/services
|
|
```
|
|
|
|
#### Response
|
|
|
|
`Status: 200 OK`
|
|
|
|
```javascript
|
|
{
|
|
"links": {
|
|
"self": "http://localhost:8989/v1/services/"
|
|
},
|
|
"data": [ // Collection of service resources
|
|
{
|
|
"id": "Read-Connection-Router",
|
|
"type": "services",
|
|
"attributes": {
|
|
"router": "readconnroute",
|
|
"state": "Started",
|
|
"router_diagnostics": {
|
|
"connections": 0,
|
|
"current_connections": 1,
|
|
"queries": 0
|
|
},
|
|
"started": "Mon May 22 13:00:46 2017",
|
|
"total_connections": 1,
|
|
"connections": 1,
|
|
"parameters": {
|
|
"router_options": "master",
|
|
"user": "maxuser",
|
|
"password": "maxpwd",
|
|
"enable_root_user": false,
|
|
"max_retry_interval": 3600,
|
|
"max_connections": 0,
|
|
"connection_timeout": 0,
|
|
"auth_all_servers": false,
|
|
"strip_db_esc": true,
|
|
"localhost_match_wildcard_host": true,
|
|
"version_string": "",
|
|
"log_auth_warnings": true,
|
|
"retry_on_failure": true
|
|
},
|
|
"listeners": [
|
|
{
|
|
"attributes": {
|
|
"parameters": {
|
|
"port": 4008,
|
|
"protocol": "MySQLClient",
|
|
"authenticator": "MySQLAuth"
|
|
}
|
|
},
|
|
"id": "Read-Connection-Listener",
|
|
"type": "listeners"
|
|
}
|
|
]
|
|
},
|
|
"relationships": {
|
|
"servers": {
|
|
"links": {
|
|
"self": "http://localhost:8989/v1/servers/"
|
|
},
|
|
"data": [
|
|
{
|
|
"id": "server1",
|
|
"type": "servers"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"links": {
|
|
"self": "http://localhost:8989/v1/services/Read-Connection-Router"
|
|
}
|
|
},
|
|
{
|
|
"id": "CLI",
|
|
"type": "services",
|
|
"attributes": {
|
|
"router": "cli",
|
|
"state": "Started",
|
|
"started": "Mon May 22 13:00:46 2017",
|
|
"total_connections": 2,
|
|
"connections": 2,
|
|
"parameters": {
|
|
"router_options": "",
|
|
"user": "",
|
|
"password": "",
|
|
"enable_root_user": false,
|
|
"max_retry_interval": 3600,
|
|
"max_connections": 0,
|
|
"connection_timeout": 0,
|
|
"auth_all_servers": false,
|
|
"strip_db_esc": true,
|
|
"localhost_match_wildcard_host": true,
|
|
"version_string": "",
|
|
"log_auth_warnings": true,
|
|
"retry_on_failure": true
|
|
},
|
|
"listeners": [
|
|
{
|
|
"attributes": {
|
|
"parameters": {
|
|
"address": "default",
|
|
"port": 0,
|
|
"protocol": "maxscaled",
|
|
"authenticator": "MaxAdminAuth"
|
|
}
|
|
},
|
|
"id": "CLI-Listener",
|
|
"type": "listeners"
|
|
},
|
|
{
|
|
"attributes": {
|
|
"parameters": {
|
|
"address": "0.0.0.0",
|
|
"port": 6603,
|
|
"protocol": "maxscaled",
|
|
"authenticator": "MaxAdminAuth"
|
|
}
|
|
},
|
|
"id": "CLI-Network-Listener",
|
|
"type": "listeners"
|
|
}
|
|
]
|
|
},
|
|
"relationships": {},
|
|
"links": {
|
|
"self": "http://localhost:8989/v1/services/CLI"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Get service listeners
|
|
|
|
Get the listeners of a service. The _:name_ in the URI must be a valid service
|
|
name with all whitespace replaced with hyphens.
|
|
|
|
```
|
|
GET /v1/services/:name/listeners
|
|
```
|
|
|
|
#### Response
|
|
|
|
`Status: 200 OK`
|
|
|
|
```javascript
|
|
{
|
|
"links": {
|
|
"self": "http://localhost:8989/v1/services/Read-Connection-Router/listeners"
|
|
},
|
|
"data": [
|
|
{
|
|
"attributes": {
|
|
"parameters": {
|
|
"port": 4008,
|
|
"protocol": "MySQLClient",
|
|
"authenticator": "MySQLAuth"
|
|
}
|
|
},
|
|
"id": "Read-Connection-Listener",
|
|
"type": "listeners"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Get service listeners
|
|
|
|
Get the listeners of a service. The _:name_ in the URI must be a valid service
|
|
name with all whitespace replaced with hyphens.
|
|
|
|
```
|
|
GET /v1/services/:name/listeners
|
|
```
|
|
|
|
#### Response
|
|
|
|
`Status: 200 OK`
|
|
|
|
```javascript
|
|
{
|
|
"links": {
|
|
"self": "http://localhost:8989/v1/services/Read-Connection-Router/listeners"
|
|
},
|
|
"data": [
|
|
{
|
|
"attributes": {
|
|
"parameters": {
|
|
"port": 4008,
|
|
"protocol": "MySQLClient",
|
|
"authenticator": "MySQLAuth"
|
|
}
|
|
},
|
|
"id": "Read-Connection-Listener",
|
|
"type": "listeners"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Get a sigle service listener
|
|
|
|
Get the listeners of a service. The _:name_ in the URI must be a valid service
|
|
name and _:listener_ must be a valid listener name, both with all whitespace
|
|
replaced with hyphens.
|
|
|
|
```
|
|
GET /v1/services/:name/listeners/:listener
|
|
```
|
|
|
|
#### Response
|
|
|
|
`Status: 200 OK`
|
|
|
|
```javascript
|
|
{
|
|
"links": {
|
|
"self": "http://localhost:8989/v1/services/RW-Split-Router/listeners/RW-Split-Listener"
|
|
},
|
|
"data": {
|
|
"attributes": {
|
|
"parameters": {
|
|
"port": 4006,
|
|
"protocol": "MySQLClient",
|
|
"authenticator": "MySQLAuth"
|
|
}
|
|
},
|
|
"id": "RW-Split-Listener",
|
|
"type": "listeners"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Create a new listener
|
|
|
|
|
|
```
|
|
POST /v1/services/:name/listeners
|
|
```
|
|
|
|
Create a new listener for a service by defining the resource. The _:name_ in the
|
|
URI must map to a service name with all whitespace replaced with hyphens. The
|
|
posted object must define the _data.id_ field with the name of the server and
|
|
the _data.attributes.parameters.port_ field with the port where the listener
|
|
will listen on. The following is the minimal required JSON object for defining a
|
|
new listener.
|
|
|
|
```javascript
|
|
{
|
|
"data": {
|
|
"id": "my-listener",
|
|
"type": "listeners",
|
|
"attributes": {
|
|
"parameters": {
|
|
"port": 3306
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
The following values can be given in the _parameters_ object. If SSL options are
|
|
provided, the _ssl_key_, _ssl_cert_ and _ssl_ca_cert_ parameters must all be
|
|
defined.
|
|
|
|
- [address](../Getting-Started/Configuration-Guide.md#user-content-address-1)
|
|
- [port](../Getting-Started/Configuration-Guide.md#user-content-port-1)
|
|
- [protocol](../Getting-Started/Configuration-Guide.md#user-content-protocol-1)
|
|
- [authenticator](../Getting-Started/Configuration-Guide.md#user-content-authenticator-1)
|
|
- [authenticator_options](../Getting-Started/Configuration-Guide.md#user-content-authenticator-options-1)
|
|
- [ssl_key](../Getting-Started/Configuration-Guide.md#user-content-ssl_key-1)
|
|
- [ssl_cert](../Getting-Started/Configuration-Guide.md#user-content-ssl_cert-1)
|
|
- [ssl_ca_cert](../Getting-Started/Configuration-Guide.md#user-content-ssl_ca_cert-1)
|
|
- [ssl_version](../Getting-Started/Configuration-Guide.md#user-content-ssl_version-1)
|
|
- [ssl_cert_verify_depth](../Getting-Started/Configuration-Guide.md#user-content-ssl_cert_verify_depth-1)
|
|
|
|
### Destroy a listener
|
|
|
|
```
|
|
DELETE /v1/services/:service/listeners/:name
|
|
```
|
|
|
|
In the URI , the _:name_ must map to a listener and the _:service_ must map to a
|
|
service. Both names must have all whitespace replaced with hyphens.
|
|
|
|
#### Response
|
|
|
|
Listener is destroyed:
|
|
|
|
`Status: 204 No Content`
|
|
|
|
Listener cannot be deleted:
|
|
|
|
`Status: 403 Forbidden`
|
|
|
|
### Update a service
|
|
|
|
The _:name_ in the URI must map to a service name and the request body must be a
|
|
valid JSON Patch document which is applied to the resource.
|
|
|
|
```
|
|
PATCH /v1/services/:name
|
|
```
|
|
|
|
The following standard service parameters can be modified.
|
|
|
|
- [user](../Getting-Started/Configuration-Guide.md#user)
|
|
- [password](../Getting-Started/Configuration-Guide.md#password)
|
|
- [enable_root_user](../Getting-Started/Configuration-Guide.md#enable_root_user)
|
|
- [max_retry_interval](../Getting-Started/Configuration-Guide.md#max_retry_interval)
|
|
- [max_connections](../Getting-Started/Configuration-Guide.md#max_connections)
|
|
- [connection_timeout](../Getting-Started/Configuration-Guide.md#connection_timeout)
|
|
- [auth_all_servers](../Getting-Started/Configuration-Guide.md#auth_all_servers)
|
|
- [strip_db_esc](../Getting-Started/Configuration-Guide.md#strip_db_esc)
|
|
- [localhost_match_wildcard_host](../Getting-Started/Configuration-Guide.md#localhost_match_wildcard_host)
|
|
- [version_string](../Getting-Started/Configuration-Guide.md#version_string)
|
|
- [weightby](../Getting-Started/Configuration-Guide.md#weightby)
|
|
- [log_auth_warnings](../Getting-Started/Configuration-Guide.md#log_auth_warnings)
|
|
- [retry_on_failure](../Getting-Started/Configuration-Guide.md#retry_on_failure)
|
|
|
|
Refer to the documentation on these parameters for valid values.
|
|
|
|
#### Response
|
|
|
|
Service is modified:
|
|
|
|
`Status: 204 No Content`
|
|
|
|
### Stop a service
|
|
|
|
Stops a started service.
|
|
|
|
```
|
|
PUT /v1/service/:name/stop
|
|
```
|
|
|
|
#### Response
|
|
|
|
Service is stopped:
|
|
|
|
`Status: 204 No Content`
|
|
|
|
### Start a service
|
|
|
|
Starts a stopped service.
|
|
|
|
```
|
|
PUT /v1/service/:name/start
|
|
```
|
|
|
|
#### Response
|
|
|
|
Service is started:
|
|
|
|
`Status: 204 No Content`
|