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.
dokku · Feb 3, 2021 · 0f8ce10 · 0f8ce10
1 parent 2078e42
commit 0f8ce10
Show file tree

Hide file tree

Showing 6 changed files with 114 additions and 56 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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