Python API¶

Spicerack Python API autodoc.

Spicerack package.

class spicerack.Spicerack(*, verbose: bool = False, dry_run: bool = True, cumin_config: str = '/etc/cumin/config.yaml', cumin_installer_config: str = '/etc/cumin/config-installer.yaml', conftool_config: str = '/etc/conftool/config.yaml', conftool_schema: str = '/etc/conftool/schema.yaml', debmonitor_config: str = '/etc/debmonitor.conf', spicerack_config_dir: str = '/etc/spicerack', http_proxy: str = '', get_cookbook_callback: Callable[[Spicerack, str, Sequence[str]], BaseItem | None] | None = None, extender_class: type['SpicerackExtenderBase'] | None = None)[source]¶

Bases: object

Spicerack service locator.

Initialize the service locator for the Spicerack library.

Parameters:

verbose (bool, optional) -- whether to set the verbose mode.
dry_run (bool, optional) -- whether this is a DRY-RUN.
cumin_config (str, optional) -- the path to Cumin's configuration file.
cumin_installer_config (str, optional) -- the path to Cumin's configuration file for the Debian installer.
conftool_config (str, optional) -- the path to Conftool's configuration file.
conftool_schema (str, optional) -- the path to Conftool's schema file.
debmonitor_config (str, optional) --
the path to Debmonitor's INI configuration file. It must have at least the following schema:
```
[DEFAULT]
server=debmonitor.example.com
cert=/etc/debmonitor/ssl/cert.pem
key=/etc/debmonitor/ssl/server.key
```
spicerack_config_dir (str, optional) -- the path for the root configuration directory for Spicerack. Module-specific configuration will be loaded from config_dir/module_name/.
http_proxy (str, optional) -- the scheme://url:port of the HTTP proxy to use for external calls.
get_cookbook_callback (callable, optional) -- a callable to retrieve a CookbookItem to execute a cookbook from inside another cookbook.
extender_class (type, optional) -- an optional class object that inherits from spicerack.SpicerackExtenderBase to dynamically add accessors to Spicerack. If not set no extenders will be registered, even if external_modules_dir is specified in the configuration.

admin_reason(reason: str, task_id: str | None = None) → Reason[source]¶

Get an administrative Reason instance.

Parameters:

reason (str) -- the reason to use to justify an administrative action. See spicerack.administrative.Reason for all the details.
task_id (str, optional) -- the task ID to mention in the reason.

Returns:

the administrative Reason instance.

Return type:

spicerack.administrative.Reason

alerting_hosts(target_hosts: TypeHosts, *, verbatim_hosts: bool = False) → AlertingHosts[source]¶

Get an AlertingHosts instance.

Parameters:

target_hosts (spicerack.typing.TypeHosts) -- the target hosts either as a NodeSet instance or a sequence of strings.
verbatim_hosts (bool, optional) -- if True use the hosts passed verbatim as is, if instead False, the default, consider the given target hosts as FQDNs and extract their hostnames to be used in Icinga.

Returns:

AlertingHosts instance.

Return type:

spicerack.alerting.AlertingHosts

alertmanager() → Alertmanager[source]¶

Get an Alertmanager instance.

Note

To interact with Alertmanager alerts attached to an instance use spicerack.Spicerack.alertmanager_hosts() instead.

Returns:: the Alertmanager instance.
Return type:: spicerack.alertmanager.Alertmanager

alertmanager_hosts(target_hosts: TypeHosts, *, verbatim_hosts: bool = False) → AlertmanagerHosts[source]¶

Get an AlertmanagerHosts instance.

Note

To interact with both Icinga and Alertmanager alerts, use spicerack.Spicerack.alerting_hosts() instead.

Parameters:

target_hosts (spicerack.typing.TypeHosts) -- the target hosts either as a NodeSet instance or a sequence of strings.
verbatim_hosts (bool, optional) -- if True use the hosts passed verbatim as is, if instead False, the default, consider the given target hosts as FQDNs and extract their hostnames to be used in Icinga.

Returns:

the AlertmanagerHosts instance.

Return type:

spicerack.alertmanager.AlertmanagerHosts

confctl(entity_name: str) → ConftoolEntity[source]¶

Access a Conftool specific entity instance.

Parameters:: entity_name (str) -- the name of a Conftool entity. Possible values: node, service, discovery, mwconfig.
Returns:: the confctl entity instance.
Return type:: spicerack.confctl.ConftoolEntity

debmonitor() → Debmonitor[source]¶

Get a Debmonitor instance to interact with a Debmonitor website.

Returns:: the instance.
Return type:: spicerack.debmonitor.Debmonitor
Raises:: KeyError -- if any configuration option is missing.

dhcp(remote_hosts: RemoteHosts) → DHCP[source]¶

Return a DHCP configuration manager for specified site.

Parameters:: remote_hosts (RemoteHosts instance) -- Hosts to operate on, which are normally install servers with dhcp.
Returns:: A DHCP configuration instance
Return type:: spicerack.dhcp.DHCP

discovery(*records: str) → Discovery[source]¶

Get a Discovery instance.

