pyinfra 3.0b2__tar.gz → 3.0b3__tar.gz

{pyinfra-3.0b2 → pyinfra-3.0b3}/CHANGELOG.md

@@ -1,4 +1,4 @@
-# v3.0.beta2
+# v3.0.beta3
 
 Welcome to pyinfra v3! This version is the biggest overhaul of pyinfra since it was created back in 2015. Most v2 deployment code should be automatically compatible, but as always be aware. Major changes:
 

{pyinfra-3.0b2/pyinfra.egg-info → pyinfra-3.0b3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyinfra
-Version: 3.0b2
+Version: 3.0b3
 Summary: pyinfra automates/provisions/manages/deploys infrastructure.
 Home-page: https://pyinfra.com
 Author: Nick / Fizzadar
@@ -57,7 +57,7 @@ Requires-Dist: types-python-dateutil; extra == "test"
 Requires-Dist: types-PyYAML; extra == "test"
 Requires-Dist: types-setuptools; extra == "test"
 Provides-Extra: docs
-Requires-Dist: pyinfra-guzzle_sphinx_theme==0.15; extra == "docs"
+Requires-Dist: pyinfra-guzzle_sphinx_theme==0.16; extra == "docs"
 Requires-Dist: myst-parser==2.0.0; extra == "docs"
 Requires-Dist: sphinx==6.2.1; extra == "docs"
 Provides-Extra: dev
@@ -75,7 +75,7 @@ Requires-Dist: types-paramiko; extra == "dev"
 Requires-Dist: types-python-dateutil; extra == "dev"
 Requires-Dist: types-PyYAML; extra == "dev"
 Requires-Dist: types-setuptools; extra == "dev"
-Requires-Dist: pyinfra-guzzle_sphinx_theme==0.15; extra == "dev"
+Requires-Dist: pyinfra-guzzle_sphinx_theme==0.16; extra == "dev"
 Requires-Dist: myst-parser==2.0.0; extra == "dev"
 Requires-Dist: sphinx==6.2.1; extra == "dev"
 Requires-Dist: wheel; extra == "dev"

{pyinfra-3.0b2 → pyinfra-3.0b3}/pyinfra/facts/docker.py

@@ -86,3 +86,19 @@ class DockerNetwork(DockerSingleMixin):
     """
 
     docker_type = "network"
+
+
+class DockerVolumes(DockerFactBase):
+    """
+    Returns ``docker inspect`` output for all Docker volumes.
+    """
+
+    command = "docker volume inspect `docker volume ls -q`"
+
+
+class DockerVolume(DockerSingleMixin):
+    """
+    Returns ``docker inspect`` output for a single Docker container.
+    """
+
+    docker_type = "volume"

pyinfra-3.0b3/pyinfra/facts/runit.py

@@ -0,0 +1,68 @@
+from pyinfra.api import FactBase
+
+
+class RunitStatus(FactBase):
+    """
+    Returns a dict of name -> status for runit services.
+
+    + service: optionally check only for a single service
+    + svdir: alternative ``SVDIR``
+
+    .. code:: python
+
+        {
+            'agetty-tty1': True,     # service is running
+            'dhcpcd': False,         # service is down
+            'wpa_supplicant': None,  # service is managed, but not running or down,
+                                     # possibly in a fail state
+        }
+    """
+
+    requires_command = "sv"
+    default = dict
+
+    def command(self, service=None, svdir="/var/service"):
+        if service is None:
+            return (
+                'export SVDIR="{0}" && '
+                'cd "$SVDIR" && find * -maxdepth 0 -exec sv status {{}} + 2>/dev/null'
+            ).format(svdir)
+        else:
+            return 'SVDIR="{0}" sv status "{1}"'.format(svdir, service)
+
+    def process(self, output):
+        services = {}
+        for line in output:
+            statusstr, service, _ = line.split(sep=": ", maxsplit=2)
+            status = None
+
+            if statusstr == "run":
+                status = True
+            elif statusstr == "down":
+                status = False
+            # another observable state is "fail"
+            # report as ``None`` for now
+
+            services[service] = status
+
+        return services
+
+
+class RunitManaged(FactBase):
+    """
+    Returns a set of all services managed by runit
+
+    + service: optionally check only for a single service
+    + svdir: alternative ``SVDIR``
+    """
+
+    default = set
+
+    def command(self, service=None, svdir="/var/service"):
+        if service is None:
+            return 'cd "{0}" && find -mindepth 1 -maxdepth 1 -type l -printf "%f\n"'.format(svdir)
+        else:
+            return 'cd "{0}" && test -h "{1}" && echo "{1}" || true'.format(svdir, service)
+
+    def process(self, output):
+        return set(output)

pyinfra-3.0b3/pyinfra/operations/docker.py

@@ -0,0 +1,339 @@
+"""
+Manager Docker Containers, Volumes and Networks
+"""
+
+from pyinfra import host
+from pyinfra.api import operation
+from pyinfra.facts.docker import DockerContainers, DockerNetworks, DockerVolumes
+
+from .util.docker import handle_docker
+
+
+@operation()
+def container(
+    container,
+    image="",
+    ports=None,
+    networks=None,
+    volumes=None,
+    env_vars=None,
+    pull_always=False,
+    present=True,
+    force=False,
+    start=True,
+):
+    """
+    Manage Docker containers
+
+    + container: name to identify the container
+    + image: container image and tag ex: nginx:alpine
+    + networks: network list to attach on container
+    + ports: port list to expose
+    + volumes: volume list to map on container
+    + env_vars: environment varible list to inject on container
+    + pull_always: force image pull
+    + force: remove a contaner with same name and create a new one
+    + present: whether the container should be up and running
+    + start: start or stop the container
+
+    **Examples:**
+
+    .. code:: python
+
+        # Run a container
+        docker.container(
+            name="Deploy Nginx container",
+            container="nginx",
+            image="nginx:alpine",
+            ports=["80:80"],
+            present=True,
+            force=True,
+            networks=["proxy", "services"],
+            volumes=["nginx_data:/usr/share/nginx/html"],
+            pull_always=True,
+        )
+
+        # Stop a container
+        docker.container(
+            name="Stop Nginx container",
+            container="nginx",
+            start=False,
+        )
+
+        # Start a container
+        docker.container(
+            name="Start Nginx container",
+            container="nginx",
+            start=True,
+        )
+    """
+
+    existent_container = [c for c in host.get_fact(DockerContainers) if container in c["Name"]]
+
+    if force:
+        if existent_container:
+            yield handle_docker(
+                resource="container",
+                command="remove",
+                container=container,
+            )
+
+    if present:
+        if not existent_container or force:
+            yield handle_docker(
+                resource="container",
+                command="create",
+                container=container,
+                image=image,
+                ports=ports,
+                networks=networks,
+                volumes=volumes,
+                env_vars=env_vars,
+                pull_always=pull_always,
+                present=present,
+                force=force,
+                start=start,
+            )
+
+    if existent_container and start:
+        if existent_container[0]["State"]["Status"] != "running":
+            yield handle_docker(
+                resource="container",
+                command="start",
+                container=container,
+            )
+
+    if existent_container and not start:
+        if existent_container[0]["State"]["Status"] == "running":
+            yield handle_docker(
+                resource="container",
+                command="stop",
+                container=container,
+            )
+
+    if existent_container and not present:
+        yield handle_docker(
+            resource="container",
+            command="remove",
+            container=container,
+        )
+
+
+@operation(is_idempotent=False)
+def image(image, present=True):
+    """
+    Manage Docker images
+
+    + image: Image and tag ex: nginx:alpine
+    + present: whether the Docker image should be exist
+
+    **Examples:**
+
+    .. code:: python
+
+        # Pull a Docker image
+        docker.image(
+            name="Pull nginx image",
+            image="nginx:alpine",
+            present=True,
+        )
+
+        # Remove a Docker image
+        docker.image(
+            name="Remove nginx image",
+            image:"nginx:image",
+            present=False,
+        )
+    """
+
+    if present:
+        yield handle_docker(
+            resource="image",
+            command="pull",
+            image=image,
+        )
+
+    else:
+        yield handle_docker(
+            resource="image",
+            command="remove",
+            image=image,
+        )
+
+
+@operation()
+def volume(volume, driver="", labels=None, present=True):
+    """
+    Manage Docker volumes
+
+    + volume: Volume name
+    + driver: Docker volume storage driver
+    + labels: Label list to attach in the volume
+    + present: whether the Docker volume should exist
+
+    **Examples:**
+
+    .. code:: python
+
+        # Create a Docker volume
+        docker.volume(
+            name="Create nginx volume",
+            volume="nginx_data",
+            present=True
+        )
+    """
+
+    existent_volume = [v for v in host.get_fact(DockerVolumes) if v["Name"] == volume]
+
+    if present:
+
+        if existent_volume:
+            host.noop("Volume alredy exist!")
+            return
+
+        yield handle_docker(
+            resource="volume",
+            command="create",
+            volume=volume,
+            driver=driver,
+            labels=labels,
+            present=present,
+        )
+
+    else:
+        if existent_volume is None:
+            host.noop("There is no {0} volume!".format(volume))
+            return
+
+        yield handle_docker(
+            resource="volume",
+            command="remove",
+            volume=volume,
+        )
+
+
+@operation()
+def network(
+    network,
+    driver="",
+    gateway="",
+    ip_range="",
+    ipam_driver="",
+    subnet="",
+    scope="",
+    opts=None,
+    ipam_opts=None,
+    labels=None,
+    ingress=False,
+    attachable=False,
+    present=True,
+):
+    """
+    Manage docker networks
+
+    + network_name: Image name
+    + driver: Container image and tag ex: nginx:alpine
+    + gateway: IPv4 or IPv6 Gateway for the master subnet
+    + ip_range: Allocate container ip from a sub-range
+    + ipam_driver: IP Address Management Driver
+    + subnet: Subnet in CIDR format that represents a network segment
+    + scope: Control the network's scope
+    + opts: Set driver specific options
+    + ipam_opts: Set IPAM driver specific options
+    + labels: Label list to attach in the network
+    + ingress: Create swarm routing-mesh network
+    + attachable: Enable manual container attachment
+    + present: whether the Docker network should exist
+
+    **Examples:**
+
+    .. code:: python
+
+        # Create Docker network
+        docker.network(
+            name="Create nginx network",
+            network_name="nginx",
+            attachable=True,
+            present=True,
+        )
+    """
+    existent_network = [n for n in host.get_fact(DockerNetworks) if n["Name"] == network]
+
+    if present:
+        if existent_network:
+            host.noop("Alredy exist a network with {0} name!".format(network))
+            return
+
+        yield handle_docker(
+            resource="network",
+            command="create",
+            network=network,
+            driver=driver,
+            gateway=gateway,
+            ip_range=ip_range,
+            ipam_driver=ipam_driver,
+            subnet=subnet,
+            scope=scope,
+            opts=opts,
+            ipam_opts=ipam_opts,
+            labels=labels,
+            ingress=ingress,
+            attachable=attachable,
+            present=present,
+        )
+
+    else:
+        if existent_network is None:
+            host.noop("Ther is not network with {0} name!".format(network))
+            return
+
+        yield handle_docker(
+            resource="network",
+            command="create",
+            network=network,
+        )
+
+
+@operation(is_idempotent=False)
+def prune(
+    all=False,
+    volume=False,
+    filter="",
+):
+    """
+    Execute a docker system prune.
+
+    + all: Remove all unused images not just dangling ones
+    + volumes: Prune anonymous volumes
+    + filter: Provide filter values (e.g. "label=<key>=<value>" or "until=24h")
+
+    **Examples:**
+
+    .. code:: python
+
+        # Remove dangling images
+        docker.prune(
+            name="remove dangling images",
+        )
+
+        # Remove all images and volumes
+        docker.prune(
+            name="Remove all images and volumes",
+            all=True,
+            volumes=True,
+        )
+
+        # Remove images older than 90 days
+        docker.prune(
+            name="Remove unused older than 90 days",
+            filter="until=2160h"
+        )
+    """
+
+    yield handle_docker(
+        resource="system",
+        command="prune",
+        all=all,
+        volume=volume,
+        filter=filter,
+    )

pyinfra-3.0b3/pyinfra/operations/runit.py

@@ -0,0 +1,182 @@
+"""
+Manage runit services.
+"""
+
+from typing import Optional
+
+from pyinfra import host
+from pyinfra.api import operation
+from pyinfra.facts.files import File
+from pyinfra.facts.runit import RunitManaged, RunitStatus
+
+from .files import file, link
+from .util.service import handle_service_control
+
+
+@operation()
+def service(
+    service: str,
+    running: bool = True,
+    restarted: bool = False,
+    reloaded: bool = False,
+    command: Optional[str] = None,
+    enabled: Optional[bool] = None,
+    managed: bool = True,
+    svdir: str = "/var/service",
+    sourcedir: str = "/etc/sv",
+):
+    """
+    Manage the state of runit services.
+
+    + service: name of the service to manage
+    + running: whether the service should be running
+    + restarted: whether the service should be restarted
+    + reloaded: whether the service should be reloaded
+    + command: custom command to pass like: ``sv <command> <service>``
+    + enabled: whether this service should be enabled/disabled on boot
+    + managed: whether runit should manage this service
+
+      For services to be controlled, they first need to be managed by runit by
+      adding a symlink to the service in ``SVDIR``.
+      By setting ``managed=False`` the symlink will be removed.
+      Other options won't have any effect after that.
+      Although the ``<service>/down`` file can still be controlled with the
+      ``enabled`` option.
+
+    + svdir: alternative ``SVDIR``
+
+      An alternative ``SVDIR`` can be specified. This can be used for user services.
+
+    + sourcedir: where to search for available services
+
+      An alternative directory for available services can be specified.
+      Example: ``sourcedir=/etc/sv.local`` for services managed by the administrator.
+    """
+
+    was_managed = service in host.get_fact(RunitManaged, service=service, svdir=svdir)
+    was_auto = not host.get_fact(File, path="{0}/{1}/down".format(sourcedir, service))
+
+    # Disable autostart for previously unmanaged services.
+    #
+    # Where ``running=False`` is requested, this prevents one case of briefly
+    # starting and stopping the service.
+    if not was_managed and managed and was_auto:
+        yield from auto._inner(
+            service=service,
+            auto=False,
+            sourcedir=sourcedir,
+        )
+
+    yield from manage._inner(
+        service=service,
+        managed=managed,
+        svdir=svdir,
+        sourcedir=sourcedir,
+    )
+
+    # Service wasn't managed before, so wait for ``runsv`` to start.
+    # ``runsvdir`` will check at least every 5 seconds for new services.
+    # Wait for at most 10 seconds for the service to be managed, otherwise fail.
+    if not was_managed and managed:
+        yield from wait_runsv._inner(
+            service=service,
+            svdir=svdir,
+        )
+
+    if isinstance(enabled, bool):
+        yield from auto._inner(
+            service=service,
+            auto=enabled,
+            sourcedir=sourcedir,
+        )
+    else:
+        # restore previous state of ``<service>/down``
+        yield from auto._inner(
+            service=service,
+            auto=was_auto,
+            sourcedir=sourcedir,
+        )
+
+    # Services need to be managed by ``runit`` for the other options to make sense.
+    if not managed:
+        return
+
+    yield from handle_service_control(
+        host,
+        service,
+        host.get_fact(RunitStatus, service=service, svdir=svdir),
+        "SVDIR={0} sv {{1}} {{0}}".format(svdir),
+        running,
+        restarted,
+        reloaded,
+        command,
+    )
+
+
+@operation()
+def manage(
+    service: str,
+    managed: bool = True,
+    svdir: str = "/var/service",
+    sourcedir: str = "/etc/sv",
+):
+    """
+    Manage runit svdir links.
+
+    + service: name of the service to manage
+    + managed: whether the link should exist
+    + svdir: alternative ``SVDIR``
+    + sourcedir: where to search for available services
+    """
+
+    yield from link._inner(
+        path="{0}/{1}".format(svdir, service),
+        target="{0}/{1}".format(sourcedir, service),
+        present=managed,
+        create_remote_dir=False,
+    )
+
+
+@operation(is_idempotent=False)
+def wait_runsv(
+    service: str,
+    svdir: str = "/var/service",
+    timeout: int = 10,
+):
+    """
+    Wait for runsv for ``service`` to be available.
+
+    + service: name of the service to manage
+    + svdir: alternative ``SVDIR``
+    + timeout: time in seconds to wait
+    """
+
+    yield (
+        "export SVDIR={0}\n"
+        "for i in $(seq {1}); do\n"
+        "    sv status {2} > /dev/null && exit 0\n"
+        "    sleep 1;\n"
+        "done\n"
+        "exit 1"
+    ).format(svdir, timeout, service)
+
+
+@operation()
+def auto(
+    service: str,
+    auto: bool = True,
+    sourcedir: str = "/etc/sv",
+):
+    """
+    Start service automatically by managing the ``service/down`` file.
+
+    + service: name of the service to manage
+    + auto: whether the service should start automatically
+    + sourcedir: where to search for available services
+    """
+
+    yield from file._inner(
+        path="{0}/{1}/down".format(sourcedir, service),
+        present=not auto,
+        create_remote_dir=False,
+    )

{pyinfra-3.0b2 → pyinfra-3.0b3}/pyinfra/operations/server.py

@@ -41,6 +41,7 @@ from . import (
     openrc,
     pacman,
     pkg,
+    runit,
     systemd,
     sysvinit,
     upstart,
@@ -492,6 +493,9 @@ def service(
     elif host.get_fact(Which, command="initctl"):
         service_operation = upstart.service
 
+    elif host.get_fact(Which, command="sv"):
+        service_operation = runit.service
+
     elif (
         host.get_fact(Which, command="service")
         or host.get_fact(Link, path="/etc/init.d")

{pyinfra-3.0b2 → pyinfra-3.0b3}/pyinfra/operations/systemd.py

@@ -4,6 +4,8 @@ Manage systemd services.
 
 from __future__ import annotations
 
+import shlex
+
 from pyinfra import host
 from pyinfra.api import StringCommand, operation
 from pyinfra.facts.systemd import SystemdEnabled, SystemdStatus, _make_systemctl_cmd
@@ -140,8 +142,8 @@ def service(
 
         # Isn't enabled and want enabled?
         if not is_enabled and enabled is True:
-            yield "{0} enable {1}".format(systemctl_cmd, service)
+            yield "{0} enable {1}".format(systemctl_cmd, shlex.quote(service))
 
         # Is enabled and want disabled?
         elif is_enabled and enabled is False:
-            yield "{0} disable {1}".format(systemctl_cmd, service)
+            yield "{0} disable {1}".format(systemctl_cmd, shlex.quote(service))