/docsite/rst/guide_rax.rst
ReStructuredText | 592 lines | 472 code | 120 blank | 0 comment | 0 complexity | 63995dda5fd66b0bc42a1b13dcea73fd MD5 | raw file
1Rackspace Cloud Guide 2===================== 3 4.. _introduction: 5 6Introduction 7```````````` 8 9.. note:: This section of the documentation is under construction. We are in the process of adding more examples about the Rackspace modules and how they work together. Once complete, there will also be examples for Rackspace Cloud in `ansible-examples <http://github.com/ansible/ansible-examples/>`_. 10 11Ansible contains a number of core modules for interacting with Rackspace Cloud. 12 13The purpose of this section is to explain how to put Ansible modules together 14(and use inventory scripts) to use Ansible in a Rackspace Cloud context. 15 16Prerequisites for using the rax modules are minimal. In addition to ansible itself, 17all of the modules require and are tested against pyrax 1.5 or higher. 18You'll need this Python module installed on the execution host. 19 20pyrax is not currently available in many operating system 21package repositories, so you will likely need to install it via pip: 22 23.. code-block:: bash 24 25 $ pip install pyrax 26 27The following steps will often execute from the control machine against the Rackspace Cloud API, so it makes sense 28to add localhost to the inventory file. (Ansible may not require this manual step in the future): 29 30.. code-block:: ini 31 32 [localhost] 33 localhost ansible_connection=local 34 35In playbook steps, we'll typically be using the following pattern: 36 37.. code-block:: yaml 38 39 - hosts: localhost 40 connection: local 41 gather_facts: False 42 tasks: 43 44.. _credentials_file: 45 46Credentials File 47```````````````` 48 49The `rax.py` inventory script and all `rax` modules support a standard `pyrax` credentials file that looks like: 50 51.. code-block:: ini 52 53 [rackspace_cloud] 54 username = myraxusername 55 api_key = d41d8cd98f00b204e9800998ecf8427e 56 57Setting the environment parameter RAX_CREDS_FILE to the path of this file will help Ansible find how to load 58this information. 59 60More information about this credentials file can be found at 61https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating 62 63 64.. _virtual_environment: 65 66Running from a Python Virtual Environment (Optional) 67++++++++++++++++++++++++++++++++++++++++++++++++++++ 68 69Most users will not be using virtualenv, but some users, particularly Python developers sometimes like to. 70 71There are special considerations when Ansible is installed to a Python virtualenv, rather than the default of installing at a global scope. Ansible assumes, unless otherwise instructed, that the python binary will live at /usr/bin/python. This is done via the interpreter line in modules, however when instructed by setting the inventory variable 'ansible_python_interpreter', Ansible will use this specified path instead to find Python. This can be a cause of confusion as one may assume that modules running on 'localhost', or perhaps running via 'local_action', are using the virtualenv Python interpreter. By setting this line in the inventory, the modules will execute in the virtualenv interpreter and have available the virtualenv packages, specifically pyrax. If using virtualenv, you may wish to modify your localhost inventory definition to find this location as follows: 72 73.. code-block:: ini 74 75 [localhost] 76 localhost ansible_connection=local ansible_python_interpreter=/path/to/ansible_venv/bin/python 77 78.. note:: 79 80 pyrax may be installed in the global Python package scope or in a virtual environment. There are no special considerations to keep in mind when installing pyrax. 81 82.. _provisioning: 83 84Provisioning 85```````````` 86 87Now for the fun parts. 88 89The 'rax' module provides the ability to provision instances within Rackspace Cloud. Typically the provisioning task will be performed from your Ansible control server (in our example, localhost) against the Rackspace cloud API. This is done for several reasons: 90 91 - Avoiding installing the pyrax library on remote nodes 92 - No need to encrypt and distribute credentials to remote nodes 93 - Speed and simplicity 94 95.. note:: 96 97 Authentication with the Rackspace-related modules is handled by either 98 specifying your username and API key as environment variables or passing 99 them as module arguments, or by specifying the location of a credentials 100 file. 101 102Here is a basic example of provisioning an instance in ad-hoc mode: 103 104.. code-block:: bash 105 106 $ ansible localhost -m rax -a "name=awx flavor=4 image=ubuntu-1204-lts-precise-pangolin wait=yes" -c local 107 108Here's what it would look like in a playbook, assuming the parameters were defined in variables: 109 110.. code-block:: yaml 111 112 tasks: 113 - name: Provision a set of instances 114 local_action: 115 module: rax 116 name: "{{ rax_name }}" 117 flavor: "{{ rax_flavor }}" 118 image: "{{ rax_image }}" 119 count: "{{ rax_count }}" 120 group: "{{ group }}" 121 wait: yes 122 register: rax 123 124The rax module returns data about the nodes it creates, like IP addresses, hostnames, and login passwords. By registering the return value of the step, it is possible used this data to dynamically add the resulting hosts to inventory (temporarily, in memory). This facilitates performing configuration actions on the hosts in a follow-on task. In the following example, the servers that were successfully created using the above task are dynamically added to a group called "raxhosts", with each nodes hostname, IP address, and root password being added to the inventory. 125 126.. code-block:: yaml 127 128 - name: Add the instances we created (by public IP) to the group 'raxhosts' 129 local_action: 130 module: add_host 131 hostname: "{{ item.name }}" 132 ansible_ssh_host: "{{ item.rax_accessipv4 }}" 133 ansible_ssh_pass: "{{ item.rax_adminpass }}" 134 groupname: raxhosts 135 with_items: rax.success 136 when: rax.action == 'create' 137 138With the host group now created, the next play in this playbook could now configure servers belonging to the raxhosts group. 139 140.. code-block:: yaml 141 142 - name: Configuration play 143 hosts: raxhosts 144 user: root 145 roles: 146 - ntp 147 - webserver 148 149The method above ties the configuration of a host with the provisioning step. This isn't always what you want, and leads us 150to the next section. 151 152.. _host_inventory: 153 154Host Inventory 155`````````````` 156 157Once your nodes are spun up, you'll probably want to talk to them again. The best way to handle his is to use the "rax" inventory plugin, which dynamically queries Rackspace Cloud and tells Ansible what nodes you have to manage. You might want to use this even if you are spinning up Ansible via other tools, including the Rackspace Cloud user interface. The inventory plugin can be used to group resources by metadata, region, OS, etc. Utilizing metadata is highly recommended in "rax" and can provide an easy way to sort between host groups and roles. If you don't want to use the ``rax.py`` dynamic inventory script, you could also still choose to manually manage your INI inventory file, though this is less recommended. 158 159In Ansible it is quite possible to use multiple dynamic inventory plugins along with INI file data. Just put them in a common directory and be sure the scripts are chmod +x, and the INI-based ones are not. 160 161.. _raxpy: 162 163rax.py 164++++++ 165 166To use the rackspace dynamic inventory script, copy ``rax.py`` into your inventory directory and make it executable. You can specify a credentails file for ``rax.py`` utilizing the ``RAX_CREDS_FILE`` environment variable. 167 168.. note:: Dynamic inventory scripts (like ``rax.py``) are saved in ``/usr/share/ansible/inventory`` if Ansible has been installed globally. If installed to a virtualenv, the inventory scripts are installed to ``$VIRTUALENV/share/inventory``. 169 170.. note:: Users of :doc:`tower` will note that dynamic inventory is natively supported by Tower, and all you have to do is associate a group with your Rackspace Cloud credentials, and it will easily synchronize without going through these steps:: 171 172 $ RAX_CREDS_FILE=~/.raxpub ansible all -i rax.py -m setup 173 174``rax.py`` also accepts a ``RAX_REGION`` environment variable, which can contain an individual region, or a comma separated list of regions. 175 176When using ``rax.py``, you will not have a 'localhost' defined in the inventory. 177 178As mentioned previously, you will often be running most of these modules outside of the host loop, and will need 'localhost' defined. The recommended way to do this, would be to create an ``inventory`` directory, and place both the ``rax.py`` script and a file containing ``localhost`` in it. 179 180Executing ``ansible`` or ``ansible-playbook`` and specifying the ``inventory`` directory instead 181of an individual file, will cause ansible to evaluate each file in that directory for inventory. 182 183Let's test our inventory script to see if it can talk to Rackspace Cloud. 184 185.. code-block:: bash 186 187 $ RAX_CREDS_FILE=~/.raxpub ansible all -i inventory/ -m setup 188 189Assuming things are properly configured, the ``rax.py`` inventory script will output information similar to the 190following information, which will be utilized for inventory and variables. 191 192.. code-block:: json 193 194 { 195 "ORD": [ 196 "test" 197 ], 198 "_meta": { 199 "hostvars": { 200 "test": { 201 "ansible_ssh_host": "1.1.1.1", 202 "rax_accessipv4": "1.1.1.1", 203 "rax_accessipv6": "2607:f0d0:1002:51::4", 204 "rax_addresses": { 205 "private": [ 206 { 207 "addr": "2.2.2.2", 208 "version": 4 209 } 210 ], 211 "public": [ 212 { 213 "addr": "1.1.1.1", 214 "version": 4 215 }, 216 { 217 "addr": "2607:f0d0:1002:51::4", 218 "version": 6 219 } 220 ] 221 }, 222 "rax_config_drive": "", 223 "rax_created": "2013-11-14T20:48:22Z", 224 "rax_flavor": { 225 "id": "performance1-1", 226 "links": [ 227 { 228 "href": "https://ord.servers.api.rackspacecloud.com/111111/flavors/performance1-1", 229 "rel": "bookmark" 230 } 231 ] 232 }, 233 "rax_hostid": "e7b6961a9bd943ee82b13816426f1563bfda6846aad84d52af45a4904660cde0", 234 "rax_human_id": "test", 235 "rax_id": "099a447b-a644-471f-87b9-a7f580eb0c2a", 236 "rax_image": { 237 "id": "b211c7bf-b5b4-4ede-a8de-a4368750c653", 238 "links": [ 239 { 240 "href": "https://ord.servers.api.rackspacecloud.com/111111/images/b211c7bf-b5b4-4ede-a8de-a4368750c653", 241 "rel": "bookmark" 242 } 243 ] 244 }, 245 "rax_key_name": null, 246 "rax_links": [ 247 { 248 "href": "https://ord.servers.api.rackspacecloud.com/v2/111111/servers/099a447b-a644-471f-87b9-a7f580eb0c2a", 249 "rel": "self" 250 }, 251 { 252 "href": "https://ord.servers.api.rackspacecloud.com/111111/servers/099a447b-a644-471f-87b9-a7f580eb0c2a", 253 "rel": "bookmark" 254 } 255 ], 256 "rax_metadata": { 257 "foo": "bar" 258 }, 259 "rax_name": "test", 260 "rax_name_attr": "name", 261 "rax_networks": { 262 "private": [ 263 "2.2.2.2" 264 ], 265 "public": [ 266 "1.1.1.1", 267 "2607:f0d0:1002:51::4" 268 ] 269 }, 270 "rax_os-dcf_diskconfig": "AUTO", 271 "rax_os-ext-sts_power_state": 1, 272 "rax_os-ext-sts_task_state": null, 273 "rax_os-ext-sts_vm_state": "active", 274 "rax_progress": 100, 275 "rax_status": "ACTIVE", 276 "rax_tenant_id": "111111", 277 "rax_updated": "2013-11-14T20:49:27Z", 278 "rax_user_id": "22222" 279 } 280 } 281 } 282 } 283 284.. _standard_inventory: 285 286Standard Inventory 287++++++++++++++++++ 288 289When utilizing a standard ini formatted inventory file (as opposed to the inventory plugin), it may still be adventageous to retrieve discoverable hostvar information from the Rackspace API. 290 291This can be achieved with the ``rax_facts`` module and an inventory file similar to the following: 292 293.. code-block:: ini 294 295 [test_servers] 296 hostname1 rax_region=ORD 297 hostname2 rax_region=ORD 298 299.. code-block:: yaml 300 301 - name: Gather info about servers 302 hosts: test_servers 303 gather_facts: False 304 tasks: 305 - name: Get facts about servers 306 local_action: 307 module: rax_facts 308 credentials: ~/.raxpub 309 name: "{{ inventory_hostname }}" 310 region: "{{ rax_region }}" 311 - name: Map some facts 312 set_fact: 313 ansible_ssh_host: "{{ rax_accessipv4 }}" 314 315While you don't need to know how it works, it may be interesting to know what kind of variables are returned. 316 317The ``rax_facts`` module provides facts as followings, which match the ``rax.py`` inventory script: 318 319.. code-block:: json 320 321 { 322 "ansible_facts": { 323 "rax_accessipv4": "1.1.1.1", 324 "rax_accessipv6": "2607:f0d0:1002:51::4", 325 "rax_addresses": { 326 "private": [ 327 { 328 "addr": "2.2.2.2", 329 "version": 4 330 } 331 ], 332 "public": [ 333 { 334 "addr": "1.1.1.1", 335 "version": 4 336 }, 337 { 338 "addr": "2607:f0d0:1002:51::4", 339 "version": 6 340 } 341 ] 342 }, 343 "rax_config_drive": "", 344 "rax_created": "2013-11-14T20:48:22Z", 345 "rax_flavor": { 346 "id": "performance1-1", 347 "links": [ 348 { 349 "href": "https://ord.servers.api.rackspacecloud.com/111111/flavors/performance1-1", 350 "rel": "bookmark" 351 } 352 ] 353 }, 354 "rax_hostid": "e7b6961a9bd943ee82b13816426f1563bfda6846aad84d52af45a4904660cde0", 355 "rax_human_id": "test", 356 "rax_id": "099a447b-a644-471f-87b9-a7f580eb0c2a", 357 "rax_image": { 358 "id": "b211c7bf-b5b4-4ede-a8de-a4368750c653", 359 "links": [ 360 { 361 "href": "https://ord.servers.api.rackspacecloud.com/111111/images/b211c7bf-b5b4-4ede-a8de-a4368750c653", 362 "rel": "bookmark" 363 } 364 ] 365 }, 366 "rax_key_name": null, 367 "rax_links": [ 368 { 369 "href": "https://ord.servers.api.rackspacecloud.com/v2/111111/servers/099a447b-a644-471f-87b9-a7f580eb0c2a", 370 "rel": "self" 371 }, 372 { 373 "href": "https://ord.servers.api.rackspacecloud.com/111111/servers/099a447b-a644-471f-87b9-a7f580eb0c2a", 374 "rel": "bookmark" 375 } 376 ], 377 "rax_metadata": { 378 "foo": "bar" 379 }, 380 "rax_name": "test", 381 "rax_name_attr": "name", 382 "rax_networks": { 383 "private": [ 384 "2.2.2.2" 385 ], 386 "public": [ 387 "1.1.1.1", 388 "2607:f0d0:1002:51::4" 389 ] 390 }, 391 "rax_os-dcf_diskconfig": "AUTO", 392 "rax_os-ext-sts_power_state": 1, 393 "rax_os-ext-sts_task_state": null, 394 "rax_os-ext-sts_vm_state": "active", 395 "rax_progress": 100, 396 "rax_status": "ACTIVE", 397 "rax_tenant_id": "111111", 398 "rax_updated": "2013-11-14T20:49:27Z", 399 "rax_user_id": "22222" 400 }, 401 "changed": false 402 } 403 404 405Use Cases 406````````` 407 408This section covers some additional usage examples built around a specific use case. 409 410.. _example_1: 411 412Example 1 413+++++++++ 414 415Create an isolated cloud network and build a server 416 417.. code-block:: yaml 418 419 - name: Build Servers on an Isolated Network 420 hosts: localhost 421 connection: local 422 gather_facts: False 423 tasks: 424 - name: Network create request 425 local_action: 426 module: rax_network 427 credentials: ~/.raxpub 428 label: my-net 429 cidr: 192.168.3.0/24 430 region: IAD 431 state: present 432 433 - name: Server create request 434 local_action: 435 module: rax 436 credentials: ~/.raxpub 437 name: web%04d.example.org 438 flavor: 2 439 image: ubuntu-1204-lts-precise-pangolin 440 disk_config: manual 441 networks: 442 - public 443 - my-net 444 region: IAD 445 state: present 446 count: 5 447 exact_count: yes 448 group: web 449 wait: yes 450 wait_timeout: 360 451 register: rax 452 453.. _example_2: 454 455Example 2 456+++++++++ 457 458Build a complete webserver environment with servers, custom networks and load balancers, install nginx and create a custom index.html 459 460.. code-block:: yaml 461 462 --- 463 - name: Build environment 464 hosts: localhost 465 connection: local 466 gather_facts: False 467 tasks: 468 - name: Load Balancer create request 469 local_action: 470 module: rax_clb 471 credentials: ~/.raxpub 472 name: my-lb 473 port: 80 474 protocol: HTTP 475 algorithm: ROUND_ROBIN 476 type: PUBLIC 477 timeout: 30 478 region: IAD 479 wait: yes 480 state: present 481 meta: 482 app: my-cool-app 483 register: clb 484 485 - name: Network create request 486 local_action: 487 module: rax_network 488 credentials: ~/.raxpub 489 label: my-net 490 cidr: 192.168.3.0/24 491 state: present 492 region: IAD 493 register: network 494 495 - name: Server create request 496 local_action: 497 module: rax 498 credentials: ~/.raxpub 499 name: web%04d.example.org 500 flavor: performance1-1 501 image: ubuntu-1204-lts-precise-pangolin 502 disk_config: manual 503 networks: 504 - public 505 - private 506 - my-net 507 region: IAD 508 state: present 509 count: 5 510 exact_count: yes 511 group: web 512 wait: yes 513 register: rax 514 515 - name: Add servers to web host group 516 local_action: 517 module: add_host 518 hostname: "{{ item.name }}" 519 ansible_ssh_host: "{{ item.rax_accessipv4 }}" 520 ansible_ssh_pass: "{{ item.rax_adminpass }}" 521 ansible_ssh_user: root 522 groupname: web 523 with_items: rax.success 524 when: rax.action == 'create' 525 526 - name: Add servers to Load balancer 527 local_action: 528 module: rax_clb_nodes 529 credentials: ~/.raxpub 530 load_balancer_id: "{{ clb.balancer.id }}" 531 address: "{{ item.rax_networks.private|first }}" 532 port: 80 533 condition: enabled 534 type: primary 535 wait: yes 536 region: IAD 537 with_items: rax.success 538 when: rax.action == 'create' 539 540 - name: Configure servers 541 hosts: web 542 handlers: 543 - name: restart nginx 544 service: name=nginx state=restarted 545 546 tasks: 547 - name: Install nginx 548 apt: pkg=nginx state=latest update_cache=yes cache_valid_time=86400 549 notify: 550 - restart nginx 551 552 - name: Ensure nginx starts on boot 553 service: name=nginx state=started enabled=yes 554 555 - name: Create custom index.html 556 copy: content="{{ inventory_hostname }}" dest=/usr/share/nginx/www/index.html 557 owner=root group=root mode=0644 558 559 560.. _advanced_usage: 561 562Advanced Usage 563`````````````` 564 565.. _awx_autoscale: 566 567Autoscaling with Tower 568++++++++++++++++++++++ 569 570:doc:`tower` also contains a very nice feature for auto-scaling use cases. 571In this mode, a simple curl script can call a defined URL and the server will "dial out" to the requester 572and configure an instance that is spinning up. This can be a great way to reconfigure ephemeral nodes. 573See the Tower documentation for more details. 574 575A benefit of using the callback in Tower over pull mode is that job results are still centrally recorded 576and less information has to be shared with remote hosts. 577 578.. _pending_information: 579 580Orchestration in the Rackspace Cloud 581++++++++++++++++++++++++++++++++++++ 582 583Ansible is a powerful orchestration tool, and rax modules allow you the opportunity to orchestrate complex tasks, deployments, and configurations. The key here is to automate provisioning of infrastructure, like any other pice of software in an environment. Complex deployments might have previously required manual manipulation of load balancers, or manual provisioning of servers. Utilizing the rax modules included with Ansible, one can make the deployment of additional nodes contingent on the current number of running nodes, or the configuration of a clustered application dependent on the number of nodes with common metadata. One could automate the following scenarios, for example: 584 585* Servers that are removed from a Cloud Load Balancer one-by-one, updated, verified, and returned to the load balancer pool 586* Expansion of an already-online environment, where nodes are provisioned, bootstrapped, configured, and software installed 587* A procedure where app log files are uploaded to a central location, like Cloud Files, before a node is decommissioned 588* Servers and load balancers that have DNS records created and destroyed on creation and decommissioning, respectively 589 590 591 592