puppet

Puppet module.

exception spicerack.puppet.PuppetHostsCheckError[source]

Bases: SpicerackCheckError

Custom base exception class for check errors in the PuppetHosts class.

exception spicerack.puppet.PuppetHostsError[source]

Bases: SpicerackError

Custom base exception class for errors in the PuppetHosts class.

exception spicerack.puppet.PuppetServerCheckError[source]

Bases: SpicerackCheckError

Custom exception class for check errors in the PuppetMaster class.

exception spicerack.puppet.PuppetServerError[source]

Bases: SpicerackError

Custom base exception class for errors in the PuppetMaster class.

class spicerack.puppet.PuppetHosts(remote_hosts: spicerack.remote.RemoteHosts) → None[source]

Bases: RemoteHostsAdapter

Class to manage Puppet on the target hosts.

Initialize the instance.

Parameters:: remote_hosts (spicerack.remote.RemoteHosts) -- the instance to act on the remote hosts.

check_disabled() → None[source]

Check if Puppet is disabled on all hosts.

Raises:: spicerack.puppet.PuppetHostsCheckError -- if Puppet is enabled on some hosts.
Return type:: None

check_enabled() → None[source]

Check if Puppet is enabled on all hosts.

Raises:: spicerack.puppet.PuppetHostsCheckError -- if Puppet is disabled on some hosts.
Return type:: None

disable(reason: spicerack.administrative.Reason, verbatim_reason: bool = False) → None[source]

Disable puppet with a specific reason.

If Puppet was already disabled on a host with a different reason, the reason will not be overriden, allowing to leave Puppet disabled when re-enabling it if it was already disabled.

Parameters:

reason (spicerack.administrative.Reason) -- the reason to set for the Puppet disable.
verbatim_reason (bool, default: False) -- if true use the reason value verbatim.

Return type:

None

disabled(reason: spicerack.administrative.Reason, verbatim_reason: bool = False) → collections.abc.Iterator[None][source]

Context manager to perform actions while puppet is disabled.

Parameters:

reason (spicerack.administrative.Reason) -- the reason to set for the Puppet disable and to use for the Puppet enable.
verbatim_reason (bool, default: False) -- if true use the reason value verbatim.

Return type:

collections.abc.Iterator[None]

enable(reason: spicerack.administrative.Reason, verbatim_reason: bool = False) → None[source]

Enable Puppet with a specific reason, it must be the same used to disable it.

Puppet will be re-enabled only if it was disable with the same reason. If it was disable with a different reason it will keep being disabled.

Parameters:

reason (spicerack.administrative.Reason) -- the reason to use for the Puppet enable.
verbatim_reason (bool, default: False) -- if true use the reason value verbatim.

Return type:

None

first_run(has_systemd: bool = True) → collections.abc.Iterator[tuple][source]

Perform the first Puppet run on a clean host without using custom wrappers.

Parameters:: has_systemd (bool, default: True) -- if the host has systemd as init system.
Return type:: collections.abc.Iterator[tuple]

get_ca_servers() → dict[str, str][source]

Retrieve the ca_servers for each node.

Return type:: dict[str, str]

get_config(config: str, *, section: str = 'agent') → dict[str, str][source]

Retrieve the ca_servers for each node.

Return type:: dict[str, str]

regenerate_certificate() → dict[str, str][source]

Delete the local Puppet certificate and generate a new CSR.

Return type:: dict[str, str]
Returns:: A dictionary with hostnames as keys and CSR fingerprint as values.

run(*, timeout: int = 300, enable_reason: spicerack.administrative.Reason | None = None, quiet: bool = False, failed_only: bool = False, force: bool = False, attempts: int = 0, batch_size: int = 10) → None[source]

Run Puppet.

Parameters:

