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 dhall bindings defined in the `dhall/` directory will need Dhall version `1.26.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_cli_version`: Version of clever cli tools, default to `2.6.1`.
  43 - `clever_user_path`: Path relative to ansible_user home dir where cli tools and helpers are installed default to `.local/bin`.
  44 - `clever_app_root`: Path of the application to deploy, default to `app_root` if defined or `"{{ playbook_dir }}/.."` otherwise. I.e. the default behavior will work fine if you define a playbook using this role in a one level deep directory (e.g. `deployment/`) of the root of the application.
  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 Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
  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
  86 Tests
  87 ----
  88
  89 The role is tested with automated continuous integration on Travis. Please check the `tests/` directory for other usage examples of this role.
  90
  91 License
  92 -------
  93
  94 BSD
  95
  96 Author Information
  97 ------------------
  98
  99 Developped at Fretlink (https://www.fretlink.com)