diff --git a/CHANGES.rst b/CHANGES.rst index 919ef55..af00c70 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,6 +1,20 @@ Changelog ========= +**debops.docker** + +debops.docker master - unreleased +------------------------------------ + +Changed +~~~~~~~ +- Update documentation and Changelog. [tallandtree] + +- Rename all role variables from ``docker_*`` to ``docker__*`` to move them into + their own namespace. [tallandtree] + +- ``*.changed`` is changed to ``*|changed`` to ensure correct variable type resolution by Ansible + v0.1.2 ------ diff --git a/defaults/main.yml b/defaults/main.yml index ec0d239..39fa2d5 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -9,43 +9,43 @@ # Docker packages and installation # ------------------------------------ -# .. envvar:: docker_upstream +# .. envvar:: docker__upstream # # By default ``debops.docker`` installs Docker from the system distribution # repositories. Here you can enable upstream repositories and install the # upstream version of Docker. -docker_upstream: False +docker__upstream: False -# .. envvar:: docker_upstream_key +# .. envvar:: docker__upstream_key # # APT GPG key id used to sign the upstream Docker packages. -docker_upstream_key: '58118E89F3A912897C070ADBF76221572C52609D' +docker__upstream_key: '58118E89F3A912897C070ADBF76221572C52609D' -# .. envvar:: docker_upstream_repository +# .. envvar:: docker__upstream_repository # # Address of the Docker upstream APT repository. -docker_upstream_repository: 'deb https://apt.dockerproject.org/repo {{ ansible_distribution | lower }}-{{ ansible_distribution_release }} main' +docker__upstream_repository: 'deb https://apt.dockerproject.org/repo {{ ansible_distribution | lower }}-{{ ansible_distribution_release }} main' -# .. envvar:: docker_base_packages +# .. envvar:: docker__base_packages # # List of base packages to install with Docker. -docker_base_packages: [ 'aufs-tools', 'python-docker', 'python-setuptools' ] +docker__base_packages: [ 'aufs-tools', 'python-docker', 'python-setuptools' ] -# .. envvar:: docker_packages +# .. envvar:: docker__packages # # List of additional packages to install with Docker. -docker_packages: [] +docker__packages: [] -# .. envvar:: docker_admins +# .. envvar:: docker__admins # # List of UNIX accounts which should be added to ``docker`` system group which # has access to the Docker UNIX socket. -docker_admins: [ '{{ (ansible_ssh_user +docker__admins: [ '{{ (ansible_ssh_user if (ansible_ssh_user|d() | bool and ansible_ssh_user != "root") else lookup("env", "USER")) }}' ] @@ -55,35 +55,35 @@ docker_admins: [ '{{ (ansible_ssh_user # Network configuration # ------------------------- -# .. envvar:: docker_bridge +# .. envvar:: docker__bridge # # Name of the bridge to use instead of the autogenerated ``docker0`` bridge. -docker_bridge: '' +docker__bridge: '' -# .. envvar:: docker_fixed_cirt +# .. envvar:: docker__fixed_cidr # # Fixed subnet in CIDR format to confine dynamically allocated IP addresses. # Should be included in the IP address range set on the bridge. -docker_fixed_cidr: '' +docker__fixed_cidr: '' -# .. envvar:: docker_dns_nameserver +# .. envvar:: docker__dns_nameserver # # List of IP addresses of nameservers used by Docker. By default they # are gathered by the ``debops.core`` role from the :file:`/etc/resolv.conf` file of # the remote host. -docker_dns_nameserver: '{{ ansible_local.resolver.nameserver +docker__dns_nameserver: '{{ ansible_local.resolver.nameserver if (ansible_local|d() and ansible_local.resolver|d() and ansible_local.resolver.nameserver|d()) else [] }}' -# .. envvar:: docker_dns_search +# .. envvar:: docker__dns_search # # List of DNS search domains to use by Docker. By default they are gathered by # the ``debops.core`` role from the :file:`/etc/resolv.conf` file of the remote host. -docker_dns_search: '{{ ansible_local.resolver.search +docker__dns_search: '{{ ansible_local.resolver.search if (ansible_local|d() and ansible_local.resolver|d() and ansible_local.resolver.search|d()) else [] }}' @@ -93,147 +93,147 @@ docker_dns_search: '{{ ansible_local.resolver.search # Remote Docker connection (TCP) # ---------------------------------- -# .. envvar:: docker_tcp +# .. envvar:: docker__tcp # # Enable or disable listening for TLS connections on the TCP docker port. By # default remote connections are enabled if the ``debops.pki`` role has been # configured on remote host (access is controlled by the firewall). -docker_tcp: '{{ docker_pki | bool }}' +docker__tcp: '{{ docker__pki | bool }}' -# .. envvar:: docker_tcp_bind +# .. envvar:: docker__tcp_bind # # IP address of the interface to listen on for incoming connections (all # interfaces by default). -docker_tcp_bind: '0.0.0.0' +docker__tcp_bind: '0.0.0.0' -# .. envvar:: docker_tcp_port +# .. envvar:: docker__tcp_port # # Port on which to listen for incoming TLS connections. -docker_tcp_port: '2375' +docker__tcp_port: '2375' -# .. envvar:: docker_tcp_allow +# .. envvar:: docker__tcp_allow # # List of IP addresses or subnets in CIDR format which are allowed to connect # to the Docker daemon over TLS. If it's not specified, remote connections are # denied by the firewall. -docker_tcp_allow: [] +docker__tcp_allow: [] -# .. envvar:: docker_tcp_listen +# .. envvar:: docker__tcp_listen # # Default connection configured in addition to local socket connection, using # TCP over TLS. -docker_tcp_listen: '{{ ("tcp://" + docker_tcp_bind + ":" + docker_tcp_port) - if (docker_tcp|d() | bool) else "" }}' +docker__tcp_listen: '{{ ("tcp://" + docker__tcp_bind + ":" + docker__tcp_port) + if (docker__tcp|d() | bool) else "" }}' -# .. envvar:: docker_custom_ports +# .. envvar:: docker__custom_ports # # List of additional TCP/UDP ports to allow in the firewall, useful for other # Docker-related services, like Swarm, Consul. -docker_custom_ports: [] +docker__custom_ports: [] # -------------------------------- # Docker configuration options # -------------------------------- -# .. envvar:: docker_listen +# .. envvar:: docker__listen # # List of host connections configured in the Docker daemon (``--host`` parameter). -docker_listen: [ '{{ docker_tcp_listen }}' ] +docker__listen: [ '{{ docker__tcp_listen }}' ] -# .. envvar:: docker_labels +# .. envvar:: docker__labels # # Dictionary with labels configured on the Docker daemon, each key is the label # name and value is the label attribute. Examples:: # -# docker_labels: +# docker__labels: # 'com.example.environment': 'production' # 'com.example.storage': 'extfs' # -docker_labels: {} +docker__labels: {} -# .. envvar:: docker_options +# .. envvar:: docker__options # # List of additional options passed to ``docker`` daemon. Examples:: # -# docker_options: +# docker__options: # - '--icc=false' # - '--debug=true' # -docker_options: [] +docker__options: [] # ------------------------ # PKI and certificates # ------------------------ -# .. envvar:: docker_pki +# .. envvar:: docker__pki # # Enable or disable support for PKI certificates managed by ``debops.pki``. -docker_pki: '{{ (True +docker__pki: '{{ (True if (ansible_local|d() and ansible_local.pki|d() and ansible_local.pki.enabled|d() | bool) else False) | bool }}' -# .. envvar:: docker_pki_path +# .. envvar:: docker__pki_path # # Directory where PKI files are located on the remote host. -docker_pki_path: '{{ ansible_local.pki.base_path +docker__pki_path: '{{ ansible_local.pki.base_path if (ansible_local|d() and ansible_local.pki|d() and ansible_local.pki.base_path|d()) else "/etc/pki" }}' -# .. envvar:: docker_pki_realm +# .. envvar:: docker__pki_realm # # Name of the PKI realm used by Docker. -docker_pki_realm: '{{ ansible_local.pki.realm +docker__pki_realm: '{{ ansible_local.pki.realm if (ansible_local|d() and ansible_local.pki|d() and ansible_local.pki.realm|d()) else "system" }}' -# .. envvar:: docker_pki_ca +# .. envvar:: docker__pki_ca # # Name of the Root CA certificate file used by Docker. -docker_pki_ca: 'CA.crt' +docker__pki_ca: 'CA.crt' -# .. envvar:: docker_pki_crt +# .. envvar:: docker__pki_crt # # Name of the host certificate used by Docker. -docker_pki_crt: 'default.crt' +docker__pki_crt: 'default.crt' -# .. envvar:: docker_pki_key +# .. envvar:: docker__pki_key # # Name of the private key file used by Docker. -docker_pki_key: 'default.key' +docker__pki_key: 'default.key' # -------------------------------- # Firewall and ferment support # -------------------------------- -# .. envvar:: docker_ferment +# .. envvar:: docker__ferment # # Enable or disable support for :program:`ferment` script, which can generate ``ferm`` # configuration with the current Docker state. -docker_ferment: True +docker__ferment: True -# .. envvar:: docker_ferment_wrapper +# .. envvar:: docker__ferment_wrapper # # Path to the :program:`ferment` wrapper script used to generate ``ferm`` configuration. -docker_ferment_wrapper: '{{ (ansible_local.root.lib +docker__ferment_wrapper: '{{ (ansible_local.root.lib if (ansible_local|d() and ansible_local.root|d() and ansible_local.root.lib|d()) else "/usr/local/lib") + "/docker-ferment-wrapper" }}' @@ -243,11 +243,11 @@ docker_ferment_wrapper: '{{ (ansible_local.root.lib # Configuration of other Ansible roles # ---------------------------------------- -# .. envvar:: docker_etc_services_dependent_list +# .. envvar:: docker__etc_services__dependent_list # # Configuration for ``debops.etc_services`` role which registers port numbers # for Docker REST API. -docker_etc_services_dependent_list: +docker__etc_services__dependent_list: - name: 'docker' port: '2375' @@ -258,26 +258,26 @@ docker_etc_services_dependent_list: comment: 'Docker REST API (SSL)' -# .. envvar:: docker_ferm_dependent_rules +# .. envvar:: docker__ferm__dependent_rules # # Configuration for ``debops.ferm`` role which enables support for :program:`ferment` # script and opens access to the Docker REST API in the firewall. -docker_ferm_dependent_rules: +docker__ferm__dependent_rules: - type: 'custom' weight: '99' role: 'docker' name: 'ferment_rules' rules: | - @def $DOCKER_FERMENT = `test -x {{ docker_ferment_wrapper }} && echo 1 || echo 0`; + @def $DOCKER_FERMENT = `test -x {{ docker__ferment_wrapper }} && echo 1 || echo 0`; @if $DOCKER_FERMENT { - @include '{{ docker_ferment_wrapper + (" " + docker_bridge if docker_bridge else "") }}|'; + @include '{{ docker__ferment_wrapper + (" " + docker__bridge if docker__bridge else "") }}|'; } - type: 'accept' - dport: '{{ [ docker_tcp_port ] + docker_custom_ports }}' + dport: '{{ [ docker__tcp_port ] + docker__custom_ports }}' protocol: [ 'tcp', 'udp' ] - saddr: '{{ docker_tcp_allow }}' + saddr: '{{ docker__tcp_allow }}' accept_any: False weight: '50' role: 'docker' diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 1243cbb..9841c0f 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -10,12 +10,12 @@ Initial configuration The Docker package from distribution repositories will be installed by default (on Jessie it means that the ``jessie-backports`` repository needs to be available, which is the default in DebOps). You can install the upstream version of Docker -by setting the ``docker_upstream: True`` variable in Ansible’s inventory. +by setting the ``docker__upstream: True`` variable in Ansible’s inventory. If ``debops.pki`` was configured on the host, Docker will automatically listen on its TCP port for incoming TLS connections, which is by default blocked by the ``ferm`` firewall. If you don't use a firewall or have it disabled, you might -want to set ``docker_tcp`` to ``False`` to disable this behavior. +want to set ``docker__tcp`` to ``False`` to disable this behavior. Docker manages its own network bridge and :command:`iptables` entries. The :program:`ferment` Python script will be installed to allow ``ferm`` firewall to reload Docker @@ -32,11 +32,11 @@ Useful variables This is a list of role variables which your most likely want to define in Ansible inventory to customize Docker: -``docker_tcp_allow`` +``docker__tcp_allow`` List of IP addresses or subnets that can connect to Docker daemon remotely over TLS. -``docker_admins`` +``docker__admins`` List of UNIX accounts that have access to Docker daemon socket. Example inventory diff --git a/tasks/main.yml b/tasks/main.yml index c854c73..a6bd7fe 100644 --- a/tasks/main.yml +++ b/tasks/main.yml @@ -2,20 +2,20 @@ - name: Get upstream APT GPG key apt_key: - id: '{{ docker_upstream_key }}' + id: '{{ docker__upstream_key }}' keyserver: '{{ ansible_local.core.keyserver if (ansible_local|d() and ansible_local.core|d() and ansible_local.core.keyserver) else "hkp://pool.sks-keyservers.net" }}' state: 'present' - when: docker_upstream|d() | bool + when: docker__upstream|d() | bool - name: Configure upstream APT repository apt_repository: - repo: '{{ docker_upstream_repository }}' + repo: '{{ docker__upstream_repository }}' state: 'present' update_cache: True - when: docker_upstream|d() | bool + when: docker__upstream|d() | bool - name: Install required packages apt: @@ -23,30 +23,30 @@ state: 'present' install_recommends: False with_flattened: - - '{{ "docker-engine" if docker_upstream|d() else "docker.io" }}' - - '{{ docker_base_packages }}' - - '{{ docker_packages }}' + - '{{ "docker-engine" if docker__upstream|d() else "docker.io" }}' + - '{{ docker__base_packages }}' + - '{{ docker__packages }}' - name: Install ferment generator pip: name: 'ferment' state: 'present' - when: docker_ferment|d() | bool + when: docker__ferment|d() | bool - name: Install ferment wrapper script template: src: 'usr/local/lib/docker-ferment-wrapper.j2' - dest: '{{ docker_ferment_wrapper }}' + dest: '{{ docker__ferment_wrapper }}' owner: 'root' group: 'root' mode: '0755' - when: docker_ferment|d() | bool + when: docker__ferment|d() | bool - name: Check Docker version environment: LC_MESSAGES: 'C' - shell: dpkg-query -W -f='${Version}\n' '{{ ("docker-engine" if docker_upstream|d() else "docker.io") }}' | cut -d- -f1 - register: docker_register_version + shell: dpkg-query -W -f='${Version}\n' '{{ ("docker-engine" if docker__upstream|d() else "docker.io") }}' | cut -d- -f1 + register: docker__register_version changed_when: False failed_when: False tags: [ 'role::docker:config' ] @@ -68,7 +68,7 @@ owner: 'root' group: 'root' mode: '0755' - when: docker_upstream|d() | bool + when: docker__upstream|d() | bool tags: [ 'role::docker:config' ] - name: Make sure that docker.service.d directory exists @@ -78,7 +78,7 @@ owner: 'root' group: 'root' mode: '0755' - when: (docker_upstream|d() | bool) and + when: (docker__upstream|d() | bool) and (inventory__environment is defined and inventory__environment.http_proxy is defined) tags: [ 'role::docker:config' ] @@ -89,8 +89,8 @@ owner: 'root' group: 'root' mode: '0644' - register: docker_register_systemd_service - when: docker_upstream|d() | bool + register: docker__register_systemd_service + when: docker__upstream|d() | bool tags: [ 'role::docker:config' ] - name: Configure Docker proxy @@ -100,15 +100,15 @@ owner: 'root' group: 'root' mode: '0644' - register: docker_register_systemd_proxy_present - when: (docker_upstream|d() | bool) and + register: docker__register_systemd_proxy_present + when: (docker__upstream|d() | bool) and (inventory__environment is defined and inventory__environment.http_proxy is defined) tags: [ 'role::docker:config' ] - name: Remove Docker proxy configuration file: path='/etc/systemd/system/docker.service.d/http-proxy.conf' state=absent - register: docker_register_systemd_proxy_absent - when: (docker_upstream|d() | bool) and + register: docker__register_systemd_proxy_absent + when: (docker__upstream|d() | bool) and (inventory__environment is not defined or inventory__environment.http_proxy is not defined) tags: [ 'role::docker:config' ] @@ -117,12 +117,12 @@ notify: [ 'Restart docker'] when: ((ansible_local|d() and ansible_local.init|d() and ansible_local.init == 'systemd') and - ((docker_register_systemd_service|d() and - docker_register_systemd_service.changed) or - (docker_register_systemd_proxy_present|d() and - docker_register_systemd_proxy_present|changed) or - (docker_register_systemd_proxy_absent|d() and - docker_register_systemd_proxy_absent|changed))) + ((docker__register_systemd_service|d() and + docker__register_systemd_service|changed) or + (docker__register_systemd_proxy_present|d() and + docker__register_systemd_proxy_present|changed) or + (docker__register_systemd_proxy_absent|d() and + docker__register_systemd_proxy_absent|changed))) tags: [ 'role::docker:config' ] - name: Add specified users to 'docker' group @@ -130,7 +130,7 @@ name: '{{ item }}' groups: 'docker' append: True - with_items: '{{ docker_admins }}' + with_items: '{{ docker__admins }}' when: item|d() tags: [ 'role::docker:config', 'role::docker:admins' ] diff --git a/templates/etc/default/docker.j2 b/templates/etc/default/docker.j2 index 6333e55..065d56c 100644 --- a/templates/etc/default/docker.j2 +++ b/templates/etc/default/docker.j2 @@ -5,57 +5,54 @@ # Customize location of Docker binary (especially for development testing). #DOCKER="/usr/local/bin/docker" -{% set docker_tpl_options = [] %} -{% if docker_bridge|d() %} -{% set _ = docker_tpl_options.append("--bridge " + docker_bridge) %} +{% set docker__tpl_options = [] %} +{% if docker__bridge|d() %} +{% set _ = docker__tpl_options.append("--bridge " + docker__bridge) %} {% endif %} -{% if docker_fixed_cidr|d() %} -{% set _ = docker_tpl_options.append("--fixed-cidr " + docker_fixed_cidr) %} +{% if docker__fixed_cidr|d() %} +{% set _ = docker__tpl_options.append("--fixed-cidr " + docker__fixed_cidr) %} {% endif %} -{% if docker_dns_nameserver|d() %} -{% for nameserver in docker_dns_nameserver %} -{% set _ = docker_tpl_options.append("--dns " + nameserver) %} +{% if docker__dns_nameserver|d() %} +{% for nameserver in docker__dns_nameserver %} +{% set _ = docker__tpl_options.append("--dns " + nameserver) %} {% endfor %} {% endif %} -{% if docker_dns_search|d() %} -{% for domain in docker_dns_search %} -{% set _ = docker_tpl_options.append("--dns-search " + domain) %} +{% if docker__dns_search|d() %} +{% for domain in docker__dns_search %} +{% set _ = docker__tpl_options.append("--dns-search " + domain) %} {% endfor %} {% endif %} -{% if docker_listen|d() %} -{% for host in docker_listen %} +{% if docker__listen|d() %} +{% for host in docker__listen %} {% if host %} -{% set _ = docker_tpl_options.append("-H " + host) %} +{% set _ = docker__tpl_options.append("-H " + host) %} {% endif %} {% endfor %} {% endif %} -{% if docker_pki|d() | bool %} -{% set _ = docker_tpl_options.append("--tlsverify") %} -{% set _ = docker_tpl_options.append("--tlscacert " + docker_pki_path + "/" + docker_pki_realm + "/" + docker_pki_ca) %} -{% set _ = docker_tpl_options.append("--tlscert " + docker_pki_path + "/" + docker_pki_realm + "/" + docker_pki_crt) %} -{% set _ = docker_tpl_options.append("--tlskey " + docker_pki_path + "/" + docker_pki_realm + "/" + docker_pki_key) %} +{% if docker__pki|d() | bool %} +{% set _ = docker__tpl_options.append("--tlsverify") %} +{% set _ = docker__tpl_options.append("--tlscacert " + docker__pki_path + "/" + docker__pki_realm + "/" + docker__pki_ca) %} +{% set _ = docker__tpl_options.append("--tlscert " + docker__pki_path + "/" + docker__pki_realm + "/" + docker__pki_crt) %} +{% set _ = docker__tpl_options.append("--tlskey " + docker__pki_path + "/" + docker__pki_realm + "/" + docker__pki_key) %} {% endif %} -{% if docker_labels|d() %} -{% for key, value in docker_labels.iteritems() %} -{% set _ = docker_tpl_options.append("--label " + key + '="' + value + '"') %} +{% if docker__labels|d() %} +{% for key, value in docker__labels.iteritems() %} +{% set _ = docker__tpl_options.append("--label " + key + '="' + value + '"') %} {% endfor %} {% endif %} -{% if docker_options|d() %} -{% for option in docker_options %} +{% if docker__options|d() %} +{% for option in docker__options %} {% if option %} -{% set _ = docker_tpl_options.append(option) %} +{% set _ = docker__tpl_options.append(option) %} {% endif %} {% endfor %} {% endif %} # Use DOCKER_OPTS to modify the daemon startup options. -{% if docker_tpl_options %} -DOCKER_OPTS='{{ docker_tpl_options | join(" ") }}' +{% if docker__tpl_options %} +DOCKER_OPTS='{{ docker__tpl_options | join(" ") }}' {% else %} #DOCKER_OPTS="--dns 8.8.8.8 --dns 8.8.4.4" {% endif %} -# If you need Docker to use an HTTP proxy, it can also be specified here. -#export http_proxy="http://127.0.0.1:3128/" - # This is also a handy place to tweak where Docker's temporary files go. #export TMPDIR="/mnt/bigdrive/docker-tmp" diff --git a/templates/etc/systemd/system/docker.service.j2 b/templates/etc/systemd/system/docker.service.j2 index 734e76c..5e1056e 100644 --- a/templates/etc/systemd/system/docker.service.j2 +++ b/templates/etc/systemd/system/docker.service.j2 @@ -8,7 +8,7 @@ Requires=docker.socket [Service] EnvironmentFile=-/etc/default/docker -{% if docker_register_version | version_compare('1.8', '>=') %} +{% if docker__register_version | version_compare('1.8', '>=') %} ExecStart=/usr/bin/docker daemon -H fd:// $DOCKER_OPTS {% else %} ExecStart=/usr/bin/docker -d -H fd:// $DOCKER_OPTS