PageRenderTime 47ms CodeModel.GetById 13ms app.highlight 24ms RepoModel.GetById 2ms app.codeStats 0ms

/docsite/rst/guide_rax.rst

https://github.com/ajanthanm/ansible
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