Services
TARDIS
provides the possibility to start-up dedicated services along with its main process. Those services must
be decorated with the service
decorator implemented in the cobald.daemon
module. In order to allow dynamic
creation of those services
via yaml
tags, the service needs to be decorated with the
@yaml_tag(eager=True)
decorator as well. The services are then dynamically created and started during the
yaml
parsing of the configuration. All services are configured within the Services
section of the
TARDIS
configuration using yaml
tags. Using multiple services is supported by using a separate yaml
MappingNode per service.
Example implementation
from cobald.daemon import service
from cobald.daemon.plugins import yaml_tag
@service(flavour=asyncio)
@yaml_tag(eager=True)
class ExampleService(object):
def __init__(option_1):
...
async def run():
...
Example configuration
Services:
ExampleService:
!ExampleService
option_1: my_option_1
Service_2:
!TardisService2
option_123: my_option_123
REST Service
The RestService
provides a REST API to access the information stored about managed
Drones
inside the SqliteRegistry
plugin. Currently access is read
only and limited to either list all managed resources or to get the state of a particular resource. All supported
REST API calls and their parameters are described in REST API documentation available on
http://<hostname>:<port>/docs
after starting the service. The REST service is using JSON Web Token (JWT) and
OAuth2 scopes for authentication and authorization.
Note
The REST service currently supports only read access to the
SqliteRegistry
using the resources:get
OAuth2 scope. However,
this could be extended in the future to support also DB updates and deletions using resources:put
and
resources:delete
OAuth2 scopes. In addition, plans exist to store the TARDIS
configuration in a
database as well and allow to use the REST service to perform configuration updates at run time.
Warning
In order to enable the RestService
, the
SqliteRegistry
plugin has to be enabled as well.
Available configuration options
Option |
Short Description |
Requirement |
---|---|---|
host |
Hostname or IP the REST Service is listening on |
Required |
port |
Port the REST Service is listening on |
Required |
secret_key |
32 byte secret key to generate and validate JWTs |
Required |
algorithm |
Algorithm to generate and validate JWTs (default: HS256) |
Optional |
users |
List of user entries allowed to use the REST service. (see below) |
Required |
Option |
Short Description |
Requirement |
---|---|---|
user_name |
The name of the user |
Required |
hashed_password |
The |
Required |
scopes |
List of scopes the user is allowed to request. |
Required |
Note
The REST service is using a 32 byte secret_key
to generate and verify JWTs. It can be created using
openssl rand -hex 32
.
Example configuration
Services:
restapi:
!TardisRestApi
host: 127.0.0.1
port: 1234
secret_key: 752e003f636f402cc23728e185ce8c9eef27b7e02cf509b3015f7757e625b8e4
algorithm: HS256
users:
- user_name: tardis
hashed_password: $2b$12$c9SSllh1U6tOhIo37sDWF.kdRIU5RQAAOHL9bVYMs2.HluyFE43Uq
scopes:
- resources:get
Plugins:
SqliteRegistry:
db_file: drone_registry.db
Available logging configuration options
The REST service uses uvicorn
as ASGI server, which provides some additional logging functionality. By default
the access and errors logs are written into the regular TARDIS
logfile. However, it can be configured to write
both access and error logs into a separate file. Therefore, an uvicorn
logger needs to be configured. See the
example logging configuration.
Example logging configuration
logging:
version: 1
loggers:
root:
level: DEBUG
handlers: [console, file]
uvicorn:
level: INFO
handlers: [ uvicorn_file ]
propagate: False
formatters:
precise:
format: '%(name)s: %(asctime)s %(message)s'
datefmt: '%Y-%m-%d %H:%M:%S'
handlers:
console:
class : logging.StreamHandler
formatter: precise
stream : ext://sys.stdout
file:
class : logging.handlers.RotatingFileHandler
formatter: precise
filename: tardis.log
maxBytes: 10485760
backupCount: 3
uvicorn_file:
class: logging.handlers.RotatingFileHandler
formatter: precise
filename: uvicorn.log
maxBytes: 10485760
backupCount: 3
Convenience Tools
Generate Token
The generate_token
command provides the possibility to create non-expiring tokens to be used to authenticate
against the REST service (see above). This is useful for automated scripts polling the REST
service.
Note
For security reasons it is recommended to use non-expiring tokens only together with resources:get
scope.
Option |
Short Description |
Requirement |
---|---|---|
user_name |
The user name the token includes |
Required |
scopes |
List of scopes the token should have. Comma separated list. |
Required |
config-file |
The |
Optional |
secret-key |
The secret key to generate the token |
Optional |
algorithm |
The algorithm to generate the token. For example |
Optional |
Either config-file
or secret-key
and algorithm
needs to be specified.
Examples
generate_token --user-name tardis --scopes resources:get --config-file tardis.yml
#alternatively
python -m tardis.rest.token_generator --user-name tardis --scopes resources:get --config-file tardis.yml
generate_token --user-name tardis --scopes resources:get --secret-key ... --algorithm HS256
#alternatively
python -m tardis.rest.token_generator --user-name tardis --scopes resources:get --secret-key ... --algorithm HS256
Hash Credentials
The hash_credentials
command provides an easy way to create password hashes using bcrypt to be used in the
REST service configuration (see above).
Argument |
Short Description |
Requirement |
---|---|---|
password |
The password to be hashed using bcrypt |
Required |
Examples
hash_credentials TopSecretPassword
#alternatively
python -m tardis.rest.hash_credentials TopSecretPassword