diff options
| author | Alicia Cozine <879121+acozine@users.noreply.github.com> | 2019-04-04 18:58:30 +0200 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2019-04-04 18:58:30 +0200 |
| commit | a4d0bc2c43a4734fbf57ea2e9553ea3c03258c20 (patch) | |
| tree | 0558ccc93329988643d0ade46350d42fc7194ded | |
| parent | fix missing attribs with dirct module execution (#53875) (diff) | |
| download | ansible-a4d0bc2c43a4734fbf57ea2e9553ea3c03258c20.tar.xz ansible-a4d0bc2c43a4734fbf57ea2e9553ea3c03258c20.zip | |
Shortens Scenario Guides, incorporates vmware guide (#54554)
* Shortens Scenario Guides, incorporates vmware guide
* adds links from network scenario guides to other network docs
30 files changed, 226 insertions, 177 deletions
diff --git a/docs/docsite/rst/index.rst b/docs/docsite/rst/index.rst index cd3418743b..b94f53e3c5 100644 --- a/docs/docsite/rst/index.rst +++ b/docs/docsite/rst/index.rst @@ -47,16 +47,12 @@ Ansible releases a new major release of Ansible approximately three to four time .. toctree:: :glob: - :maxdepth: 2 - :caption: Scenario Guides - - scenario_guides/guide_* - -.. toctree:: - :maxdepth: 2 - :caption: Ansible for VMWare + :maxdepth: 1 + :caption: Common Ansible Scenarios - vmware/index + scenario_guides/cloud_guides + scenario_guides/network_guides + scenario_guides/virt_guides .. toctree:: :maxdepth: 2 diff --git a/docs/docsite/rst/scenario_guides/cloud_guides.rst b/docs/docsite/rst/scenario_guides/cloud_guides.rst new file mode 100644 index 0000000000..a2e21b4315 --- /dev/null +++ b/docs/docsite/rst/scenario_guides/cloud_guides.rst @@ -0,0 +1,21 @@ +.. _cloud_guides: + +******************* +Public Cloud Guides +******************* + +The guides in this section cover using Ansible with a range of public cloud platforms. They explore particular use cases in greater depth and provide a more "top-down" explanation of some basic features. + +.. toctree:: + :maxdepth: 1 + + guide_alicloud + guide_aws + guide_cloudstack + guide_gce + guide_azure + guide_online + guide_packet + guide_rax + guide_scaleway + guide_vultr diff --git a/docs/docsite/rst/scenario_guides/guide_docker.rst b/docs/docsite/rst/scenario_guides/guide_docker.rst index fb50c53226..4c8ea77e95 100644 --- a/docs/docsite/rst/scenario_guides/guide_docker.rst +++ b/docs/docsite/rst/scenario_guides/guide_docker.rst @@ -1,5 +1,5 @@ -Getting Started with Docker -=========================== +Docker Guide +============ Ansible offers the following modules for orchestrating Docker containers: @@ -327,7 +327,3 @@ For the default host and each host in the hosts list define the following attrib description: The port containers use for SSH required: false default: 22 - - - - diff --git a/docs/docsite/rst/scenario_guides/guide_kubernetes.rst b/docs/docsite/rst/scenario_guides/guide_kubernetes.rst index 56bb5e2e0b..4e20a05549 100644 --- a/docs/docsite/rst/scenario_guides/guide_kubernetes.rst +++ b/docs/docsite/rst/scenario_guides/guide_kubernetes.rst @@ -1,5 +1,5 @@ -Getting Started with Kubernetes and OpenShift -============================================= +Kubernetes and OpenShift Guide +============================== Modules for interacting with the Kubernetes (K8s) and OpenShift API are under development, and can be used in preview mode. To use them, review the requirements, and then follow the installation and use instructions. @@ -53,4 +53,3 @@ Filing issues If you find a bug or have a suggestion regarding individual modules or the role, please file issues at `OpenShift Rest Client issues <https://github.com/openshift/openshift-restclient-python/issues>`_. There is also a utility module, k8s_common.py, that is part of the `Ansible <https://github.com/ansible/ansible>`_ repo. If you find a bug or have suggestions regarding it, please file issues at `Ansible issues <https://github.com/ansible/ansible/issues>`_. - diff --git a/docs/docsite/rst/scenario_guides/guide_online.rst b/docs/docsite/rst/scenario_guides/guide_online.rst index 4427ce8bd3..2c181a949c 100644 --- a/docs/docsite/rst/scenario_guides/guide_online.rst +++ b/docs/docsite/rst/scenario_guides/guide_online.rst @@ -1,6 +1,6 @@ -************************* -Using Ansible with Online -************************* +**************** +Online.net Guide +**************** Introduction ============ diff --git a/docs/docsite/rst/scenario_guides/guide_scaleway.rst b/docs/docsite/rst/scenario_guides/guide_scaleway.rst index 5298574ee6..82d7ace757 100644 --- a/docs/docsite/rst/scenario_guides/guide_scaleway.rst +++ b/docs/docsite/rst/scenario_guides/guide_scaleway.rst @@ -1,8 +1,8 @@ .. _guide_scaleway: -*************************** -Using Scaleway with Ansible -*************************** +************** +Scaleway Guide +************** .. _scaleway_introduction: diff --git a/docs/docsite/rst/scenario_guides/guide_vagrant.rst b/docs/docsite/rst/scenario_guides/guide_vagrant.rst index 74a04d66d0..5ec362bf85 100644 --- a/docs/docsite/rst/scenario_guides/guide_vagrant.rst +++ b/docs/docsite/rst/scenario_guides/guide_vagrant.rst @@ -1,5 +1,5 @@ -Using Vagrant and Ansible -========================= +Vagrant Guide +============= .. _vagrant_intro: @@ -151,4 +151,3 @@ The "Tips and Tricks" chapter of the `Ansible Provisioner documentation The open issues for the Ansible provisioner in the Vagrant project :ref:`working_with_playbooks` An introduction to playbooks - diff --git a/docs/docsite/rst/scenario_guides/guide_vmware.rst b/docs/docsite/rst/scenario_guides/guide_vmware.rst new file mode 100644 index 0000000000..e34af8e22f --- /dev/null +++ b/docs/docsite/rst/scenario_guides/guide_vmware.rst @@ -0,0 +1,30 @@ +.. _vmware_ansible: + +****************** +VMware Guide +****************** + +Welcome to the Ansible for VMware Guide! + +The purpose of this guide is to teach you everything you need to know about using Ansible with VMware. + +To get started, please select one of the following topics. + +.. toctree:: + :maxdepth: 1 + + vmware_scenarios/vmware_intro + vmware_scenarios/vmware_concepts + vmware_scenarios/vmware_requirements + vmware_scenarios/vmware_inventory + vmware_scenarios/vmware_scenarios + vmware_scenarios/vmware_troubleshooting + vmware_scenarios/vmware_external_doc_links + vmware_scenarios/faq +.. comments look like this - start with two dots +.. getting_started content not ready +.. vmware_scenarios/vmware_getting_started +.. module index page not ready +.. vmware_scenarios/vmware_module_reference +.. always exclude the template file +.. vmware_scenarios/vmware_scenario_1 diff --git a/docs/docsite/rst/scenario_guides/guides.rst b/docs/docsite/rst/scenario_guides/guides.rst index 958937fdab..65a40b98c7 100644 --- a/docs/docsite/rst/scenario_guides/guides.rst +++ b/docs/docsite/rst/scenario_guides/guides.rst @@ -1,15 +1,42 @@ :orphan: -*************** +.. unified index page included for backwards compatibility + +****************** Scenario Guides -*************** +****************** + +The guides in this section cover integrating Ansible with a variety of +platforms, products, and technologies. They explore particular use cases in greater depth and provide a more "top-down" explanation of some basic features. + +.. toctree:: + :maxdepth: 1 + :caption: Public Cloud Guides -The guides in this section explore particular use cases in greater depth and provide a more "top-down" explanation of some basic features. + guide_alicloud + guide_aws + guide_cloudstack + guide_gce + guide_azure + guide_online + guide_packet + guide_rax + guide_scaleway + guide_vultr .. toctree:: - :glob: :maxdepth: 1 + :caption: Network Technology Guides + + guide_aci + guide_meraki + guide_infoblox - guide_* +.. toctree:: + :maxdepth: 1 + :caption: Virtualization & Containerization Guides -Pending topics may include: Jenkins, Linode/DigitalOcean, Continuous Deployment, and more. + guide_docker + guide_kubernetes + guide_vagrant + guide_vmware diff --git a/docs/docsite/rst/scenario_guides/network_guides.rst b/docs/docsite/rst/scenario_guides/network_guides.rst new file mode 100644 index 0000000000..2b538ff05e --- /dev/null +++ b/docs/docsite/rst/scenario_guides/network_guides.rst @@ -0,0 +1,16 @@ +.. _network_guides: + +************************* +Network Technology Guides +************************* + +The guides in this section cover using Ansible with specific network technologies. They explore particular use cases in greater depth and provide a more "top-down" explanation of some basic features. + +.. toctree:: + :maxdepth: 1 + + guide_aci + guide_meraki + guide_infoblox + +To learn more about Network Automation with Ansible, see :ref:`network_getting_started` and :ref:`network_advanced`. diff --git a/docs/docsite/rst/scenario_guides/virt_guides.rst b/docs/docsite/rst/scenario_guides/virt_guides.rst new file mode 100644 index 0000000000..b623799fdc --- /dev/null +++ b/docs/docsite/rst/scenario_guides/virt_guides.rst @@ -0,0 +1,15 @@ +.. _virtualization_guides: + +****************************************** +Virtualization and Containerization Guides +****************************************** + +The guides in this section cover integrating Ansible with popular tools for creating virtual machines and containers. They explore particular use cases in greater depth and provide a more "top-down" explanation of some basic features. + +.. toctree:: + :maxdepth: 1 + + guide_docker + guide_kubernetes + guide_vagrant + guide_vmware diff --git a/docs/docsite/rst/vmware/faq.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/faq.rst index 5dd04cb0f5..5dd04cb0f5 100644 --- a/docs/docsite/rst/vmware/faq.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/faq.rst diff --git a/docs/docsite/rst/vmware/scenario_clone_template.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_clone_template.rst index 2c3fb9e1e7..2c3fb9e1e7 100644 --- a/docs/docsite/rst/vmware/scenario_clone_template.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_clone_template.rst diff --git a/docs/docsite/rst/vmware/scenario_find_vm_folder.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_find_vm_folder.rst index 62758867c4..62758867c4 100644 --- a/docs/docsite/rst/vmware/scenario_find_vm_folder.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_find_vm_folder.rst diff --git a/docs/docsite/rst/vmware/scenario_remove_vm.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_remove_vm.rst index fb5c71522f..fb5c71522f 100644 --- a/docs/docsite/rst/vmware/scenario_remove_vm.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_remove_vm.rst diff --git a/docs/docsite/rst/vmware/scenario_rename_vm.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_rename_vm.rst index 812728979f..812728979f 100644 --- a/docs/docsite/rst/vmware/scenario_rename_vm.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_rename_vm.rst diff --git a/docs/docsite/rst/vmware/scenario_vmware_http.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_vmware_http.rst index ae830fe059..ae830fe059 100644 --- a/docs/docsite/rst/vmware/scenario_vmware_http.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_vmware_http.rst diff --git a/docs/docsite/rst/vmware/vmware_concepts.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_concepts.rst index 48290530ac..ce1e831aa5 100644 --- a/docs/docsite/rst/vmware/vmware_concepts.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_concepts.rst @@ -4,9 +4,10 @@ Ansible for VMware Concepts *************************** -These concepts are common to all uses of Ansible, including VMware automation. You need to understand them to use Ansible for VMware automation. This basic introduction provides the background you need to follow the examples in this guide. +Some of these concepts are common to all uses of Ansible, including VMware automation; some are specific to VMware. You need to understand them to use Ansible for VMware automation. This introduction provides the background you need to follow the :ref:`scenarios<vmware_scenarios>` in this guide. -.. contents:: Topics +.. contents:: + :local: Control Node ============ @@ -16,20 +17,18 @@ Any machine with Ansible installed. You can run commands and playbooks, invoking Delegation ========== -If you want to perform a VMware specific task on one host with reference to ESXi server or vCenter server, use the ``delegate_to`` keyword on a task. This delegation host will be any host where you have ``pyVmomi`` installed. Your control node and ``delegate_to`` host can be same or different. +Delegation allows you to select the system that executes a given task. If you do not have ``pyVmomi`` installed on your control node, use the ``delegate_to`` keyword on VMware-specific tasks to execute them on any host where you have ``pyVmomi`` installed. Modules ======= -The units of code Ansible executes. Each module has a particular use, from creating virtual machines on vCenter to managing distributed virtual switches on vCenter environment. You can invoke a single module with a task, or invoke several different modules in a playbook. For an idea of how many modules Ansible includes, take a look at the :ref:`list of VMware modules<vmware_cloud_modules>`. - +The units of code Ansible executes. Each module has a particular use, from creating virtual machines on vCenter to managing distributed virtual switches in the vCenter environment. You can invoke a single module with a task, or invoke several different modules in a playbook. For an idea of how many modules Ansible includes, take a look at the :ref:`list of cloud modules<cloud_modules>`, which includes VMware modules. Playbooks ========= Ordered lists of tasks, saved so you can run those tasks in that order repeatedly. Playbooks can include variables as well as tasks. Playbooks are written in YAML and are easy to read, write, share and understand. - pyVmomi ======= diff --git a/docs/docsite/rst/vmware/vmware_external_doc_links.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_external_doc_links.rst index 6e3480b789..632343fb70 100644 --- a/docs/docsite/rst/vmware/vmware_external_doc_links.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_external_doc_links.rst @@ -1,10 +1,8 @@ .. _vmware_external_doc_links: -****************************** -List of useful links to VMware -****************************** - -Following is the list of various external documentation and guides which can helpful in further readings. +***************************** +Other useful VMware resources +***************************** * `PyVmomi Documentation <https://github.com/vmware/pyvmomi/tree/master/docs>`_ * `VMware API and SDK Documentation <https://www.vmware.com/support/pubs/sdk_pubs.html>`_ diff --git a/docs/docsite/rst/vmware/vmware_getting_started.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_getting_started.rst index cab29e856e..fc5691b7ab 100644 --- a/docs/docsite/rst/vmware/vmware_getting_started.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_getting_started.rst @@ -1,3 +1,5 @@ +:orphan: + .. _vmware_ansible_getting_started: *************************************** diff --git a/docs/docsite/rst/vmware/vmware_intro.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_intro.rst index 911d63fcdb..911d63fcdb 100644 --- a/docs/docsite/rst/vmware/vmware_intro.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_intro.rst diff --git a/docs/docsite/rst/vmware/vmware_inventory.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory.rst index fbd6136483..fbd6136483 100644 --- a/docs/docsite/rst/vmware/vmware_inventory.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory.rst diff --git a/docs/docsite/rst/vmware/vmware_module_reference.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_module_reference.rst index 24a502fe03..3c7de1dd6e 100644 --- a/docs/docsite/rst/vmware/vmware_module_reference.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_module_reference.rst @@ -1,7 +1,9 @@ +:orphan: + .. _vmware_ansible_module_index: *************************** Ansible VMware Module Guide *************************** -This will be a listing similar to the module index in our core docs.
\ No newline at end of file +This will be a listing similar to the module index in our core docs. diff --git a/docs/docsite/rst/vmware/vmware_requirements.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_requirements.rst index 4671441f0d..367d90a238 100644 --- a/docs/docsite/rst/vmware/vmware_requirements.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_requirements.rst @@ -4,28 +4,22 @@ VMware Prerequisites ******************** -.. contents:: Topics +.. contents:: + :local: +Installing SSL Certificates +=========================== -Installing SSL Certificate -========================== +All vCenter and ESXi servers require SSL encryption on all connections to enforce secure communication. You must enable SSL encryption for Ansible by installing the server's SSL certificates on your Ansible control node or delegate node. -All vCenter and ESXi servers require SSL encryption on all connections to enforce secure communication. +If the SSL certificate of your vCenter or ESXi server is not correctly installed on your Ansible control node, you will see the following warning when using Ansible VMware modules: -If you see the following warning while using Ansible VMware modules [warning], you need to enable SSL encryption for Ansible by installing the server's SSL certificates on your Ansible control node or delegate node. +``Unable to connect to vCenter or ESXi API at xx.xx.xx.xx on TCP/443: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:777)`` -``` -Unable to connect to vCenter or ESXi API at xx.xx.xx.xx on TCP/443: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:777) -``` +To install the SSL certificate for your VMware server, and run your Ansible VMware modules in encrypted mode, please follow the instructions for the server you are running with VMware. -then, this means you need to add/install SSL certificate of vCenter or ESXi server in your Ansible control node. - -The following instructions allow you to run your Ansible VMware modules with encrypted mode (viz. ``validate_certs=True``). - -Please follow the instructions depending upon your server to install SSL certificate. - -vCenter -------- +Installing vCenter SSL certificates for Ansible +----------------------------------------------- * From any web browser, go to the base URL of the vCenter Server without port number like ``https://vcenter-domain.example.com`` @@ -38,9 +32,8 @@ vCenter * Install the certificate files are trusted certificates by the process that is appropriate for your operating system. - -ESXi ----- +Installing ESXi SSL certificates for Ansible +-------------------------------------------- * Enable SSH Service on ESXi either by using Ansible VMware module `vmware_host_service_manager <https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/cloud/vmware/vmware_host_config_manager.py>`_ or manually using vSphere Web interface. diff --git a/docs/docsite/rst/vmware/vmware_scenario_1.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_scenario_1.rst index c841c1d32b..cc743fa80b 100644 --- a/docs/docsite/rst/vmware/vmware_scenario_1.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_scenario_1.rst @@ -1,4 +1,4 @@ -.. _vmware_scenario_1: +:orphan: ********************************** Sample Scenario for Ansible VMware diff --git a/docs/docsite/rst/vmware/vmware_scenarios.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_scenarios.rst index f0c5000498..b044740baf 100644 --- a/docs/docsite/rst/vmware/vmware_scenarios.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_scenarios.rst @@ -4,21 +4,13 @@ Ansible for VMware Scenarios **************************** -Welcome to the Ansible for VMWare Guide! - -The purpose of this guide is to teach you everything you need to know about using Ansible with VMWare. - -To get started, please select one of the following topics. - +These scenarios teach you how to accomplish common VMware tasks using Ansible. To get started, please select the task you want to accomplish. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 scenario_clone_template scenario_rename_vm scenario_remove_vm scenario_find_vm_folder scenario_vmware_http - vmware_scenario_1 - - diff --git a/docs/docsite/rst/vmware/vmware_troubleshooting.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_troubleshooting.rst index bad49f7514..3ca5eac284 100644 --- a/docs/docsite/rst/vmware/vmware_troubleshooting.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_troubleshooting.rst @@ -8,8 +8,8 @@ Troubleshooting Ansible for VMware This section lists things that can go wrong and possible ways to fix them. -Debugging -========= +Debugging Ansible for VMware +============================ When debugging or creating a new issue, you will need information about your VMware infrastructure. You can get this information using `govc <https://github.com/vmware/govmomi/tree/master/govc>`_, For example: @@ -22,8 +22,8 @@ When debugging or creating a new issue, you will need information about your VMw $ export GOVC_URL=https://ESXI_OR_VCENTER_HOSTNAME:443 $ govc find / -Known issues -============ +Known issues with Ansible for VMware +==================================== Network settings with vmware_guest in Ubuntu 18.04 @@ -35,15 +35,15 @@ This issue is tracked via: * https://github.com/vmware/open-vm-tools/issues/240 * https://github.com/ansible/ansible/issues/41133 -Potential Workaround -^^^^^^^^^^^^^^^^^^^^ +Potential Workarounds +^^^^^^^^^^^^^^^^^^^^^ There are several workarounds for this issue. -1) Modifying the Ubuntu 18.04 images and installing ``ifupdown`` in them via ``sudo apt install ifupdown``. +1) Modify the Ubuntu 18.04 images and installing ``ifupdown`` in them via ``sudo apt install ifupdown``. If so you need to remove ``netplan`` via ``sudo apt remove netplan.io`` and you need stop ``systemd-networkd`` via ``sudo systemctl disable systemctl-networkd``. -2) You can generate the ``systemd-networkd`` files with a task in your vmware Ansible role: +2) Generate the ``systemd-networkd`` files with a task in your VMware Ansible role: .. code-block:: yaml @@ -100,14 +100,3 @@ There are several workarounds for this issue. delegate_to: localhost 3) Wait for ``netplan`` support in ``open-vm-tools`` - - -Troubleshooting Item -==================== - -Description - -Potential Workaround --------------------- - -How to fix... diff --git a/docs/docsite/rst/scenario_guides/guide_rolling_upgrade.rst b/docs/docsite/rst/user_guide/guide_rolling_upgrade.rst index 6e7de9eaa1..ee85de9670 100644 --- a/docs/docsite/rst/scenario_guides/guide_rolling_upgrade.rst +++ b/docs/docsite/rst/user_guide/guide_rolling_upgrade.rst @@ -1,12 +1,16 @@ -Continuous Delivery and Rolling Upgrades -======================================== +********************************************************** +Playbook Example: Continuous Delivery and Rolling Upgrades +********************************************************** + +.. contents:: + :local: .. _lamp_introduction: -Introduction -```````````` +What is continuous delivery? +============================ -Continuous Delivery is the concept of frequently delivering updates to your software application. +Continuous delivery (CD) means frequently delivering updates to your software application. The idea is that by updating more often, you do not have to wait for a specific timed period, and your organization gets better at the process of responding to change. @@ -14,31 +18,31 @@ gets better at the process of responding to change. Some Ansible users are deploying updates to their end users on an hourly or even more frequent basis -- sometimes every time there is an approved code change. To achieve this, you need tools to be able to quickly apply those updates in a zero-downtime way. -This document describes in detail how to achieve this goal, using one of Ansible's most complete example -playbooks as a template: lamp_haproxy. This example uses a lot of Ansible features: roles, templates, -and group variables, and it also comes with an orchestration playbook that can do zero-downtime +This document describes in detail how to achieve this goal, using one of Ansible's most complete example +playbooks as a template: lamp_haproxy. This example uses a lot of Ansible features: roles, templates, +and group variables, and it also comes with an orchestration playbook that can do zero-downtime rolling upgrades of the web application stack. .. note:: - `Click here for the latest playbooks for this example + `Click here for the latest playbooks for this example <https://github.com/ansible/ansible-examples/tree/master/lamp_haproxy>`_. The playbooks deploy Apache, PHP, MySQL, Nagios, and HAProxy to a CentOS-based set of servers. -We're not going to cover how to run these playbooks here. Read the included README in the github project along with the +We're not going to cover how to run these playbooks here. Read the included README in the github project along with the example for that information. Instead, we're going to take a close look at every part of the playbook and describe what it does. .. _lamp_deployment: -Site Deployment -``````````````` +Site deployment +=============== -Let's start with ``site.yml``. This is our site-wide deployment playbook. It can be used to initially deploy the site, as well +Let's start with ``site.yml``. This is our site-wide deployment playbook. It can be used to initially deploy the site, as well as push updates to all of the servers:: --- - # This playbook deploys the whole application stack in this site. + # This playbook deploys the whole application stack in this site. # Apply common configuration to all hosts - hosts: all @@ -48,29 +52,29 @@ as push updates to all of the servers:: # Configure and deploy database servers. - hosts: dbservers - + roles: - db # Configure and deploy the web servers. Note that we include two roles # here, the 'base-apache' role which simply sets up Apache, and 'web' # which includes our example web application. - + - hosts: webservers - + roles: - base-apache - web # Configure and deploy the load balancer(s). - hosts: lbservers - + roles: - haproxy # Configure and deploy the Nagios monitoring node(s). - hosts: monitoring - + roles: - base-apache - nagios @@ -79,45 +83,45 @@ as push updates to all of the servers:: If you're not familiar with terms like playbooks and plays, you should review :ref:`working_with_playbooks`. -In this playbook we have 5 plays. The first one targets ``all`` hosts and applies the ``common`` role to all of the hosts. +In this playbook we have 5 plays. The first one targets ``all`` hosts and applies the ``common`` role to all of the hosts. This is for site-wide things like yum repository configuration, firewall configuration, and anything else that needs to apply to all of the servers. -The next four plays run against specific host groups and apply specific roles to those servers. -Along with the roles for Nagios monitoring, the database, and the web application, we've implemented a -``base-apache`` role that installs and configures a basic Apache setup. This is used by both the +The next four plays run against specific host groups and apply specific roles to those servers. +Along with the roles for Nagios monitoring, the database, and the web application, we've implemented a +``base-apache`` role that installs and configures a basic Apache setup. This is used by both the sample web application and the Nagios hosts. .. _lamp_roles: -Reusable Content: Roles -``````````````````````` +Reusable content: roles +======================= -By now you should have a bit of understanding about roles and how they work in Ansible. Roles are a way to organize +By now you should have a bit of understanding about roles and how they work in Ansible. Roles are a way to organize content: tasks, handlers, templates, and files, into reusable components. -This example has six roles: ``common``, ``base-apache``, ``db``, ``haproxy``, ``nagios``, and ``web``. How you organize -your roles is up to you and your application, but most sites will have one or more common roles that are applied to +This example has six roles: ``common``, ``base-apache``, ``db``, ``haproxy``, ``nagios``, and ``web``. How you organize +your roles is up to you and your application, but most sites will have one or more common roles that are applied to all systems, and then a series of application-specific roles that install and configure particular parts of the site. -Roles can have variables and dependencies, and you can pass in parameters to roles to modify their behavior. +Roles can have variables and dependencies, and you can pass in parameters to roles to modify their behavior. You can read more about roles in the :ref:`playbooks_reuse_roles` section. .. _lamp_group_variables: -Configuration: Group Variables -`````````````````````````````` +Configuration: group variables +============================== -Group variables are variables that are applied to groups of servers. They can be used in templates and in -playbooks to customize behavior and to provide easily-changed settings and parameters. They are stored in -a directory called ``group_vars`` in the same location as your inventory. +Group variables are variables that are applied to groups of servers. They can be used in templates and in +playbooks to customize behavior and to provide easily-changed settings and parameters. They are stored in +a directory called ``group_vars`` in the same location as your inventory. Here is lamp_haproxy's ``group_vars/all`` file. As you might expect, these variables are applied to all of the machines in your inventory:: --- httpd_port: 80 ntpserver: 192.0.2.23 -This is a YAML file, and you can create lists and dictionaries for more complex variable structures. -In this case, we are just setting two variables, one for the port for the web server, and one for the +This is a YAML file, and you can create lists and dictionaries for more complex variable structures. +In this case, we are just setting two variables, one for the port for the web server, and one for the NTP server that our machines should use for time synchronization. Here's another group variables file. This is ``group_vars/dbservers`` which applies to the hosts in the ``dbservers`` group:: @@ -159,9 +163,9 @@ You can also use these variables in templates, like this, in ``roles/common/temp keys /etc/ntp/keys -You can see that the variable substitution syntax of {{ and }} is the same for both templates and variables. The syntax -inside the curly braces is Jinja2, and you can do all sorts of operations and apply different filters to the -data inside. In templates, you can also use for loops and if statements to handle more complex situations, +You can see that the variable substitution syntax of {{ and }} is the same for both templates and variables. The syntax +inside the curly braces is Jinja2, and you can do all sorts of operations and apply different filters to the +data inside. In templates, you can also use for loops and if statements to handle more complex situations, like this, in ``roles/common/templates/iptables.j2``: .. code-block:: jinja @@ -170,7 +174,7 @@ like this, in ``roles/common/templates/iptables.j2``: -A INPUT -p tcp --dport 3306 -j ACCEPT {% endif %} -This is testing to see if the inventory name of the machine we're currently operating on (``inventory_hostname``) +This is testing to see if the inventory name of the machine we're currently operating on (``inventory_hostname``) exists in the inventory group ``dbservers``. If so, that machine will get an iptables ACCEPT line for port 3306. Here's another example, from the same template: @@ -181,18 +185,18 @@ Here's another example, from the same template: -A INPUT -p tcp -s {{ hostvars[host].ansible_default_ipv4.address }} --dport 5666 -j ACCEPT {% endfor %} -This loops over all of the hosts in the group called ``monitoring``, and adds an ACCEPT line for +This loops over all of the hosts in the group called ``monitoring``, and adds an ACCEPT line for each monitoring hosts' default IPv4 address to the current machine's iptables configuration, so that Nagios can monitor those hosts. -You can learn a lot more about Jinja2 and its capabilities `here <http://jinja.pocoo.org/docs/>`_, and you +You can learn a lot more about Jinja2 and its capabilities `here <http://jinja.pocoo.org/docs/>`_, and you can read more about Ansible variables in general in the :ref:`playbooks_variables` section. .. _lamp_rolling_upgrade: -The Rolling Upgrade -``````````````````` +The rolling upgrade +=================== -Now you have a fully-deployed site with web servers, a load balancer, and monitoring. How do you update it? This is where Ansible's +Now you have a fully-deployed site with web servers, a load balancer, and monitoring. How do you update it? This is where Ansible's orchestration features come into play. While some applications use the term 'orchestration' to mean basic ordering or command-blasting, Ansible refers to orchestration as 'conducting machines like an orchestra', and has a pretty sophisticated engine for it. @@ -217,8 +221,8 @@ Here is the next part of the update play:: pre_tasks: - name: disable nagios alerts for this host webserver service - nagios: - action: disable_alerts + nagios: + action: disable_alerts host: "{{ inventory_hostname }}" services: webserver delegate_to: "{{ item }}" @@ -266,8 +270,8 @@ Again, if you were using a Netscaler or F5 or Elastic Load Balancer, you would j .. _lamp_end_notes: -Managing Other Load Balancers -````````````````````````````` +Managing other load balancers +============================= In this example, we use the simple HAProxy load balancer to front-end the web servers. It's easy to configure and easy to manage. As we have mentioned, Ansible has built-in support for a variety of other load balancers like Citrix NetScaler, F5 BigIP, Amazon Elastic Load Balancers, and more. See the :ref:`working_with_modules` documentation for more information. @@ -275,8 +279,8 @@ For other load balancers, you may need to send shell commands to them (like we d .. _lamp_end_to_end: -Continuous Delivery End-To-End -`````````````````````````````` +Continuous delivery end-to-end +============================== Now that you have an automated way to deploy updates to your application, how do you tie it all together? A lot of organizations use a continuous integration tool like `Jenkins <https://jenkins.io/>`_ or `Atlassian Bamboo <https://www.atlassian.com/software/bamboo>`_ to tie the development, test, release, and deploy steps together. You may also want to use a tool like `Gerrit <https://www.gerritcodereview.com/>`_ to add a code review step to commits to either the application code itself, or to your Ansible playbooks, or both. @@ -298,5 +302,3 @@ This should give you a good idea of how to structure a multi-tier application wi An introduction to Ansible variables `Ansible.com: Continuous Delivery <https://www.ansible.com/use-cases/continuous-delivery>`_ An introduction to Continuous Delivery with Ansible - - diff --git a/docs/docsite/rst/user_guide/playbooks.rst b/docs/docsite/rst/user_guide/playbooks.rst index e12a65df96..5216322459 100644 --- a/docs/docsite/rst/user_guide/playbooks.rst +++ b/docs/docsite/rst/user_guide/playbooks.rst @@ -7,10 +7,10 @@ Playbooks are Ansible's configuration, deployment, and orchestration language. T If Ansible modules are the tools in your workshop, playbooks are your instruction manuals, and your inventory of hosts are your raw material. -At a basic level, playbooks can be used to manage configurations of and deployments to remote machines. At a more advanced level, they can sequence multi-tier rollouts involving rolling updates, and can delegate actions to other hosts, interacting with monitoring servers and load balancers along the way. +At a basic level, playbooks can be used to manage configurations of and deployments to remote machines. At a more advanced level, they can sequence multi-tier rollouts involving rolling updates, and can delegate actions to other hosts, interacting with monitoring servers and load balancers along the way. While there's a lot of information here, there's no need to learn everything at once. You can start small and pick up more features -over time as you need them. +over time as you need them. Playbooks are designed to be human-readable and are developed in a basic text language. There are multiple ways to organize playbooks and the files they include, and we'll offer up some suggestions on that and making the most out of Ansible. @@ -30,5 +30,4 @@ You should look at `Example Playbooks <https://github.com/ansible/ansible-exampl playbooks_special_topics playbooks_strategies playbooks_best_practices - - + guide_rolling_upgrade diff --git a/docs/docsite/rst/vmware/index.rst b/docs/docsite/rst/vmware/index.rst deleted file mode 100644 index 8275f8197e..0000000000 --- a/docs/docsite/rst/vmware/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _vmware_ansible: - -****************** -Ansible for VMware -****************** - -Welcome to the Ansible for VMware Guide! This is a set of placeholder docs to be filled in. - -The purpose of this guide is to teach you everything you need to know about using Ansible with VMware. - -To get started, please select one of the following topics. - - -.. toctree:: - :maxdepth: 2 - - vmware_intro - vmware_concepts - vmware_requirements - vmware_getting_started - vmware_inventory - vmware_scenarios - vmware_module_reference - vmware_troubleshooting - vmware_external_doc_links - faq |