Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/znerol/ansible-collection-podluck

Runs podman pods under systemd
https://github.com/znerol/ansible-collection-podluck

ansible podman systemd

Last synced: 25 days ago
JSON representation

Runs podman pods under systemd

Awesome Lists containing this project

README 

        
# Ansible Collection - znerol.podluck



Runs podman pods under systemd.



This collection provides the modules `znerol.podluck.podluck_container` and

`znerol.podluck_podluck_pod` as well as the role

`znerol.podluck.podluck_pod_systemd`. Modules and role are intended to be

combined into playbooks in order to install pods on target systems managed by

systemd.



Most options of `containers.podman.podman_pod` and

`containers.podman.podman_contaier` can be used as is in

`znerol.podluck_podluck_pod` and `znerol.podluck_podluck_container`. This should

reduce the effort for upgraing from `containers.podman` to `znerol.podluck`.



Note that the systemd units installed by this role are designed to always

*create* and *remove* all containers in a pod when *starting* and *stopping*

them respectively. As a result, the systemd units are working well with `podman

auto-update`.



Units and config can be installed both, in the `user` scope

(`~/.config/podluck`, `~/.config/systemd/user`) as well as in `system` scope

(`/etc/podluck`, `/etc/systemd/system`). As a result, this collection supports

rootfull as well as rootless deployments.



## Requirements



* Ansible>=2.10

* Python 3.6 or better

* containers.podman collection



## Installation



Using a `requirements.yml` file:



```yaml

collections:

  - name: znerol.podluck

```



## Reference



### Options for `znerol.podluck_podluck_pod` module



```

= name

        Name of the pod



        type: str



- path

        Path to the pod configuration file. Use the defaults, since

        this is what the `podluck-service.service` systemd unit

        expects.

        Defaults to `/etc/podluck/pod/{{ name }}/systemd-pod-env` when

        module is executed as `root'.

        Defaults to `~/.config/podluck/pod/{{ name }}/systemd-pod-env`

        when module is executed as an unprivileged user.

        [Default: (null)]

        type: str



- state

        `absent' - A podluck configuration file for the pod in the is

        unlinked if it exists.

        `present' - A podluck configuration file for the pod in the is

        created and populated with cli arguments matching the desired

        configuration. Returns `changed: True` if existing

        configuration does not match the current config. The calling

        playbook / role is responsible for restarting the pod if

        necessary.

        (Choices: absent, present)[Default: present]

        type: str

```



* This module supports check mode.

* This module supports all options provided by

  [containers.podman.podman_pod](https://docs.ansible.com/ansible/latest/collections/containers/podman/podman_pod_module.html#ansible-collections-containers-podman-podman-pod-module) with the following

  exceptions: `executable`, `infra_conmon_pidfile`,

  `pod_id_file`, `recreate`, `replace`.



### Options for `znerol.podluck_podluck_container` module



```

= name

        Name of the container



        type: str



- path

        Path to the container configuration file. Use the defaults,

        since this is what the `[email protected]` systemd unit

        expects.

        Defaults to `/etc/podluck/pod/{{ pod }}/systemd-container-{{

        name }}-env` when module is executed as `root'.

        Defaults to `~/.config/podluck/pod/{{ pod }}/systemd-

        container-{{ name }}-env` when module is executed as an

        unprivileged user.

        [Default: (null)]

        type: str



= pod

        Name of a pod created using [znerol.podluck.podluck_pod].



        type: str



- state

        `absent' - A podluck configuration file for the container in

        the specified pod is unlinked if it exists.

        `present' - A podluck configuration file for the container in

        the specified pod is created and populated with cli arguments

        matching the desired configuration. Returns `changed: True` if

        existing configuration does not match the current config. The

        calling playbook / role is responsible for restarting the

        container / pod if necessary.

        (Choices: absent, present)[Default: present]

        type: str

```



* This module supports check mode.

