salt.returners.mysql

Return data to a mysql server

maintainer

Dave Boucha <dave@saltstack.com>, Seth House <shouse@saltstack.com>

maturity

mature

depends

python-mysqldb

platform

all

To enable this returner, the minion will need the python client for mysql installed and the following values configured in the minion or master config. These are the defaults:

mysql.host: 'salt'
mysql.user: 'salt'
mysql.pass: 'salt'
mysql.db: 'salt'
mysql.port: 3306

SSL is optional. The defaults are set to None. If you do not want to use SSL, either exclude these options or set them to None.

mysql.ssl_ca: None
mysql.ssl_cert: None
mysql.ssl_key: None

Alternative configuration values can be used by prefacing the configuration with alternative.. Any values not found in the alternative configuration will be pulled from the default location. As stated above, SSL configuration is optional. The following ssl options are simply for illustration purposes:

alternative.mysql.host: 'salt'
alternative.mysql.user: 'salt'
alternative.mysql.pass: 'salt'
alternative.mysql.db: 'salt'
alternative.mysql.port: 3306
alternative.mysql.ssl_ca: '/etc/pki/mysql/certs/localhost.pem'
alternative.mysql.ssl_cert: '/etc/pki/mysql/certs/localhost.crt'
alternative.mysql.ssl_key: '/etc/pki/mysql/certs/localhost.key'

Should you wish the returner data to be cleaned out every so often, set keep_jobs to the number of hours for the jobs to live in the tables. Setting it to 0 will cause the data to stay in the tables. The default setting for keep_jobs is set to 24.

Should you wish to archive jobs in a different table for later processing, set archive_jobs to True. Salt will create 3 archive tables

  • jids_archive

  • salt_returns_archive

  • salt_events_archive

and move the contents of jids, salt_returns, and salt_events that are more than keep_jobs hours old to these tables.

Use the following mysql database schema:

CREATE DATABASE  `salt`
  DEFAULT CHARACTER SET utf8
  DEFAULT COLLATE utf8_general_ci;

USE `salt`;

--
-- Table structure for table `jids`
--

DROP TABLE IF EXISTS `jids`;
CREATE TABLE `jids` (
  `jid` varchar(255) NOT NULL,
  `load` mediumtext NOT NULL,
  UNIQUE KEY `jid` (`jid`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
CREATE INDEX jid ON jids(jid) USING BTREE;

--
-- Table structure for table `salt_returns`
--

DROP TABLE IF EXISTS `salt_returns`;
CREATE TABLE `salt_returns` (
  `fun` varchar(50) NOT NULL,
  `jid` varchar(255) NOT NULL,
  `return` mediumtext NOT NULL,
  `id` varchar(255) NOT NULL,
  `success` varchar(10) NOT NULL,
  `full_ret` mediumtext NOT NULL,
  `alter_time` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  KEY `id` (`id`),
  KEY `jid` (`jid`),
  KEY `fun` (`fun`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

--
-- Table structure for table `salt_events`
--

DROP TABLE IF EXISTS `salt_events`;
CREATE TABLE `salt_events` (
`id` BIGINT NOT NULL AUTO_INCREMENT,
`tag` varchar(255) NOT NULL,
`data` mediumtext NOT NULL,
`alter_time` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
`master_id` varchar(255) NOT NULL,
PRIMARY KEY (`id`),
KEY `tag` (`tag`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

Required python modules: MySQLdb

To use the mysql returner, append '--return mysql' to the salt command.

salt '*' test.ping --return mysql

To use the alternative configuration, append '--return_config alternative' to the salt command.

New in version 2015.5.0.

salt '*' test.ping --return mysql --return_config alternative

To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command.

New in version 2016.3.0.

salt '*' test.ping --return mysql --return_kwargs '{"db": "another-salt"}'
salt.returners.mysql.clean_old_jobs()

Called in the master's event loop every loop_interval. Archives and/or deletes the events and job details from the database. :return:

salt.returners.mysql.event_return(events)

Return event to mysql server

Requires that configuration be enabled via 'event_return' option in master config.

salt.returners.mysql.get_fun(fun)

Return a dict of the last function called for all minions

salt.returners.mysql.get_jid(jid)

Return the information returned when the specified job id was executed

salt.returners.mysql.get_jids()

Return a list of all job ids

salt.returners.mysql.get_jids_filter(count, filter_find_job=True)

Return a list of all job ids :param int count: show not more than the count of most recent jobs :param bool filter_find_jobs: filter out 'saltutil.find_job' jobs

salt.returners.mysql.get_load(jid)

Return the load data that marks a specified jid

salt.returners.mysql.get_minions()

Return a list of minions

salt.returners.mysql.prep_jid(nocache=False, passed_jid=None)

Do any work necessary to prepare a JID, including sending a custom id

salt.returners.mysql.returner(ret)

Return data to a mysql server

salt.returners.mysql.save_load(jid, load, minions=None)

Save the load to the specified jid id