timeout (int, default: 300) -- the timeout in seconds to set in Cumin for the execution of the command.
enable_reason (typing.Optional[spicerack.administrative.Reason], default: None) -- the reason to use to contextually re-enable Puppet if it was disabled.
quiet (bool, default: False) -- suppress Puppet output if True.
failed_only (bool, default: False) -- run Puppet only if the last run failed.
force (bool, default: False) -- forcely re-enable Puppet if it was disabled with ANY message.
attempts (int, default: 0) -- override the default number of attempts waiting that an in-flight Puppet run completes before timing out as set in run-puppet-agent.
batch_size (int, default: 10) -- how many concurrent Puppet runs to perform. The default value is tailored to not overload the Puppet masters.

Return type:

None

wait() → None[source]

Wait until the next successful Puppet run is completed.

Return type:: None

wait_since(start: datetime.datetime) → None[source]

Wait until a successful Puppet run is completed after the start time.

Parameters:: start (datetime.datetime) -- wait until a Puppet run is completed after this time.
Raises:: spicerack.puppet.PuppetHostsCheckError -- if unable to get a successful Puppet run within the timeout.
Return type:: None

class spicerack.puppet.PuppetMaster(server_host: spicerack.remote.RemoteHosts) → None[source]

Bases: PuppetServer

Class to manage nodes and certificates on a Puppet master and Puppet CA server.

Initialize the instance.

Parameters:: server_host (spicerack.remote.RemoteHosts) -- the remote hosts instance for the Puppetserver and Puppet CA server. It must have only one target host.
Raises:: spicerack.puppet.PuppetServerError -- if the server_host doesn't have only one target host.

destroy(hostname: str) → None[source]

Remove the certificate for the given hostname.

If there is no certificate to remove it doesn't raise exception as the Puppet CA just outputs 'Nothing was deleted'.

Parameters:: hostname (str) -- the FQDN of the host for which to remove the certificate.
Return type:: None

get_certificate_metadata(hostname: str) → dict[source]

Return the metadata of the certificate of the given hostname in the Puppet CA.

Parameters:

hostname (str) -- the FQDN of the host for which to verify the certificate.

Return type:

dict

Returns:

As returned by the Puppet CA CLI with the render as JSON option set. As example:

{
    'dns_alt_names': ['DNS:service.example.com'],
    'fingerprint': '00:FF:...',
    'fingerprints': {
        'SHA1': '00:FF:...',
        'SHA256': '00:FF:...',
        'SHA512': '00:FF:...',
        'default': '00:FF:...',
    },
    'name': 'host.example.com',
    'state': 'signed',
}

Raises:

spicerack.puppet.PuppetServerCheckError -- if no certificate is found.
spicerack.puppet.PuppetServerError -- if more than one certificate is found or it has invalid data.

sign(hostname: str, fingerprint: str) → None[source]

Sign a CSR on the Puppet CA for the given host checking its fingerprint.

Parameters:

hostname (str) -- the FQDN of the host for which to sign the certificate.
fingerprint (str) -- the fingerprint of the CSR generated on the client to verify it.

Raises:

spicerack.puppet.PuppetServerError -- if the certificate is in an unexpected state.

Return type:

None

verify(hostname: str) → None[source]

Verify that there is a valid certificate signed by the Puppet CA for the given hostname.

Parameters:: hostname (str) -- the FQDN of the host for which to verify the certificate.
Raises:: spicerack.puppet.PuppetServerError -- if the certificate is not valid.
Return type:: None

property master_host: RemoteHosts: Accessor for the master_host property.

class spicerack.puppet.PuppetServer(server_host: spicerack.remote.RemoteHosts) → None[source]

Bases: RemoteHostsAdapter

Class to manage nodes and certificates on a Puppet server and Puppet CA server.

Initialize the instance.

Parameters:: server_host (spicerack.remote.RemoteHosts) -- the remote hosts instance for the Puppetserver and Puppet CA server. It must have only one target host.
Raises:: spicerack.puppet.PuppetServerError -- if the server_host doesn't have only one target host.

