From 0f8ce10988239fca3b977413dc28d6e1d210b631 Mon Sep 17 00:00:00 2001 From: Leopold Talirz Date: Wed, 3 Feb 2021 10:49:15 +0100 Subject: [PATCH] feat: make version pinning optional (#97) The ansible role was pinning the versions of dokku-related apt packages. In order to use the role with newer (or older) dokku versions, users of the role would have to figure out by themselves which versions of these packages were compatible - despite the fact that a simple `apt-get install dokku` would have taken care of the dependencies correctly. Here we deprecate version pinning (to be removed in 07/2021) and turn it off by default (unless the user explicitly provides package versions). We introduce a new variable `dokku_packages_state` that accepts the values 'present' and 'latest' and defaults to 'present' (subsequent runs of the role therefore won't touch any of the packages installed). When users wish to upgrade their dokku installation via ansible, they can pass the value `latest`. Special case dokku-daemon: dokku daemon is installed directly from GitHub and doesn't release that often - safer to stick to a version than to switch to the master branch. --- README.md | 48 +++++++++++++++++++++++++---------------- bin/generate | 27 ++++++++++++++++++----- defaults/main.yml | 9 ++++---- defaults/main.yml.base | 49 ++++++++++++++++++++++++++++++------------ tasks/install-pin.yml | 15 +++++++++++++ tasks/install.yml | 22 +++++++------------ 6 files changed, 114 insertions(+), 56 deletions(-) create mode 100644 tasks/install-pin.yml diff --git a/README.md b/README.md index b26aff4..a08ce36 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ Supported Platforms - geerlingguy.docker ansible role - nginxinc.nginx ansible role -- Dokku version 0.21.4 (for library usage) +- Dokku (for library usage) ## Role Variables @@ -58,7 +58,7 @@ Supported Platforms - default: `0.0.2` - type: `string` -- description: Version of dokku-daemon to install +- description: The version of dokku-daemon to install ### dokku_hostname @@ -78,6 +78,12 @@ Supported Platforms - type: `boolean` - description: Whether we should manage the 00-default nginx site +### dokku_packages_state + +- default: `present` +- type: `string` +- description: State of dokku packages. Accepts 'present' and 'latest' + ### dokku_plugins - default: `{}` @@ -100,7 +106,7 @@ Supported Platforms ### dokku_users -- default: `None` +- default: `null` - type: `list` - description: A list of users who should have access to Dokku. This will _not_ grant them generic SSH access, but rather only access as the `dokku` user. Users should be specified in the following format: @@ -113,11 +119,12 @@ Supported Platforms ssh_key: CAMILLAS_PUBLIC_SSH_KEY ``` -### dokku_version +### dokku_version (deprecated) -- default: `0.21.4` -- type: `version` -- description: The version of Dokku to install +- default: `''` +- type: `string` +- description: The version of dokku to install. +Scheduled for deletion after 07/2021. Use `dokku_packages_state` instead. ### dokku_vhost_enable @@ -131,23 +138,26 @@ Supported Platforms - type: `string` - description: Use web-based config for hostname and keyfile -### herokuish_version +### herokuish_version (deprecated) -- default: `0.5.18` -- type: `version` -- description: The version of herokuish to install +- default: `''` +- type: `string` +- description: The version of herokuish to install. +Scheduled for deletion after 07/2021. Use `dokku_packages_state` instead. -### plugn_version +### plugn_version (deprecated) -- default: `0.5.0` -- type: `version` -- description: The version of plugn to install +- default: `''` +- type: `string` +- description: The version of plugn to install. +Scheduled for deletion after 07/2021. Use `dokku_packages_state` instead. -### sshcommand_version +### sshcommand_version (deprecated) -- default: `0.11.0` -- type: `version` -- description: The version of sshcommand to install +- default: `''` +- type: `string` +- description: The version of sshcommand to install. +Scheduled for deletion after 07/2021. Use `dokku_packages_state` instead. ## Libraries diff --git a/bin/generate b/bin/generate index 5fab95e..eb43911 100755 --- a/bin/generate +++ b/bin/generate @@ -4,6 +4,13 @@ import os import yaml +def represent_none(self, _): + return self.represent_scalar("tag:yaml.org,2002:null", "") + + +yaml.add_representer(type(None), represent_none) + + def section_header(text, level=1): return "{0} {1}".format("#" * level, text) @@ -145,9 +152,7 @@ def add_requirements(text, meta, defaults): "- {0} ansible role".format(dependency) for dependency in meta["dependencies"] ] - dependencies.append( - "- Dokku version {0} (for library usage)".format(defaults["dokku_version"]) - ) + dependencies.append("- Dokku (for library usage)") text.append("\n".join(dependencies)) return text @@ -164,10 +169,22 @@ def add_variables(text, role_path): variables = sorted(defaults.keys()) for variable in variables: config = defaults[variable] - text.append(section_header("{0}".format(variable), 3)) + header_text = "{0}".format(variable) + if config.get("deprecated", False): + header_text += " (deprecated)" + text.append(section_header(header_text, 3)) + + # Note: there doesn't seem to be a straighforward way of mapping a python value to its yaml representation + # without getting a whole yaml document back. See https://stackoverflow.com/questions/28376530 + default_str = config["default"] + if default_str == "": + default_str = "''" + elif default_str is None: + default_str = "null" + text.append( "- default: `{0}`\n- type: `{1}`\n- description: {2}".format( - config["default"], config["type"], config["description"].strip() + default_str, config["type"], config["description"].strip() ) ) diff --git a/defaults/main.yml b/defaults/main.yml index 47f689d..0e9f9e5 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -3,11 +3,12 @@ dokku_daemon_version: 0.0.2 dokku_hostname: dokku.me dokku_key_file: /root/.ssh/id_rsa.pub dokku_manage_nginx: true +dokku_packages_state: present dokku_plugins: {} dokku_skip_key_file: 'false' -dokku_version: 0.21.4 +dokku_version: '' dokku_vhost_enable: 'true' dokku_web_config: 'false' -herokuish_version: 0.5.18 -plugn_version: 0.5.0 -sshcommand_version: 0.11.0 +herokuish_version: '' +plugn_version: '' +sshcommand_version: '' diff --git a/defaults/main.yml.base b/defaults/main.yml.base index 638a03f..a68fe8e 100644 --- a/defaults/main.yml.base +++ b/defaults/main.yml.base @@ -1,7 +1,16 @@ +dokku_packages_state: + default: present + description: State of dokku packages. Accepts 'present' and 'latest' + type: string + dokku_version: - default: 0.21.4 - description: The version of Dokku to install - type: version + default: "" + description: | + The version of dokku to install. + Scheduled for deletion after 07/2021. Use `dokku_packages_state` instead. + deprecated: true + templated: true + type: string dokku_manage_nginx: default: true @@ -14,23 +23,35 @@ dokku_daemon_install: type: boolean dokku_daemon_version: default: 0.0.2 - description: Version of dokku-daemon to install + description: The version of dokku-daemon to install type: string herokuish_version: - default: 0.5.18 - description: The version of herokuish to install - type: version + default: "" + description: | + The version of herokuish to install. + Scheduled for deletion after 07/2021. Use `dokku_packages_state` instead. + deprecated: true + templated: true + type: string sshcommand_version: - default: 0.11.0 - description: The version of sshcommand to install - type: version + default: "" + description: | + The version of sshcommand to install. + Scheduled for deletion after 07/2021. Use `dokku_packages_state` instead. + deprecated: true + templated: true + type: string plugn_version: - default: 0.5.0 - description: The version of plugn to install - type: version + default: "" + description: | + The version of plugn to install. + Scheduled for deletion after 07/2021. Use `dokku_packages_state` instead. + deprecated: true + templated: true + type: string dokku_users: default: null @@ -45,7 +66,7 @@ dokku_users: username: camilla ssh_key: CAMILLAS_PUBLIC_SSH_KEY ``` - templated: False + templated: false type: list # debconf diff --git a/tasks/install-pin.yml b/tasks/install-pin.yml new file mode 100644 index 0000000..549a24f --- /dev/null +++ b/tasks/install-pin.yml @@ -0,0 +1,15 @@ +- name: pin dokku packages where requested + copy: + dest: /etc/apt/preferences.d/ansible-hold-{{ item.key }} + content: | + Package: {{ item.key }} + Pin: version {{ item.value }} + Pin-Priority: 1001 + mode: 0644 + when: item.value + +- name: remove pins from 'unpinned' dokku packages + file: + path: /etc/apt/preferences.d/ansible-hold-{{ item.key }} + state: absent + when: not item.value diff --git a/tasks/install.yml b/tasks/install.yml index f13d506..bbb89ec 100644 --- a/tasks/install.yml +++ b/tasks/install.yml @@ -58,14 +58,8 @@ tags: - dokku -- name: pin dokku packages - copy: - dest: /etc/apt/preferences.d/ansible-hold-{{ item.key }} - content: | - Package: {{ item.key }} - Pin: version {{ item.value }} - Pin-Priority: 1001 - mode: 0644 +- name: package pinning + include_tasks: install-pin.yml with_dict: plugn: "{{ plugn_version }}" sshcommand: "{{ sshcommand_version }}" @@ -77,12 +71,12 @@ - name: install dokku packages apt: - name: "{{ item.key }}={{ item.value }}" - with_dict: - plugn: "{{ plugn_version }}" - sshcommand: "{{ sshcommand_version }}" - herokuish: "{{ herokuish_version }}" - dokku: "{{ dokku_version }}" + name: + - plugn + - sshcommand + - herokuish + - dokku + state: "{{ dokku_packages_state }}" tags: - dokku - dokku-install