|
| 1 | +.. _provisioners: |
| 2 | + |
| 3 | +Provisioners |
| 4 | +============ |
| 5 | + |
| 6 | +.. toctree:: |
| 7 | + :maxdepth: 2 |
| 8 | + |
| 9 | +Introduction |
| 10 | +------------ |
| 11 | + |
| 12 | +* Cloud Deploy can use any combination of Ansible and Saltstack provisioners to build AMIs. |
| 13 | +* Each Cloud Deploy feature is a Saltstack formula or an Ansible role. |
| 14 | +* Saltstack is enabled by default to build AMIs. |
| 15 | +* Provisioners configurations are managed in the Cloud Deploy configuration file. |
| 16 | +* Cloud Deploy uses git repositories to get provisioners' code. |
| 17 | +* Cloud Deploy needs access to each git repositories with at least a read permission. |
| 18 | +* In the WebUI, each feature variable can be filled with an input field. Entreprise_License_. |
| 19 | + |
| 20 | +How to configure a Saltstack provisioner feature |
| 21 | +------------------------------------------------ |
| 22 | + |
| 23 | +A Saltstack provisioner feature is basically a Saltstack formula that takes 2 arguments: |
| 24 | + |
| 25 | +* The formula's name |
| 26 | +* The input variable to set |
| 27 | + |
| 28 | +A formula that takes more than one variable has to be declared multiple times. |
| 29 | + |
| 30 | +For example, using a formula that installs package using a package variable as input has to be declared this way: |
| 31 | + |
| 32 | ++--------------+---------------------------------+ |
| 33 | +| Feature Name | Feature Value | |
| 34 | ++==============+=================================+ |
| 35 | +| pkg | package=htop | |
| 36 | ++--------------+---------------------------------+ |
| 37 | +| pkg | package=nginx | |
| 38 | ++--------------+---------------------------------+ |
| 39 | + |
| 40 | +**Note:** To pass multiple values for the same variable the feature has to be delared multiple times. |
| 41 | + |
| 42 | +The feature's name will be mapped to a Saltstack formula's name and the feature's value will be mapped to a Saltstack pillar. The following files should be generated by Cloud Deploy: |
| 43 | + |
| 44 | +*Sample salt/top.sls* |
| 45 | + |
| 46 | +.. code-block:: yaml |
| 47 | +
|
| 48 | + base: |
| 49 | + '*': |
| 50 | + - common |
| 51 | + - pkg |
| 52 | +
|
| 53 | +**Note:** The ``common`` formula is included by default, this formula should contain some system upgrade or common packages installation for all buildd AMI's. |
| 54 | + |
| 55 | +*Sample pillar/top.sls* |
| 56 | + |
| 57 | +.. code-block:: yaml |
| 58 | +
|
| 59 | + base: |
| 60 | + '*': |
| 61 | + - features |
| 62 | + - mypillar |
| 63 | +
|
| 64 | +**Note:** An additional pillar file can be added to load common variables for example here ``mypillar``, see additional_pillar_. |
| 65 | + |
| 66 | +*Sample pillar/features.sls* |
| 67 | + |
| 68 | +.. code-block:: yaml |
| 69 | +
|
| 70 | + pkg: |
| 71 | + version: '' |
| 72 | + package: |
| 73 | + - htop |
| 74 | + - nginx |
| 75 | +
|
| 76 | +**Note:** By default a feature that has no variable name is mapped to a variable ``version``, this is a legacy behavior. |
| 77 | + |
| 78 | +How to configure Saltstack provisioner repository |
| 79 | +------------------------------------------------- |
| 80 | + |
| 81 | +Use the ``features_provisioners`` section of the Cloud Deploy configuration file to declare the repository and the tag to use as follow |
| 82 | + |
| 83 | +.. code-block:: yaml |
| 84 | +
|
| 85 | + features_provisioners: |
| 86 | + salt: |
| 87 | + git_repo: [email protected]:myaccount/my-salt-formulas.git |
| 88 | + git_revision: v1.0.0 |
| 89 | +
|
| 90 | +.. _additional_pillar: |
| 91 | + |
| 92 | +Additional pillar file can be loaded using the ``salt_additonal_pillar`` propertie as follow in the ``salt`` section |
| 93 | + |
| 94 | +.. code-block:: yaml |
| 95 | +
|
| 96 | + salt_additional_pillar: mypillar |
| 97 | +
|
| 98 | +**Note:** A ``pillar/mypillar.sls`` must exist in the Saltstack repository if an additionnal pillar is set. |
| 99 | + |
| 100 | +The Saltstack provisioner can use only one repository at a time containing all the saltstack hierarchy as follow |
| 101 | + |
| 102 | +.. code-block:: sh |
| 103 | +
|
| 104 | + my-salt-formulas/ |
| 105 | + |_salt/ |
| 106 | + | |_nginx/ |
| 107 | + | |_apache/ |
| 108 | + |_pillar/ |
| 109 | + | |_top.sls |
| 110 | + | |_mypillar.sls |
| 111 | + |_top.sls |
| 112 | +
|
| 113 | +The Cloud Deploy WebUI uses a json inventory to expose a list of available formulas that use a json_form plugin. The url of this file can be set using the ``salt_role_inventory_url`` property. Entreprise_License_. |
| 114 | + |
| 115 | +Here is an example of json inventory: |
| 116 | + |
| 117 | +.. code-block:: json |
| 118 | +
|
| 119 | + [ |
| 120 | + "nginx", |
| 121 | + "apache", |
| 122 | + "mysql" |
| 123 | + ] |
| 124 | +
|
| 125 | +
|
| 126 | +
|
| 127 | +How to configure an Ansible provisioner feature |
| 128 | +----------------------------------------------- |
| 129 | + |
| 130 | +An Ansible provisioner feature is basically an Ansible role that takes 2 arguments: |
| 131 | + |
| 132 | +* The role's name |
| 133 | +* The input yml document to pass as variable |
| 134 | + |
| 135 | +A role can take a complex variable structure. |
| 136 | + |
| 137 | +For example, using a role that installs package using a complex variable structure as input as to be declared this way: |
| 138 | + |
| 139 | ++--------------+-------------------------------------+ |
| 140 | +| Feature Name | Feature Value | |
| 141 | ++==============+=====================================+ |
| 142 | +| apt | .. code-block:: yaml | |
| 143 | +| | | |
| 144 | +| | apt_autoremove: true | |
| 145 | +| | apt_force: false | |
| 146 | +| | apt_install_recommends: false | |
| 147 | +| | apt_packages: | |
| 148 | +| | - {name: apache2} | |
| 149 | +| | - {name: htop} | |
| 150 | +| | apt_repositories: | |
| 151 | +| | - {update_cache: false} | |
| 152 | +| | apt_upgrade: false | |
| 153 | ++--------------+-------------------------------------+ |
| 154 | + |
| 155 | +How to configure Ansible provisioner repository |
| 156 | +----------------------------------------------- |
| 157 | + |
| 158 | +Use the ``features_provisioners`` section of the Cloud Deploy configuration file to declare the repository and the tag to use as follow |
| 159 | + |
| 160 | +.. code-block:: yaml |
| 161 | +
|
| 162 | + features_provisioners: |
| 163 | + ansible: |
| 164 | + git_repo: [email protected]:myaccount/my-ansible-galaxy-requirement.git |
| 165 | + git_revision: v1.0.0 |
| 166 | +
|
| 167 | +**Note:** the repository must have a yaml file containing the role catalog as Ansible Galaxy requirement file https://docs.ansible.com/ansible/latest/reference_appendices/galaxy.html#installing-multiple-roles-from-a-file |
| 168 | + |
| 169 | +Here is an example of requirement file: |
| 170 | + |
| 171 | +.. code-block:: yaml |
| 172 | +
|
| 173 | + # from galaxy |
| 174 | + - src: yatesr.timezone |
| 175 | + |
| 176 | + # from GitHub |
| 177 | + - src: https://github.com/bennojoy/nginx |
| 178 | + |
| 179 | + # from GitHub, overriding the name and specifying a specific tag |
| 180 | + - src: https://github.com/bennojoy/nginx |
| 181 | + version: master |
| 182 | + name: nginx_role |
| 183 | +
|
| 184 | + # from a webserver, where the role is packaged in a tar.gz |
| 185 | + - src: https://some.webserver.example.com/files/master.tar.gz |
| 186 | + name: http-role |
| 187 | + |
| 188 | + # from Bitbucket |
| 189 | + - src: git+http://bitbucket.org/willthames/git-ansible-galaxy |
| 190 | + version: v1.4 |
| 191 | +
|
| 192 | +The name and path of the requirement file is ``requirements.yml`` by default but can be overrided using the property ``ansible_galaxy_requirements_path``. |
| 193 | + |
| 194 | +Cloud Deploy uses a base playbook executed at each BuildImage. This playbook usually contains upgrades commands and base package installation. The path of the requirement file and the path of the base playbook file can be set using the following properties ``base_playbook_requirements_file`` and ``base_playbook_file``. |
| 195 | + |
| 196 | +The Cloud Deploy WebUI uses a json inventory to create a dynamic form with the roles variables that use a json_form plugin. The url of this file can be set using the propertie ``ansible_role_inventory_url``. Entreprise_License_. |
| 197 | + |
| 198 | +Here is an example of json inventory: |
| 199 | + |
| 200 | +.. code-block:: json |
| 201 | +
|
| 202 | + [ |
| 203 | + { |
| 204 | + "name": "package", |
| 205 | + "type": "object", |
| 206 | + "properties": |
| 207 | + { |
| 208 | + "package_name": |
| 209 | + { |
| 210 | + "title": "Package name, or package specifier with version, like name-1.0", |
| 211 | + "type": "array", |
| 212 | + "items": |
| 213 | + { |
| 214 | + "type": "string" |
| 215 | + } |
| 216 | + } |
| 217 | + } |
| 218 | + } |
| 219 | + ] |
| 220 | +
|
| 221 | +.. _Entreprise_License: |
| 222 | + |
| 223 | +**Note:** The WebUI is available only for Claranet customers or with Enterprise license. |
0 commit comments