Docker Rootless Ansible Role

This is an Ansible role that helps you to install and set up a Docker daemon to run as a non-root user.

Before using this, please test it in a safe environment first.

Rootless mode allows you to run the Docker daemon and containers as a non-root user, reducing potential security risks. (docker)

Note There is a SLSA artifact available for verification in the slsa action workflow.

Requirements

To use this role, include the following in your playbook:

---
roles:
  - name: konstruktoid.docker_rootless
    version: v0.53.0
    src: https://github.com/konstruktoid/ansible-role-docker-rootless.git
    scm: git

Example Playbook

---
- hosts: all
  any_errors_fatal: true
  tasks:
    - name: Include the konstruktoid.docker_rootless role
      ansible.builtin.import_role:
        name: konstruktoid.docker_rootless

Role Variables with Defaults

---
docker_add_alias: true
docker_allow_ping: false
docker_allow_privileged_ports: false
docker_compose: false
docker_compose_arch: x86_64
docker_compose_release: v2.29.2
docker_compose_release_shasum: d037bd4937bf18fba67cff4366e084ee125a3e15c25657ee1aeceff8db3672b4
docker_compose_url: https://github.com/docker/compose/releases/download
docker_daemon_json_template: daemon.json.j2
docker_driver_network: slirp4netns
docker_driver_port: builtin
docker_release: 27.1.2
docker_release_rootless_shasum: 5565502b4fab26266327f5a018185f5a98cc1714c975b943dcb7c4365cdcdb25
docker_release_shasum: a7fff574037af22bd0239e7e5601c312d9fe9c55e2b9cf5ddea86d5499a4de88
docker_repository_template: docker.repo.j2
docker_rootful_enabled: false
docker_rootful: false
docker_rootful_opts: false
docker_rootful_service_template: docker_rootful.service.j2
docker_rootless_script_template: docker_rootless.sh.j2
docker_rootless_service_template: docker_rootless.service.j2
docker_service_restart: true
docker_url: https://download.docker.com/linux/static/stable/x86_64
docker_user_bashrc: false
docker_user: dockeruser

Before using this role, decide if you want to install Docker using the distribution's packages (known as "rootful" installation, which needs root permissions) or download and install static binaries without root permissions.

• Set docker_rootful: false to download static binaries and manually install Docker.
• If docker_rootful: true, the docker_rootful_enabled variable will determine if the daemon is enabled as a service.

The docker_service_restart option will restart the rootless service after downloading Docker binaries. This could affect any running containers.

Using both docker_rootful: true and docker_rootful_enabled: true will result in a standard Docker installation but with an additional daemon running as a non-root user.

Note: Debian 10 and earlier require docker_rootful: false due to missing dependencies.

The docker_url, docker_release, docker_compose_url, and docker_compose_release variables specify where to find the necessary binaries for manual installation.

The docker_user variable allows you to set the name of the Docker user that will download and install binaries or run the rootless installation script.

Important: The docker_user is specifically for running the Docker daemon and containers, not for general system administration or regular user tasks.

The *_shasum variables are used to check the integrity of downloaded files.

If docker_add_alias: true, an alias for the docker command will be set up for the Ansible user. If false, a shell script named docker_rootless.sh will be created in the user's home directory to help execute the rootless Docker installation.

If docker_compose: true, Docker’s compose plugin will be installed. The variable docker_compose_arch defines the architecture for Docker Compose.

The docker_allow_privileged_ports variable sets whether to allow exposing ports below 1024.

The docker_allow_ping variable controls if non-privileged users can send ping requests from containers.

The docker_driver_network and docker_driver_port variables configure the network and port drivers for RootlessKit, helping with network performance.

The *_template variables indicate where templates are located, helping you customize them easily, especially the docker_daemon_json_template.

Container Management

Standalone Container

Running containers is similar to a regular Docker daemon, but you need to switch to the unprivileged user and adapt paths accordingly.

If docker_add_alias: true, the docker command will be available as usual. You can check the command aliases by typing alias in the shell.

- name: Register Docker user info
  become: true
  ansible.builtin.user:
    name: "{{ docker_user }}"
  check_mode: true
  register: docker_user_info

- name: Example container block
  environment:
    XDG_RUNTIME_DIR: "/run/user/{{ docker_user_info.uid }}"
    PATH: "{{ docker_user_info.home }}/bin:{{ ansible_env.PATH }}"
    DOCKER_HOST: "unix:///run/user/{{ docker_user_info.uid }}/docker.sock"
  block:
    - name: Nginx container
      become: true
      become_user: "{{ docker_user }}"
      community.docker.docker_container:
        name: nginx
        image: konstruktoid/nginx
        state: started
        cap_drop: all
        capabilities:
          - chown
          - dac_override
          - net_bind_service
          - setgid
          - setuid
        pull: true
        hostname: "{{ ansible_nodename }}"
        container_default_behavior: compatibility

Docker Compose Service

- name: Register Docker user info
  become: true
  ansible.builtin.user:
    name: "{{ docker_user }}"
  check_mode: true
  register: docker_user_info

- name: Example docker compose block
  become: true
  become_user: "{{ docker_user }}"
  environment:
    XDG_RUNTIME_DIR: /run/user/{{ docker_user_info.uid }}
    PATH: "{{ docker_user_info.home }}/bin:{{ ansible_env.PATH }}"
    DOCKER_HOST: "unix:///run/user/{{ docker_user_info.uid }}/docker.sock"
  block:
    - name: Install pip dependencies
      ansible.builtin.pip:
        name:
          - docker<7 # https://github.com/docker/docker-py/issues/3194
          - docker-compose

    - name: Create and start services
      community.docker.docker_compose:
        project_src: /var/tmp/
        files: "{{ docker_user }}-docker-compose.yml"
      register: compose_output

Testing with Molecule

If you have Ansible Molecule and the Vagrant plugin installed, you can run molecule test for testing.

Use tox -l to see all available tox test environments.

Contributing

If you want to contribute, great! Your contributions are welcome, big or small. Feel free to submit issues or pull requests, or consider sponsoring this project.

License

Apache License Version 2.0

Author Information

https://github.com/konstruktoid