35745ee925
The listeners can now be deleted via the REST API. Documented the added endpoint in the REST API documentation.
396 lines
11 KiB
Markdown
396 lines
11 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. The service names are
|
|
case-insensitive.
|
|
|
|
```
|
|
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"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 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 table contains all values that can be given in the _parameters_
|
|
object.
|
|
|
|
|Parameter | Description |
|
|
|-----------------------|---------------------------------------------------|
|
|
|port | Port to listen on |
|
|
|address | Interface to listen on |
|
|
|authenticator | Authenticator module |
|
|
|authenticator_options | Options for the authenticator |
|
|
|ssl_key | Path to SSL key |
|
|
|ssl_cert | Path to SSL certificate |
|
|
|ssl_ca_cert | Path to SSL CA certificate |
|
|
|ssl_version | The SSL version to use [TLSv1.2|TLSv1.1|TLSv1.0] |
|
|
|ssl_cert_verify_depth | Certificate verification depth |
|
|
|
|
### 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
|
|
|
|
OK:
|
|
|
|
```
|
|
Status: 204 No Content
|
|
```
|
|
|
|
Listener not found:
|
|
|
|
```
|
|
Status: 404 Not Found
|
|
```
|
|
|
|
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`
|