Add section on API configuration file

This commit is contained in:
Joshua Boniface 2019-07-28 20:27:07 -04:00
parent 0d195121ba
commit c38d9b31e1
1 changed files with 105 additions and 0 deletions

View File

@ -30,6 +30,111 @@ The PVC API consistently accepts HTTP POST commands of HTML form documents. Howe
The PCI API consistently returns JSON bodies as its responses, with the one exception of the `vm dump` endpoint which returns an XML body. For all POST endpoints, unless otherwise specified below, this is a `message` value containing a human-readable message about the success or failure of the command. The HTTP return code is always 200 for a success or 510 for a failure. For all GET endpoints except the mentioned `vm dump`, this is a JSON body containing the requested data. The PCI API consistently returns JSON bodies as its responses, with the one exception of the `vm dump` endpoint which returns an XML body. For all POST endpoints, unless otherwise specified below, this is a `message` value containing a human-readable message about the success or failure of the command. The HTTP return code is always 200 for a success or 510 for a failure. For all GET endpoints except the mentioned `vm dump`, this is a JSON body containing the requested data.
## Configuration
The API is configured using a YAML configuration file which is passed in to the API process by the environment variable `PVC_CONFIG_FILE`. When running with the default package and SystemD unit, this file is located at `/etc/pvc/pvc-api.yaml`.
### Conventions
* Settings may be `required`, `optional`, or `ignored`.
* Settings may `depends` on other settings. This indicates that, if one setting is enabled, the other setting is very likely `required` by that setting.
### `pvc-api.yaml`
Example configuration:
```
---
pvc:
debug: True
coordinators:
- pvc-hv1
- pvc-hv2
- pvc-hv3
api:
listen_address: "127.0.0.1"
listen_port: "7370"
authentication:
enabled: False
secret_key: "aSuperLong&SecurePasswordString"
tokens:
- description: "testing"
token: ""
ssl:
enabled: False
cert_file: ""
key_file: ""
```
#### `debug`
* *required*
Whether to enable Debug mode or not. If enabled, the API will use the Flask debug runtime instead of the PyWSGI framework and will log additional output. Should not be enabled in production.
#### `coordinators`
* *required*
A list of coordinator hosts, used to generate the Zookeeper connection string.
#### `api` -> `listen_address`
* *required*
The IP address for the API to listen on. Use `0.0.0.0` to specify "all interfaces".
#### `api` -> `listen_port`
The port for the API to listen on.
#### `api` -> `authentication` -> `enabled`
* *required*
Whether to enable API authentication or not. Should usually be enabled in production deployments, especially if the API is available on untrusted networks.
#### `api` -> `authentication` -> `secret_key`
* *optional*
* *requires* `authentication` -> `enabled`
The Flask authentication secret key used to salt session credentials. Should be a long (>32-character) random string generated with `pwgen` or a similar tool.
#### `api` -> `authentication` -> `tokens`
* *optional*
* *requires* `authentication` -> `enabled`
A list of API authentication tokens that can be passed via the `X-Authentication` header to authorize access to the API.
##### `description`
* *required*
A text description of the token function or use. Not parsed by the API, but used for administrator reference in the configuration file.
##### `token`
* *required*
The token itself, usually a UUID created with `uuidegen` or a similar tool.
#### `api` -> `ssl` -> `enabled`
* *required*
Whether to enable SSL for the API or not. Should usually be enabled in production deployments, especially if the API is available on untrusted networks.
#### `api` -> `ssl` -> `cert_file`
The path to the SSL certificate file for the API to use.
#### `api` -> `ssl` -> `key_file`
The path to the SSL private key file for the API to use.
## API endpoint documentation ## API endpoint documentation
### General endpoints ### General endpoints