* This module supports all options provided by

  [containers.podman.podman_container](https://docs.ansible.com/ansible/latest/collections/containers/podman/podman_container_module.html#ansible-collections-containers-podman-podman-container-module) with the following

  exceptions: `cgroups`, `cidfile`, `conmon_pidfile`,

  `detach`, `executable`, `generate_systemd`,

  `infra_conmon_pidfile`, `pod_id_file`, `recreate`,

  `replace`.



### Variables for `znerol.podluck.podluck_pod_systemd` role



```yaml

---

# Required: Pod name, also used as the systemd service name. Must be defined

# when role is imported / included.

# podluck_pod_name: no-default



# Optional: State, either `present` or `absent`. Defaults to `present`.

podluck_pod_state: present



# Recommended: Whether systemd units are enabled (`true`) or disabled (`false`).

# No changes if omitted.

# podluck_pod_enabled: default(omit)



# Recommended: List of container names to start / stop when pod is started /

# stopped.

podluck_pod_containers: []



# Optional: List of dependency entries with container and wants keys:

#     podluck_pod_dependencies:

#       -

#         container: container-name

#         wants: other-container-name

#       -

#         container: other-container-name

#         wants: some-additional-container-name

podluck_pod_dependencies: []



# Optional: Systemd scope (either 'system' or 'user')

podluck_systemd_scope: system



# Optional: Path to systemd units. Defaults to /usr/local/lib/systemd/system if

# `podluck_systemd_scope` is `system` and `~/.config/systemd/user` if

# `podluck_systemd_scope` is `user`.

podluck_systemd_unit_dir: "{{ podluck_systemd_unit_dirs[podluck_systemd_scope] }}"



# Optional: Path to systemd config directory. Defaults to /etc/systemd/system if

# `podluck_systemd_scope` is `system` and `~/.config/systemd/user` if

# `podluck_systemd_scope` is `user`.

podluck_systemd_config_dir: "{{ podluck_systemd_config_dirs[podluck_systemd_scope] }}"



# Optional: Path to directory with podluck systemd unit files. Defaults to the

# ones shipped with this role.

podluck_systemd_skel_src: systemd-skel



# Optional: Whether or not to look for podluck systemd unit files on the remote

# machine. Defaults to `false`.

# podluck_systemd_skel_remote_src: default(omit)



# Optional: Owner of copied systemd unit files. Omitted by default.

# podluck_systemd_unit_file_owner: default(omit)



# Optional: Group of copied systemd unit files. Omitted by default.

# podluck_systemd_unit_file_group: default(omit)



# Optional: Mode of copied systemd unit files. Defaults to rw-r--r--

podluck_systemd_unit_file_mode: 0644



# Optional: Owner of systemd unit override directory. Omitted by default.

# podluck_systemd_override_dir_owner: default(omit)



# Optional: Group of systemd unit override directory. Omitted by default.

# podluck_systemd_override_dir_group: default(omit)



# Optional: Mode of systemd unit override directory. Defaults to rwxr-xr-x

podluck_systemd_override_dir_mode: 0755



# Optional: Owner of systemd unit override files. Omitted by default.

# podluck_systemd_override_file_owner: default(omit)



# Optional: Group of systemd unit override files. Omitted by default.

# podluck_systemd_override_file_group: default(omit)



# Optional: Mode of systemd unit override files. Defaults to rw-r--r--

podluck_systemd_override_file_mode: 0644

```



## Example



### Minimal rootless example



```yaml

---

- name: Minimal rootless example

  hosts: localhost

  gather_facts: no

  vars:

    podluck_systemd_scope: user

    podluck_pod_name: minimal.example.com

    podluck_pod_state: present

    podluck_pod_enabled: true

    podluck_pod_containers:

      - hello-world

  tasks:

    - name: Pod configuration present

      znerol.podluck.podluck_pod:

        name: "{{ podluck_pod_name }}"

        state: "{{ podluck_pod_state }}"

        share: net,uts

        mode: 0600



    - name: Container configuration present

      znerol.podluck.podluck_container:

        name: hello-world

        image: docker.io/library/hello-world:latest

        pod: "{{ podluck_pod_name }}"

        state: "{{ podluck_pod_state }}"

        log_driver: journald

        cap_drop: ALL

        mode: 0600



    - name: Systemd configuration present

      import_role:

        name: znerol.podluck.podluck_pod_systemd



    - name: Pod started

      when: podluck_pod_state != 'absent'

      systemd:

        name: "{{ podluck_pod_name }}.service"

        scope: "{{ podluck_systemd_scope }}"

        state: started

```



After running this playbook, the `minimal.example.com` pod should be up and

running along with `hello-world.minimal.example.com` container. Also systemd

units `minimal.example.com.service` as well as `minimal.example.com@hello-world`

are expected to be started. Inspect the results as follows:



```

$ systemctl --user status minimal.example.com.service

● minimal.example.com.service - Podman pod minimal.example.com managed by podluck

[...]



$ systemctl --user status [email protected]

● [email protected] - Podman container hello-world in pod minimal.example.com managed by podluck

[...]



$ journalctl --user --unit minimal.example.com.service

-- Journal begins at Sat 2021-05-22 14:40:55 CEST, ends at Sun 2021-12-19 14:49:14 CET. --

systemd[676]: Starting Podman pod minimal.example.com managed by podluck...

[...]



$ journalctl --user --unit [email protected]

-- Journal begins at Sat 2021-05-22 14:40:55 CEST, ends at Sun 2021-12-19 14:49:14 CET. --

systemd[676]: Starting Podman container hello-world in pod minimal.example.com managed by podluck...

[...]

conmon[20303]:

conmon[20303]: Hello from Docker!

conmon[20303]: This message shows that your installation appears to be working correctly.

conmon[20303]:

conmon[20303]: To generate this message, Docker took the following steps:

conmon[20303]:  1. The Docker client contacted the Docker daemon.

conmon[20303]:  2. The Docker daemon pulled the "hello-world" image from the Docker Hub.

conmon[20303]:     (amd64)

conmon[20303]:  3. The Docker daemon created a new container from that image which runs the

conmon[20303]:     executable that produces the output you are currently reading.

conmon[20303]:  4. The Docker daemon streamed that output to the Docker client, which sent it

conmon[20303]:     to your terminal.

conmon[20303]:

conmon[20303]: To try something more ambitious, you can run an Ubuntu container with:

conmon[20303]:  $ docker run -it ubuntu bash

conmon[20303]:

conmon[20303]: Share images, automate workflows, and more with a free Docker ID:

conmon[20303]:  https://hub.docker.com/

conmon[20303]:

conmon[20303]: For more examples and ideas, visit:

conmon[20303]:  https://docs.docker.com/get-started/

conmon[20303]:

[...]

systemd[676]: [email protected]: Succeeded.

systemd[676]: [email protected]: Consumed 1.344s CPU time.

```



## License



* [GPL-3 or later](https://www.gnu.org/licenses/gpl-3.0.en.html)