Service types

A component may define new service types. This are definitions of required fields for each service type.

For example in the core the predefined service types as Web Server or Email Server are defined this way. You can define new service types as a docker server, or AWS account.

Manifest YAML component definition

components:
  - name: Email Server
    type: service
    traits: email.server
    id: email.server
    fields:
      - label: SMTP Server Address
        name: smtp
        type: text
        validation: empty
    status:
      command: serverboards.core.email/daemon
      call: is_email_up
      frequency: 1d
Field Description
fields Fields as defined in Generic Form Fields
status Checked for the status of the service.

Traits

A component MUST provide one or more traits, and then this service will be usable in actions, screens or any other situation that a specific service trait is required.

This allows to have a definition of for example generic email account and Gmail account, and both can be used in the same situations although the configuration may be slightly different.

There is another indirection level possible as actions on services have their own traits and as such its possible that one action requires another that provides the email API.

Status

Each service should be able to self attest if the configured service is working this may mean that the provided credentials are right, that the webpage is up or anything similar.

It must provide a command to execute (a cmd component type) and a method to call that will receive the full service description. Optionally it can provide a frequency to state how often to check for status; by default it is once per day.

status:
  command: serverboards.core.email/daemon
  call: is_email_up
  frequency: 1d

It must return one of:

  • one string with the current status tag.
  • An object with at least:
    • status – The current status
    • message – A description of the error
    • Other codes will be stored at the logs and can be useful to diagnose the problem, as tracebacks and return codes.

Recommended tags are:

Positive status:

  • ok
  • up

Negative status:

  • error
  • unknown
  • nok
  • down
  • not-configured
  • not-authorized

If a negative status is provided a new issue is created (if it does not already exist) and if a positive status is given, the issue will be automatically closed if still open.