Document Swagger update procedure and add script (#6546)

.github/ISSUE_TEMPLATE/upgrade.md

@@ -38,6 +38,7 @@ _period: 14 days
   - [ ] … update to [GitLab](https://hub.docker.com/r/gitlab/gitlab-ce/tags) & [GitLab runner images](https://hub.docker.com/r/gitlab/gitlab-runner/tags) <sub>or no update available</sub>
   - [ ] … update to [ClamAV image](https://hub.docker.com/r/clamav/clamav/tags) <sub>or no update available</sub>
   - [ ] … update to [GitLab AMI](https://github.com/DataBiosphere/azul/blob/develop/OPERATOR.rst#updating-the-ami-for-gitlab-instances) <sub>or no update available</sub>
+  - [ ] … update to [Swagger UI](https://github.com/DataBiosphere/azul/blob/develop/OPERATOR.rst#updating-swagger-ui) <sub>or no update available</sub>
 - [ ] Created tickets for any deferred updates to …
   - [ ] … to next major or minor Python version <sub>or such ticket already exists</sub>
   - [ ] … to next major Docker version <sub>or such ticket already exists</sub>

OPERATOR.rst

@@ -412,6 +412,30 @@ SSH into the instance, and run ``sudo yum update`` followed by ``sudo reboot``.
 Wait for the GitLab web application to become available again and perform a
 ``git fetch`` from one of the Git repositories hosted on that instance.
 
+Updating Swagger UI
+^^^^^^^^^^^^^^^^^^^
+
+Operators should regularly check for available updates to the Swagger UI. The
+current version used by Azul is hardcoded in ``scripts/update_swagger.py``. The
+upstream source is located here:
+
+https://github.com/swagger-api/swagger-ui/tree/master/dist
+
+Scheduled upgrade PR's should only include minor and hotfix updates to the
+Swagger UI. If a new major version is available, open a new issue instead. To
+perform the update, edit the ``tag`` variable in the ``update_swagger`` script
+and run it. If there are nontrivial changes to the ``swagger-initializer.js``
+file, cancel the update and open a new issue; otherwise, forward any changes to
+that file to ``swagger-initializer.js.template.mustache``. Then commit the
+changes to the script and any modified files in the ``swagger/`` directory. The
+commit message must include the new tag, as well as a link to the upstream
+source in the commit body, e.g.::
+
+    Update Swagger UI to v<release version> (#issue-number)
+
+    https://github.com/swagger-api/swagger-ui/tree/v<release version>/dist
+
+
 Export AWS Inspector findings
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

scripts/update_swagger.py

@@ -0,0 +1,54 @@
+import logging
+from pathlib import (
+    Path,
+)
+
+from furl import (
+    furl,
+)
+
+from azul import (
+    config,
+    require,
+)
+from azul.http import (
+    http_client,
+)
+from azul.logging import (
+    configure_script_logging,
+)
+
+log = logging.getLogger(__name__)
+http = http_client(log)
+
+repository_url = 'https://raw.githubusercontent.com/swagger-api/swagger-ui'
+tag = 'v4.15.2'
+files = [
+    'oauth2-redirect.html',
+    'swagger-ui.css',
+    'swagger-ui-bundle.js',
+    'swagger-ui-standalone-preset.js',
+    # We don't directly serve this file, but we maintain a verbatim copy from
+    # the upstream distribution for reference.
+    'swagger-initializer.js'
+]
+
+swagger_dir = Path(config.project_root) / 'swagger'
+
+
+def download_file(name: str):
+    object_url = furl(repository_url) / tag / 'dist' / name
+    response = http.request('GET', str(object_url))
+    require(response.status == 200, name)
+    with open(swagger_dir / name, 'wb') as f:
+        f.write(response.data)
+
+
+def main():
+    for file_name in files:
+        download_file(file_name)
+
+
+if __name__ == '__main__':
+    configure_script_logging(log)
+    main()