zuul/doc/source/admin/drivers/mqtt.rst

title

MQTT Driver

MQTT

The MQTT driver supports reporters only. It is used to send MQTT message when items report.

Message Schema

An MQTT report uses this schema:

<mqtt schema>

action

The reporter action name, e.g.: 'start', 'success', 'failure', 'merge-failure', ...

tenant

The tenant name.

pipeline

The pipeline name.

project

The project name.

branch

The branch name.

change_url

The change url.

message

The report message.

change

The change number.

patchset

The patchset number.

ref

The change reference.

zuul_ref

The internal zuul change reference.

buildset

The buildset information.

uuid

The buildset global uuid.

builds

The list of builds.

job_name

The job name.

voting

The job voting status.

uuid

The build uuid (not present in start report).

start_time

The build start time (not present in start report).

end_time

The build end time (not present in start report).

log_url

The build log url (not present in start report).

result

The build results (not present in start report).

Here is an example of a start message:

{
  'action': 'start',
  'tenant': 'openstack.org',
  'pipeline': 'check',
  'project': 'sf-jobs',
  'branch': 'master',
  'change_url': 'https://gerrit.example.com/r/3',
  'message': 'Starting check jobs.',
  'change': '3',
  'patchset': '1',
  "ref": "refs/changes/03/3/1",
  'zuul_ref': 'Zf8b3d7cd34f54cb396b488226589db8f'
  'buildset': {
    'uuid': 'f8b3d7cd34f54cb396b488226589db8f'
    'builds': [{
      'job_name': 'linters',
      'voting': True
    }],
  },
}

Here is an example of a success message:

{
  'action': 'success',
  'tenant': 'openstack.org',
  'pipeline': 'check',
  'project': 'sf-jobs',
  'branch': 'master',
  'change_url': 'https://gerrit.example.com/r/3',
  'message': 'Build succeeded.',
  'change': '3',
  'patchset': '1',
  "ref": "refs/changes/03/3/1",
  'zuul_ref': 'Zf8b3d7cd34f54cb396b488226589db8f'
  'buildset': {
    'uuid': 'f8b3d7cd34f54cb396b488226589db8f'
    'builds': [{
      'job_name': 'linters',
      'voting': True
      'uuid': '16e3e55aca984c6c9a50cc3c5b21bb83',
      'start_time': 1524801179.8557224,
      'end_time': 1524801208.928095,
      'log_url': 'https://logs.example.com/logs/3/3/1/check/linters/16e3e55/',
      'result': 'SUCCESS',
    }],
  },
}

Connection Configuration

<mqtt connection>

driver

mqtt

The connection must set driver=mqtt for MQTT connections.

server

MQTT server hostname or address to use.

port

MQTT server port.

keepalive

Maximum period in seconds allowed between communications with the broker.

user

Set a username for optional broker authentication.

password

Set a password for optional broker authentication.

ca_certs

A string path to the Certificate Authority certificate files to enable TLS connection.

certfile

A strings pointing to the PEM encoded client certificate to enable client TLS based authentication. This option requires keyfile to be set too.

keyfile

A strings pointing to the PEM encoded client private keys to enable client TLS based authentication. This option requires certfile to be set too.

ciphers

A string specifying which encryption ciphers are allowable for this connection. More information in this openssl doc.

Reporter Configuration

A connection<connections> that uses the mqtt driver must be supplied to the reporter. Each pipeline must provide a topic name. For example:

- pipeline:
    name: check
    success:
      mqtt:
        topic: "{tenant}/zuul/{pipeline}/{project}/{branch}/{change}"
        qos: 2

pipeline.<reporter>.<mqtt>

To report via MQTT message, the dictionaries passed to any of the pipeline reporter<reporters> support the following attributes:

topic

The MQTT topic to publish messages. The topic can be a format string that can use the following parameters: tenant, pipeline, project, branch, change, patchset and ref. MQTT topic can have hierarchy separated by /, more details in this doc

qos

The quality of service level to use, it can be 0, 1 or 2. Read more in this guide