README.md

   1 # ansible-clever
   2
   3 [![Build Status](https://travis-ci.com/fretlink/ansible-clever.svg?token=D3nFpUxMu7vStDHwUNy4&branch=master)](https://travis-ci.com/fretlink/ansible-clever)
   4
   5 Ansible role for Clever Cloud deployment
   6 =======
   7
   8 This role deploys applications on clever cloud (https://www.clever-cloud.com).
   9 It handles the publication over git, as well as configuring domain names, environment variables and log drains, dedicated build instances, and scalability parameters.
  10
  11 Requirements
  12 ------------
  13
  14 This role requires [`clever-tools`](https://github.com/CleverCloud/clever-tools) CLI version `2.6.1` or higher.
  15
  16 If you want to configure this role with [Dhall](https://dhall-lang.org/) instead of YAML, the role publishes dhall bindings defined in the `dhall/package.dhall` file. These bindings will need Dhall version `1.29.0` or higher.
  17
  18 Role Variables
  19 --------------
  20
  21 Variables for the application:
  22
  23 - `clever_token`: clever_cloud token, **mandatory**.
  24 - `clever_secret`: clever_cloud secret, **mandatory**.
  25 - `clever_app`: the id of the app to link, **mandatory**.
  26 - `clever_env`: a dict of environment variables to add to the application, optional.
  27 - `clever_addons`: a list of dict describing addons enabled for the application from which we would use information during deploy, optional.<br/>
  28   Example: `{ name: pg, env_prefix: POSTGRESQL_ADDON }`
  29 - `clever_app_tasks_file`: path to an Ansible tasks file to be executed after environment and addons variables where gathered. Specific to an application and should be use to run migrations for example. Optional.
  30 - `clever_domain`: the domain from which the application should be reachable, optional.
  31 - `clever_syslog_server`: UDP Syslog server to be used as UDPSyslog drain for the application, optional. Example: `udp://198.51.100.51:12345`.
  32 - _Obsolete_: `clever_metrics`: metrics used to be disabled by default. Now they are enabled by default on Clever-Cloud and can be explicitly disabled with the `clever_disable_metrics` variable.
  33 - `clever_disable_metrics`: a boolean to disable metrics support. Optional, default to `false`.
  34 - `clever_env_output_file`: as a post deploy task you might need to retrieve the full Clever environment configuration (i.e. with addon env variables). If this variable is set to a filename then the env will be retrieved after a successful deploy and written to this file. Beware, the resulting file will contain sensitive information (addon passwords, …). Optional.
  35 - `clever_build_flavor`: an optional text value used to configure the size of the dedicated build instance (for instance `S` or `XL`). If not defined, it delegates to clever cloud default behaviour. Setting `disabled` disables the dedicated build instance altogether.
  36 - `clever_scaling`: an optional object used to configure the runtime instances flavours and numbers. If not defined, it delegates to clever cloud default behaviour.
  37 - `clever_service_dependencies`: a list of the service dependencies needed by the application (each service being a dict containing either an `app_id` field, or an `addon_id` field), optional.<br/>
  38   Example: `[{ addon_id: addon_00000000-0000-0000-0000-000000000000 }, { app_id: app_00000000-0000-0000-0000-000000000000 }]`
  39
  40 Variables **specific to deployment**, defaults should be fine:
  41
  42 - `clever_app_root`: Path of the application to deploy, default to `app_root` if defined or `"{{ playbook_dir }}/.."` otherwise. I.e. the default behaviour will work fine if you define a playbook using this role within a directory (e.g. `deployment/` located at the root of the application.
  43 - `clever_cli_version`: Version of clever cli tools, default to `2.6.1`.
  44 - `clever_user_path`: Path relative to ansible_user home dir where cli tools and helpers are installed default to `.local/bin`.
  45 - `clever_app_confdir`: Path where to store clever cloud data specific to this application, default to `"{{ clever_app_root }}/.clever_cloud"`
  46 - `clever_login_file`: Path to store login information. Default to `"{{ clever_app_confdir }}/login"`.
  47 - `clever_restart_only`: set to `true` to skip any deployment related tasks (domain, scaling, env, deploy, …) and only restart the application. Optional.
  48
  49 Variables specific to Haskell applications:
  50
  51 - `clever_haskell_entry_point`: the haskell executable name to be executed by clever cloud, optional.
  52
  53 Scaling configuration
  54 ---------------------
  55
  56 ```yaml
  57 clever_scaling:
  58   # instances and flavors are optional and can be configured as
  59   # either a fixed value (with `fixed`) or a range # (with `min` and `max`)
  60   flavors:
  61     fixed: XS
  62   instances:
  63     min: 2
  64     max: 5
  65 ```
  66
  67 Dependencies
  68 ------------
  69
  70 None
  71
  72 Example Playbook
  73 ----------------
  74
  75 This is the most basic usage of the role by specifying at least the clever app id and a clever token & secret pair.
  76
  77     - hosts: localhost
  78       roles:
  79          - role: fretlink.clever,
  80            vars:
  81              clever_app: app_00000000-0000-0000-0000-000000000000,
  82              clever_token: "{{ vault_clever_token }}",
  83              clever_secret: "{{ vault_clever_secret}}"
  84
  85 If you only need a task to restart your clever application, this would be enough:
  86
  87     - hosts: localhost
  88       roles:
  89          - role: fretlink.clever,
  90            vars:
  91              clever_app: app_00000000-0000-0000-0000-000000000000,
  92              clever_token: "{{ vault_clever_token }}",
  93              clever_secret: "{{ vault_clever_secret}}"
  94              clever_restart_only: true
  95
  96 Tests
  97 ----
  98
  99 The role is tested with automated continuous integration on Travis. Please check the `tests/` directory for other usage examples of this role.
 100
 101 License
 102 -------
 103
 104 MIT (see LICENSE file for details)
 105
 106 Author Information
 107 ------------------
 108
 109 Developed at [Fretlink](https://tech.fretlink.com)