From d72f94d3d67bedf5e4654cfd01e28af8830ebdb4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nicolas=20Mass=C3=A9?= <nicolas.masse@itix.fr>
Date: Thu, 21 Jun 2018 17:46:53 +0200
Subject: [PATCH] add doc on usage with tower

---
 README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/README.md b/README.md
index 9869aab..bef1863 100644
--- a/README.md
+++ b/README.md
@@ -490,6 +490,63 @@ This role has no dependencies on other roles, but it has dependencies on:
 - JMESPath
 - Jinja (at least version 2.8)
 
+## Usage in Ansible Tower
+
+If you want to use this role in Ansible Tower, the easiest way to do so is:
+
+- to have an inventory for each of your environments (dev, test, prod, etc.)
+- in those inventories, define a group (let's say `threescale`) containing
+  your 3scale Admin Portal(s)
+- set all the variables that depends on the environment (`threescale_cicd_wildcard_domain`, `threescale_cicd_api_environment_name`, etc.) as
+  group variables
+- create a playbook, committed in your GIT repository and reference it as a Project
+  in Tower
+- in this playbook, use the `assert` module to do some surface checks and set the variables that depends on the API being provisioned (such as `threescale_cicd_private_base_url`)
+- create the corresponding Job Template
+
+A very minimalistic playbook could be:
+
+```yaml
+---
+- name: Deploy an API on a 3scale instance
+  hosts: threescale
+  gather_facts: no
+  pre_tasks:
+  - assert:
+      that:
+      - "git_repo is defined"
+  - name: Clone the git repo containing the API Definition
+    git:
+      repo: '{{ git_repo }}'
+      dest: '{{ playbook_dir }}/api'
+      version: '{{ git_branch|default(''master'') }}'
+    delegate_to: localhost
+  - set_fact:
+      threescale_cicd_openapi_file: '{{ playbook_dir }}/api/{{ openapi_file|default(''openapi-spec.yaml'') }}'
+  roles:
+  - nmasse-itix.threescale-cicd
+```
+
+Then, make sure to reference this module in your `roles/requirements.yml` file:
+
+```yaml
+---
+- src: nmasse-itix.threescale-cicd
+  version: 0.0.4
+```
+
+You can reference a specific version like in this example or leave the `version`
+field out. This will pick the latest version available.
+
+**Caution:** once the role has been installed locally, it will never be
+automatically updated, even if you change the `version` field.
+
+To update this role to a more recent version use:
+
+```sh
+ansible-galaxy install -f nmasse-itix.threescale-cicd,0.0.5 -p roles/
+```
+
 ## License
 
 MIT