service¶
Service module.
- exception spicerack.service.DiscoveryRecordNotFoundError[source]¶
Bases:
spicerack.service.ServiceError
Exception class raised when a DNS Discovery record is not found by name or there is none.
- exception spicerack.service.ServiceError[source]¶
Bases:
spicerack.exceptions.SpicerackError
Generic exception class for errors in the service module.
- exception spicerack.service.ServiceNotFoundError[source]¶
Bases:
spicerack.service.ServiceError
Exception class raised when a service is not found.
- exception spicerack.service.TooManyDiscoveryRecordsError[source]¶
Bases:
spicerack.service.ServiceError
Exception class raised when more than one DNS Discovery record is present but not name was specified.
- class spicerack.service.Catalog(catalog: Dict, confctl: spicerack.confctl.ConftoolEntity, remote: spicerack.remote.Remote, dry_run: bool = True)[source]¶
Bases:
object
Class to represent the service catalog of Puppet's hierdata
service::catalog
.The catalog behaves like an Iterator, so it can be iterated in list-comprehension and similar contructs. It supports also
len()
, to quickly know how many services are loaded in the catalog.Examples
Get all service that are present in a given datacenter:
>>> esams = [service for service in catalog if "esams" in service.sites]
See how many services are configured:
>>> num_services = len(catalog)
Initialize the instance.
- Parameters
catalog (dict) -- the content of Puppet's
hieradata/common/service.yaml
.confctl (spicerack.confctl.ConftoolEntity) -- the instance to interact with confctl.
remote (spicerack.remote.Remote) -- the instance to execute remote commands.
dry_run (bool, optional) -- whether this is a DRY-RUN.
- get(name: str) spicerack.service.Service [source]¶
Get a single service by name.
Examples
Get a specific service:
>>> service = catalog.get("service_name")
- Parameters
name (str) -- the service name.
- Raises
spicerack.service.ServiceNotFoundError -- if the service is not found.
- Returns
the instance of the matched service.
- Return type
- class spicerack.service.Service(name: str, description: str, encryption: bool, ip: spicerack.service.ServiceIPs, port: int, sites: List[str], state: str, _alertmanager: spicerack.alertmanager.AlertmanagerHosts, aliases: List[str] = <factory>, discovery: Optional[spicerack.service.ServiceDiscovery] = None, lvs: Optional[spicerack.service.ServiceLVS] = None, monitoring: Optional[spicerack.service.ServiceMonitoring] = None, page: bool = True, probes: List[Dict] = <factory>, public_aliases: List[str] = <factory>, public_endpoint: str = '', role: str = '')[source]¶
Bases:
object
Class to represent a service as defined in Puppet's
service::catalog
hieradata.See also
Puppet's
modules/wmflib/types/service.pp
.- Parameters
name (str) -- the service name.
description (str) -- the service description.
encryption (bool) -- whether TLS encryption is enabled or not on the service.
ip (spicerack.service.ServiceIPs) -- the instance that represents all the service IPs.
port (int) -- the port the service listen on.
sites (list) -- the list of datacenters where the service is configured.
state (str) -- the production state of the service (e.g.
lvs_setup
).(spicerack.alertmanager (_alertmanager) -- AlertmanagerHosts): the AlertmanagerHosts instance to perform downtime.
aliases (list, optional) -- a list of aliases names for the service.
discovery (spicerack.service.ServiceDiscovery, optional) -- the collection of
spicerack.service.ServiceDiscoveryRecord
instances reprensenting the DNS Discovery capabilities of the service.lvs (spicerack.service.ServiceLVS, optional) -- the load balancer configuration.
monitoring (spicerack.service.ServiceMonitoring, optional) -- the service monitoring configuration.
page (bool, optional) -- whether the monitoring for this service does page or not.
probes (list, optional) -- a list of probe dictionaries with all the parameters necessary to define the probes for this service.
public_aliases (list, optional) -- the list of public aliases set for this service.
public_endpoint (str, optional) -- the name of the public endpoint if present, empty string otherwise.
role (str, optional) -- the service role name in Puppet if present, empty string otherwise.
- downtime(site: str, reason: spicerack.administrative.Reason, *, duration: datetime.timedelta = datetime.timedelta(seconds=14400)) str [source]¶
Downtime the service on the given site in Alertmanager.
- Parameters
site (str) -- the datacenter where to silence the service.
reason (spicerack.administrative.Reason) -- the silence reason.
duration (datetime.timedelta, optional) -- how long to silence for.
- Raises
spicerack.service.ServiceError -- if the service is not present in the given datacenter.
- Returns
the downtime ID.
- Return type
- downtimed(site: str, reason: spicerack.administrative.Reason, *, duration: datetime.timedelta = datetime.timedelta(seconds=14400), remove_on_error: bool = False) Iterator[None] [source]¶
Context manager to perform actions while the service is downtimed in the given site in Alertmanager.
- Parameters
site (str) -- the datacenter where to silence the service.
reason (spicerack.administrative.Reason) -- the silence reason.
duration (datetime.timedelta, optional) -- how long to silence for.
remove_on_error (bool, optional) -- should the downtime be removed even if an exception was raised.
- Raises
spicerack.service.ServiceError -- if the service is not present in the given datacenter.
- class spicerack.service.ServiceDiscovery(records: Sequence[spicerack.service.ServiceDiscoveryRecord])[source]¶
Bases:
collections.abc.Iterable
Represents the service Discovery records collection as list-like object with helper methods.
The discovery behaves like an Iterator, so it can be iterated in list-comprehension and similar contructs. It supports also
len()
, to quickly know how many records are configured for the service.Initialize the instance with the records.
- Parameters
records (iterable, optional) -- the DNS Discovery records.
- depool(site: str, *, name: str = '') None [source]¶
Depool the service from the given site in DNS Discovery.
- Parameters
- Raises
spicerack.service.DiscoveryRecordNotFoundError -- if there are no records at all or the record with the given
name can't be found. --
spicerack.service.TooManyDiscoveryRecordsError -- if the name is an empty string and there is more than one
record. --
- depooled(site: str, *, name: str = '', repool_on_error: bool = False) Iterator[None] [source]¶
Context manager to act while the service is depooled from the given site in DNS Discovery.
It will not repool the service on the given site if any exception is raised within the context manager context, unless
repool_on_error
is set toTrue
.- Parameters
- Yields
None
- Raises
spicerack.service.DiscoveryRecordNotFoundError -- if there are no records at all or the record with the given
name can't be found. --
spicerack.service.TooManyDiscoveryRecordsError -- if the name is an empty string and there is more than one
record. --
- get(name: str = '') spicerack.service.ServiceDiscoveryRecord [source]¶
Return the DNS Discovery record for the given name, raise an exception if not found.
- Parameters
name (str, optional) -- the dnsdic name of the DNS Discovery record. If set to an empty string, and the service has only one service, it will return that one.
- Raises
spicerack.service.DiscoveryRecordNotFoundError -- if there are no records at all or the record with the given
name can't be found. --
spicerack.service.TooManyDiscoveryRecordsError -- if the name is an empty string and there is more than one
record. --
- pool(site: str, *, name: str = '') None [source]¶
Pool the service to the given site in DNS Discovery.
- Parameters
- Raises
spicerack.service.DiscoveryRecordNotFoundError -- if there are no records at all or the record with the given
name can't be found. --
spicerack.service.TooManyDiscoveryRecordsError -- if the name is an empty string and there is more than one
record. --
- class spicerack.service.ServiceDiscoveryRecord(active_active: bool, dnsdisc: str, instance: spicerack.dnsdisc.Discovery)[source]¶
Bases:
object
Represents the DNS Discovery attributes of the service.
See also
Puppet's
modules/wmflib/types/service/discovery.pp
.- Parameters
active_active (bool) --
True
if the service is active/active in DNS Discovery.dnsdisc (str) -- the name used in conftool for the discovery record.
instance (spicerack.dnsdisc.Discovery) -- the DNS Discovery intance to operate on the service.
- class spicerack.service.ServiceIPs(data: Dict[str, Dict[str, str]])[source]¶
Bases:
object
Represent the service IPs.
See also
Puppet's
modules/wmflib/types/service/ipblock.pp
.- Parameters
data (dict) -- a dictionary representing the service IPs data as defined in
service::catalog
.
- get(site: str, label: str = 'default') Optional[Union[ipaddress.IPv4Address, ipaddress.IPv6Address]] [source]¶
Get the IP for a given datacenter and optional label.
- Parameters
- Returns
if the matched IP is an IPv4. ipaddress.IPv6Address: if the matched IP is an IPv6. None: if there is no IP matching the criteria.
- Return type
- property all: List[Union[ipaddress.IPv4Address, ipaddress.IPv6Address]]¶
Return all service IPs.
- Returns
a list of IP addresses.
- Return type
- class spicerack.service.ServiceLVS(conftool: spicerack.service.ServiceLVSConftool, depool_threshold: str, enabled: bool, lvs_class: str, monitors: Dict[str, Dict], bgp: bool = True, protocol: str = 'tcp', scheduler: str = 'wrr')[source]¶
Bases:
object
Represent the load balancer configuration for the service.
See also
Puppet's
modules/wmflib/types/service/lvs.pp
.- Parameters
conftool (spicerack.service.ServiceLVSConftool) -- the conftool configuration for the service.
depool_threshold (str) -- the percentage of the cluster that Pybal will keep pooled anyway on failure.
enabled (bool) -- whether the service is enabled on the load balancers.
lvs_class (str) -- the traffic class of the service (e.g.
low-traffic
).monitors (dict) -- a dictionary of Pybal monitors configured for the service.
bgp (bool, optional) -- whether Pybal advertise the service via BGP or not.
protocol (str, optional) -- the Internet protocol of the service.
scheduler (str, optional) -- the IPVS scheduler used for the service.
- class spicerack.service.ServiceLVSConftool(cluster: str, service: str)[source]¶
Bases:
object
Represent the conftool configuration for the service for the load balancers.
- class spicerack.service.ServiceMonitoring(check_command: str, sites: spicerack.service.ServiceMonitoringHostnames, contact_group: str = '', notes_url: str = '')[source]¶
Bases:
object
Represent the monitoring configuration for the service.
See also
Puppet's
modules/wmflib/types/service/monitoring.pp
.- Parameters
check_command (str) -- the Icinga check command used to monitor the service.
sites (spicerack.service.ServiceMonitoringHostnames) -- the FQDNs used to monitor the service in each datacenter.
contact_group (str, optional) -- the name of the Icinga contact group used for the service.
notes_url (str, optional) -- the Icinga notes URL pointing to the service runbook.
- class spicerack.service.ServiceMonitoringHostnames(data: Dict[str, Dict[str, str]])[source]¶
Bases:
object
Represent the Icinga hostnames or FQDNs used to monitor the service in each datacenter.
See also
Puppet's
modules/wmflib/types/service/monitoring.pp
.- Parameters
data (dict) -- the service monitoring dictionary.
- get(site: str) str [source]¶
Get the monitoring hostname/FQDN for the service in the given datacenter.
- Returns
the hostname/FQDN for the given datacenter if configured, empty string otherwise.
- Return type