Parameters:: *records (str) -- arbitrary positional arguments, each one must be a Discovery DNS record name.
Returns:: the pre-configured Discovery instance for the given records.
Return type:: spicerack.dnsdisc.Discovery

dns() → Dns[source]¶

Get a Dns instance.

Returns:: a Dns instance that will use the operating system default namserver(s).
Return type:: wmflib.dns.Dns

elasticsearch_clusters(clustergroup: str, write_queue_datacenters: Sequence[str]) → ElasticsearchClusters[source]¶

Get an ElasticsearchClusters instance.

Parameters:

clustergroup (str) -- name of cluster group e.g search_eqiad.
write_queue_datacenters (Sequence[str]) -- Sequence of which core DCs to query write queues for.

Returns:

ElasticsearchClusters instance.

Return type:

spicerack.elasticsearch_cluster.ElasticsearchClusters

etcdctl(*, remote_host: RemoteHosts) → EtcdctlController[source]¶

Add etcdctl control capabilities to the given RemoteHost.

Params:

remote_host: Single remote host (that should map one single host): to add capabilities to.

Returns:: A wrapped RemoteHost with the etcdctl control related methods.

ganeti() → Ganeti[source]¶

Get an instance to interact with Ganeti.

Returns:: the instance
Return type:: spicerack.ganeti.Ganeti
Raises:: KeyError -- If the configuration file does not contain the correct keys.

icinga_hosts(target_hosts: TypeHosts, *, verbatim_hosts: bool = False) → IcingaHosts[source]¶

Get an IcingaHosts instance.

Note

To interact with both Icinga and Alertmanager alerts, use spicerack.Spicerack.alerting_hosts() instead.

Parameters:

target_hosts (spicerack.typing.TypeHosts) -- the target hosts either as a NodeSet instance or a sequence of strings.
verbatim_hosts (bool, optional) -- if True use the hosts passed verbatim as is, if instead False, the default, consider the given target hosts as FQDNs and extract their hostnames to be used in Icinga.

Returns:

IcingaHosts instance.

Return type:

spicerack.icinga.IcingaHosts

ipmi(target: str) → Ipmi[source]¶

Get an Ipmi instance to send remote IPMI commands to management consoles.

Parameters:: target (str) -- the management console FQDN or IP to target.
Returns:: the instance to run ipmitool commands.
Return type:: spicerack.ipmi.Ipmi

kafka() → Kafka[source]¶

Get an instance to interact with Kafka.

Returns:: the instance
Return type:: spicerack.kafka.Kafka
Raises:: KeyError -- If the configuration file does not contain the correct keys.

kubernetes(group: str, cluster: str) → Kubernetes[source]¶

Get a kubernetes client for the specified cluster.

Parameters:

group (str) -- the cluster group
cluster (str) -- the kubernetes cluster

Returns:

a pre-configured kubernetes client

Return type:

spicerack.k8s.Kubernetes

mediawiki() → MediaWiki[source]¶

Get a MediaWiki instance.

Returns:: the MediaWiki instance.
Return type:: spicerack.mediawiki.MediaWiki

mysql() → Mysql[source]¶

Get a Mysql instance.

Returns:: the Mysql instance.
Return type:: spicerack.mysql.Mysql

mysql_legacy() → MysqlLegacy[source]¶

Get a MysqlLegacy instance.

Returns:: the MysqlLegacy instance.
Return type:: spicerack.mysql_legacy.MysqlLegacy

netbox(*, read_write: bool = False) → Netbox[source]¶

Get a Netbox instance to interact with Netbox's API.

Parameters:: read_write (bool, optional) -- whether to use a read-write token.
Returns:: the instance
Return type:: spicerack.netbox.Netbox

netbox_server(hostname: str, *, read_write: bool = False) → NetboxServer[source]¶

Get a NetboxServer instance to interact with a server in Netbox, both physical and virtual.

Parameters:

hostname (str) -- the hostname (not FQDN) of the server to manage.
read_write (bool, optional) -- whether to use a read-write token.

Raises:

spicerack.netbox.NetboxError -- if unable to find or load the server.

Returns:

the NetboxServer instance.

Return type:

spicerack.netbox.NetboxServer

peeringdb(*, ttl: int = 86400) → PeeringDB[source]¶

Get a PeeringDB instance to interact with the PeeringDB API.

Parameters:: ttl (int) -- the cache timeout in seconds. If cached items are older than the given TTL they will be ignored and fetched again.
Returns:: the instance.
Return type:: spicerack.peringdb.PeeringDB

phabricator(bot_config_file: str, section: str = 'phabricator_bot') → Phabricator[source]¶

Get a Phabricator instance to interact with a Phabricator website.

Parameters:

bot_config_file (str) --
the path to the configuration file for the Phabricator bot, with the following structure:
```
[section_name]
host = https://phabricator.example.com/api/
username = phab-bot
token = api-12345
```
section (str, optional) -- the name of the section of the configuration file where to find the required parameters.

Returns:

the instance.

Return type:

wmflib.phabricator.Phabricator

prometheus() → Prometheus[source]¶

Get a Prometheus instance.

