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

General options available to configure the REST service

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

Options available to the user entries

Option

Short Description

Requirement

user_name

The name of the user

Required

hashed_password

The bcrypt hashed password of that user

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.

Options available to the generate_token command

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 COBalD/TARDIS configuration file containing the configuration of the REST service

Optional

secret-key

The secret key to generate the token

Optional

algorithm

The algorithm to generate the token. For example HS256

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).

Arguments available to hash_credentials

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