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 ifexternal_modules_dir
is specified in the configuration.
- admin_reason(reason: str, task_id: str | None = None) Reason [source]¶
Get an administrative Reason instance.
- Parameters:
- Returns:
the administrative Reason instance.
- Return type:
- 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 insteadFalse
, the default, consider the given target hosts as FQDNs and extract their hostnames to be used in Icinga.
- Returns:
AlertingHosts instance.
- Return type:
- alertmanager() Alertmanager [source]¶
Get an Alertmanager instance.
Note
To interact with Alertmanager alerts attached to an
instance
usespicerack.Spicerack.alertmanager_hosts()
instead.- Returns:
the Alertmanager instance.
- Return type:
- 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 insteadFalse
, the default, consider the given target hosts as FQDNs and extract their hostnames to be used in Icinga.
- Returns:
the AlertmanagerHosts instance.
- Return type:
- 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:
- debmonitor() Debmonitor [source]¶
Get a Debmonitor instance to interact with a Debmonitor website.
- Returns:
the instance.
- Return type:
- 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:
- 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:
- dns() Dns [source]¶
Get a Dns instance.
- Returns:
a Dns instance that will use the operating system default namserver(s).
- Return type:
- elasticsearch_clusters(clustergroup: str, write_queue_datacenters: Sequence[str]) ElasticsearchClusters [source]¶
Get an ElasticsearchClusters instance.
- Parameters:
- Returns:
ElasticsearchClusters instance.
- Return type:
- 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:
- 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 insteadFalse
, the default, consider the given target hosts as FQDNs and extract their hostnames to be used in Icinga.
- Returns:
IcingaHosts instance.
- Return type:
- 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:
- kafka() Kafka [source]¶
Get an instance to interact with Kafka.
- Returns:
the instance
- Return type:
- 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:
- Returns:
a pre-configured kubernetes client
- Return type:
- mediawiki() MediaWiki [source]¶
Get a MediaWiki instance.
- Returns:
the MediaWiki instance.
- Return type:
- mysql_legacy() MysqlLegacy [source]¶
Get a MysqlLegacy instance.
- Returns:
the MysqlLegacy instance.
- Return type:
- 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:
- 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:
- Raises:
spicerack.netbox.NetboxError -- if unable to find or load the server.
- Returns:
the NetboxServer instance.
- Return type:
- 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:
- prometheus() Prometheus [source]¶
Get a Prometheus instance.
- Returns:
Prometheus instance.
- Return type:
- 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:
- 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:
- 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:
- redis_cluster(cluster: str) RedisCluster [source]¶
Get a RedisCluster instance.
- Parameters:
cluster (str) -- the name of the cluster.
- Returns:
the cluster instance.
- Return type:
- 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:
- 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:
- 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:
- 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:
- 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:
- property actions: ActionsDict¶
Getter for the
actions
property.- Returns:
a dictionary to log and record cookbook actions.
- Return type:
- 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:
- property config_dir: Path¶
Getter for Spicerack's configuration file directory.
- Returns:
a filesystem location of configuration files.
- Return type:
- property dry_run: bool¶
Getter for the
dry_run
property.- Returns:
True if the DRY-RUN mode is set, False otherwise.
- Return type:
- property http_proxy: str¶
Getter for the HTTP PROXY to use for external calls.
- Returns:
the scheme://url:port of the proxy.
- Return type:
- 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:
- property irc_logger: Logger¶
Getter for the
irc_logger
property.- Returns:
the logger instance to write to IRC.
- Return type:
- 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:
- 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:
- property requests_proxies: Dict[str, str] | None¶
Getter to return the HTTP proxy configuration for the Requests module.
- class spicerack.SpicerackExtenderBase(*, spicerack: Spicerack)[source]¶
Bases:
object
Base class to create a Spicerack extender. Necessary when the
external_modules_dir
configuration is set.Initialize the instance.
- Parameters:
spicerack (spicerack.Spicerack) -- the Spicerack instance.
Subpackages and Submodules
- administrative
- alerting
- alertmanager
- confctl
- constants
- cookbook
- debmonitor
- decorators
- dhcp
- dnsdisc
- elasticsearch_cluster
ElasticsearchClusterCheckError
ElasticsearchClusterError
ElasticsearchCluster
ElasticsearchCluster.check_green()
ElasticsearchCluster.check_yellow_w_no_moving_shards()
ElasticsearchCluster.flush_markers()
ElasticsearchCluster.force_allocation_of_all_unassigned_shards()
ElasticsearchCluster.frozen_writes()
ElasticsearchCluster.get_nodes()
ElasticsearchCluster.is_node_in_cluster_nodes()
ElasticsearchCluster.reset_indices_to_read_write()
ElasticsearchCluster.stopped_replication()
ElasticsearchClusters
ElasticsearchClusters.flush_markers()
ElasticsearchClusters.force_allocation_of_all_unassigned_shards()
ElasticsearchClusters.frozen_writes()
ElasticsearchClusters.get_next_clusters_nodes()
ElasticsearchClusters.reset_indices_to_read_write()
ElasticsearchClusters.stopped_replication()
ElasticsearchClusters.wait_for_all_write_queues_empty()
ElasticsearchClusters.wait_for_green()
ElasticsearchClusters.wait_for_yellow_w_no_moving_shards()
ElasticsearchHosts
NodesGroup
create_elasticsearch_clusters()
- exceptions
- ganeti
- icinga
IcingaCheckError
IcingaError
IcingaStatusNotFoundError
IcingaStatusParseError
CommandFile
HostStatus
HostsStatus
IcingaHosts
IcingaHosts.downtime()
IcingaHosts.downtime_services()
IcingaHosts.downtimed()
IcingaHosts.get_status()
IcingaHosts.recheck_all_services()
IcingaHosts.recheck_failed_services()
IcingaHosts.remove_downtime()
IcingaHosts.remove_service_downtimes()
IcingaHosts.run_icinga_command()
IcingaHosts.services_downtimed()
IcingaHosts.wait_for_downtimed()
IcingaHosts.wait_for_optimal()
IcingaStatus
ServiceStatus
- interactive
- ipmi
- k8s
- kafka
- mediawiki
MediaWikiCheckError
MediaWikiError
MediaWiki
MediaWiki.check_config_line()
MediaWiki.check_periodic_jobs_disabled()
MediaWiki.check_periodic_jobs_enabled()
MediaWiki.check_siteinfo()
MediaWiki.get_maintenance_host()
MediaWiki.get_master_datacenter()
MediaWiki.get_siteinfo()
MediaWiki.scap_sync_config_file()
MediaWiki.set_master_datacenter()
MediaWiki.set_readonly()
MediaWiki.set_readwrite()
MediaWiki.stop_periodic_jobs()
- mysql
- mysql_legacy
MysqlLegacyError
MysqlLegacy
MysqlLegacy.check_core_masters_heartbeats()
MysqlLegacy.check_core_masters_in_sync()
MysqlLegacy.get_core_dbs()
MysqlLegacy.get_core_masters_heartbeats()
MysqlLegacy.get_dbs()
MysqlLegacy.set_core_masters_readonly()
MysqlLegacy.set_core_masters_readwrite()
MysqlLegacy.verify_core_masters_readonly()
MysqlLegacy.heartbeat_query
MysqlLegacyRemoteHosts
CORE_SECTIONS
REPLICATION_ROLES
- netbox
- peeringdb
- puppet
- redfish
RedfishError
RedfishTaskNotCompletedError
ChassisResetPolicy
DellSCP
DellSCPPowerStatePolicy
DellSCPRebootPolicy
DellSCPTargetPolicy
Redfish
Redfish.change_user_password()
Redfish.chassis_reset()
Redfish.check_connection()
Redfish.find_account()
Redfish.get_power_state()
Redfish.last_reboot()
Redfish.most_recent_member()
Redfish.multipush_upload()
Redfish.poll_task()
Redfish.request()
Redfish.submit_files()
Redfish.submit_task()
Redfish.upload_file()
Redfish.wait_reboot_since()
Redfish.bios_version
Redfish.firmware_version
Redfish.hostname
Redfish.interface
Redfish.manufacturer
Redfish.model
Redfish.multipushuri
Redfish.oob_info
Redfish.oob_manager
Redfish.oob_model
Redfish.pushuri
Redfish.system_info
Redfish.system_manager
Redfish.update_service
Redfish.updateservice_info
RedfishDell
- redis_cluster
- remote
- reposync
- service
- toolforge
- toolforge.etcdctl
- typing