Returns:: Prometheus instance.
Return type:: wmflib.prometheus.Prometheus

puppet(remote_hosts: RemoteHosts) → PuppetHosts[source]¶

Get a PuppetHosts instance for the given remote hosts.

Parameters:: remote_hosts (spicerack.remote.RemoteHosts) -- the instance with the target hosts.
Returns:: the instance to manage Puppet on the target hosts.
Return type:: spicerack.puppet.PuppetHosts

puppet_master() → PuppetMaster[source]¶

Get a PuppetMaster instance to manage hosts and certificates from a Puppet master.

Returns:: the instance to manage Puppet hosts and certificates.
Return type:: spicerack.puppet.PuppetMaster

redfish(hostname: str, username: str = 'root', password: str = '') → Redfish[source]¶

Get an instance to talk to the Redfish API of a physical server.

Notes

At the moment only Dell hardware is supported.

Parameters:

hostname (str) -- the hostname (not FQDN) of the physical server to manage.
username (str, optional) -- the username for the management console.
password (str, optional) -- the password for the management console for the given user. If empty or not provided would use the production management password and ask the user for it if not already in memory.

Raises:

spicerack.exceptions.SpicerackError -- if not a physical server or unable to find the management IP.

Returns:

the instance.

Return type:

spicerack.redfish.Redfish

redis_cluster(cluster: str) → RedisCluster[source]¶

Get a RedisCluster instance.

Parameters:: cluster (str) -- the name of the cluster.
Returns:: the cluster instance.
Return type:: spicerack.redis_cluster.RedisCluster

remote(installer: bool = False) → Remote[source]¶

Get a Remote instance.

Parameters:: installer (bool, optional) -- whether to use the special configuration to connect to a Debian installer or freshly re-imaged host prior to its first Puppet run.
Returns:: the Remote instance.
Return type:: spicerack.remote.Remote

reposync(name: str) → RepoSync[source]¶

Get a Reposync instance.

Parameters:: name (str) -- the name of the repo to sync.
Returns:: the reposync instance.
Return type:: spicerack.reposync.RepoSync

requests_session(name: str, **kwargs: Any) → Session[source]¶

Return a new requests Session with timeout and retry logic.

Params:: according to wmflib.requests.http_session().

Returns:: the pre-configured session.
Return type:: requests.Session

run_cookbook(cookbook: str, args: Sequence[str] = ()) → int[source]¶

Run another Cookbook within the current run.

The other Cookbook will be executed with the current setup and will log in the same file of the current Cookbook that is running.

Parameters:

cookbook (str) -- the path to the cookbook to execute, either in Spicerack's dot notation or the relative path to the Python file to execute.
args (sequence, optional) -- an iterable sequence of strings with the Cookbook's argument. The Cookbook will be executed with the same global arguments used for the current run.

Returns:

the exit code of the Cookbook, 0 if successful, non-zero if not.

Return type:

int

Raises:

spicerack.exceptions.SpicerackError -- if the get_cookbook_callback callback is not set or unable to find the cookbook with the given name.

service_catalog() → Catalog[source]¶

Get a Catalog instance that reflects Puppet's service::catalog hieradata variable.

Returns:: the service catalog instance.
Return type:: spicerack.service.Catalog

thanos() → Thanos[source]¶

Get a Thanos instance.

Returns:: Thanos instance.
Return type:: wmflib.prometheus.Thanos

property actions: ActionsDict¶

Getter for the actions property.

Returns:: a dictionary to log and record cookbook actions.
Return type:: wmflib.actions.ActionsDict

property authdns_servers: Dict[str, str]¶

Getter for the authoritative DNS nameservers currently active in production.

Returns:: a dictionary where keys are the hostnames and values are the IPs of the active authoritative nameservers.
Return type:: dict

property config_dir: Path¶

Getter for Spicerack's configuration file directory.

Returns:: a filesystem location of configuration files.
Return type:: str

property dry_run: bool¶

Getter for the dry_run property.

Returns:: True if the DRY-RUN mode is set, False otherwise.
Return type:: bool

property http_proxy: str¶

Getter for the HTTP PROXY to use for external calls.

Returns:: the scheme://url:port of the proxy.
Return type:: str

property icinga_master_host: RemoteHosts¶

Getter for the icinga_master_host property.

Returns:: the instance to execute commands on the Icinga master host.
Return type:: spicerack.remote.RemoteHosts

property irc_logger: Logger¶

Getter for the irc_logger property.

Returns:: the logger instance to write to IRC.
Return type:: logging.Logger

property management_password: str¶

Getter for the management_password property.

Returns:: the management password. It will be asked to the user if not already cached by the current instance.
Return type:: str

property netbox_master_host: RemoteHosts¶

Getter for the netbox_master_host property.

Returns:: the instance to execute commands on the Netbox master host.
Return type:: spicerack.remote.RemoteHosts

property requests_proxies: Dict[str, str] | None¶

Getter to return the HTTP proxy configuration for the Requests module.

Returns:: with the proxies as required by Requests documentation. None: if no HTTP proxy is set.
Return type:: dict