delete(hostname: str) → None[source]

Remove the host from the Puppet server and PuppetDB.

Clean up signed certs, cached facts, node objects, and reports in the Puppet server, deactivate it in PuppetDB. Doesn't raise exception if the host was already removed.

Parameters:: hostname (str) -- the FQDN of the host for which to remove the certificate.
Return type:: None

destroy(hostname: str) → None[source]

Remove the certificate for the given hostname.

If there is no certificate to remove it doesn't raise exception.

Parameters:: hostname (str) -- the FQDN of the host for which to remove the certificate.
Raises:: spicerack.remote.RemoteExecutionError -- if unable to destroy the certificate.
Return type:: None

get_certificate_metadata(hostname: str) → dict[source]

Return the metadata of the certificate of the given hostname in the Puppet CA.

Parameters:

hostname (str) -- the FQDN of the host for which to verify the certificate.

Return type:

dict

Returns:

As returned by the Puppet CA CLI with the render as JSON option set. As example:

{
    'dns_alt_names': ['DNS:service.example.com'],
    'fingerprint': '00:FF:...',
    'fingerprints': {
        'SHA1': '00:FF:...',
        'SHA256': '00:FF:...',
        'SHA512': '00:FF:...',
        'default': '00:FF:...',
    },
    'name': 'host.example.com',
    'state': 'signed',
}

Raises:

spicerack.puppet.PuppetServerCheckError -- if no certificate is found.
spicerack.puppet.PuppetServerError -- if more than one certificate is found or it has invalid data.

hiera_lookup(fqdn: str, key: str, *, fmt: str = 's') → str[source]

Lookup a hiera value for a specific host.

Parameters:

fqdn (str) -- the fqdn whose values we are looking up
key (str) -- the hiera key to lookup
fmt (str, default: 's') -- how Puppet will render the object: 's' (PSON, default), 'json', 'yaml'

Return type:

str

sign(hostname: str, fingerprint: str) → None[source]

Sign a CSR on the Puppet CA for the given host checking its fingerprint.

Parameters:

hostname (str) -- the FQDN of the host for which to sign the certificate.
fingerprint (str) -- the fingerprint of the CSR generated on the client to verify it.

Raises:

spicerack.puppet.PuppetServerError -- if the certificate is in an unexpected state.

Return type:

None

verify(hostname: str) → None[source]

Verify that there is a valid certificate signed by the Puppet CA for the given hostname.

Parameters:: hostname (str) -- the FQDN of the host for which to verify the certificate.
Raises:: spicerack.puppet.PuppetServerError -- if the certificate is not valid.
Return type:: None

wait_for_csr(hostname: str) → None[source]

Poll until a CSR appears for the given hostname or the timeout is reached.

Parameters:

hostname (str) -- the FQDN of the host for which to check a CSR.

Raises:

spicerack.puppet.PuppetServerError -- if the certificate is in an unexpected state.
spicerack.puppet.PuppetServerCheckError -- if within the timeout no CSR is found.

Return type:

None

PUPPET_CERT_STATE_REQUESTED: str = 'requested': Puppet CA certificate status when requested.

PUPPET_CERT_STATE_SIGNED: str = 'signed': Puppet CA certificate status when signed.

property server_host: RemoteHosts: Accessor for the server_host property.

spicerack.puppet.get_ca_via_srv_record(domain: str) → str[source]

Lookup the CA Server via the domain srv record.

Return type:: str

spicerack.puppet.get_puppet_ca_hostname() → str[source]

Return the FQDN of the current Puppet CA server.

Raises:: spicerack.puppet.PuppetServerError -- if unable to get the configured Puppet CA server.
Return type:: str

spicerack.puppet.PUPPET_COMMON_SCRIPT: str = '/usr/local/share/bash/puppet-common.sh': The absolute path of the puppet-common script shipped by Puppet with useful functions.