diff options
Diffstat (limited to 'docs/docsite/rst/getting_started')
12 files changed, 417 insertions, 0 deletions
diff --git a/docs/docsite/rst/getting_started/ansible_output/first_playbook_output.txt b/docs/docsite/rst/getting_started/ansible_output/first_playbook_output.txt new file mode 100644 index 0000000..e5e1dcb --- /dev/null +++ b/docs/docsite/rst/getting_started/ansible_output/first_playbook_output.txt @@ -0,0 +1,27 @@ +PLAY [My first play] ********************************************************************** + +TASK [Gathering Facts] ******************************************************************** +ok: [vm01] +ok: [vm02] +ok: [vm03] + +TASK [Ping my hosts] ********************************************************************** +ok: [vm01] +ok: [vm02] +ok: [vm03] + +TASK [Print message] ********************************************************************** +ok: [vm01] => { + "msg": "Hello world" +} +ok: [vm02] => { + "msg": "Hello world" +} +ok: [vm03] => { + "msg": "Hello world" +} + +PLAY RECAP ******************************************************************************** +vm01: ok=3 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 +vm02: ok=3 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 +vm03: ok=3 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 diff --git a/docs/docsite/rst/getting_started/ansible_output/ping_inventory_output.txt b/docs/docsite/rst/getting_started/ansible_output/ping_inventory_output.txt new file mode 100644 index 0000000..cd7c4dd --- /dev/null +++ b/docs/docsite/rst/getting_started/ansible_output/ping_inventory_output.txt @@ -0,0 +1,21 @@ +vm03 | SUCCESS => { + "ansible_facts": { + "discovered_interpreter_python": "/usr/bin/python3" + }, + "changed": false, + "ping": "pong" +} +vm02 | SUCCESS => { + "ansible_facts": { + "discovered_interpreter_python": "/usr/bin/python3" + }, + "changed": false, + "ping": "pong" +} +vm01 | SUCCESS => { + "ansible_facts": { + "discovered_interpreter_python": "/usr/bin/python3" + }, + "changed": false, + "ping": "pong" +}
\ No newline at end of file diff --git a/docs/docsite/rst/getting_started/ansible_output/ping_output.txt b/docs/docsite/rst/getting_started/ansible_output/ping_output.txt new file mode 100644 index 0000000..9fe8886 --- /dev/null +++ b/docs/docsite/rst/getting_started/ansible_output/ping_output.txt @@ -0,0 +1,21 @@ +192.0.2.50 | SUCCESS => { + "ansible_facts": { + "discovered_interpreter_python": "/usr/bin/python3" + }, + "changed": false, + "ping": "pong" + } +192.0.2.51 | SUCCESS => { + "ansible_facts": { + "discovered_interpreter_python": "/usr/bin/python3" + }, + "changed": false, + "ping": "pong" + } +192.0.2.52 | SUCCESS => { + "ansible_facts": { + "discovered_interpreter_python": "/usr/bin/python3" + }, + "changed": false, + "ping": "pong" + }
\ No newline at end of file diff --git a/docs/docsite/rst/getting_started/basic_concepts.rst b/docs/docsite/rst/getting_started/basic_concepts.rst new file mode 100644 index 0000000..cc433c8 --- /dev/null +++ b/docs/docsite/rst/getting_started/basic_concepts.rst @@ -0,0 +1,13 @@ +.. _basic_concepts: + +**************** +Ansible concepts +**************** + +These concepts are common to all uses of Ansible. +You should understand them before using Ansible or reading the documentation. + +.. contents:: + :local: + +.. include:: /shared_snippets/basic_concepts.txt diff --git a/docs/docsite/rst/getting_started/get_started_inventory.rst b/docs/docsite/rst/getting_started/get_started_inventory.rst new file mode 100644 index 0000000..8df7330 --- /dev/null +++ b/docs/docsite/rst/getting_started/get_started_inventory.rst @@ -0,0 +1,102 @@ +.. _get_started_inventory: + +********************* +Building an inventory +********************* + +Inventories organize managed nodes in centralized files that provide Ansible with system information and network locations. +Using an inventory file, Ansible can manage a large number of hosts with a single command. +Inventories also help you use Ansible more efficiently by reducing the number of command-line options you need to specify. +For example, inventories usually contain the SSH user so you do not need to include the ``-u`` flag when running Ansible commands. + +In the previous section, you added managed nodes directly to the ``/etc/ansible/hosts`` file. +Now let's create an inventory file that you can add to source control for flexibility, reuse, and for sharing with other users. + +.. note:: + Inventory files can be in ``INI`` or ``YAML`` format. + For demonstration purposes, this section uses ``YAML`` format only. + +Complete the following steps: + +#. Open a terminal window on your control node. +#. Create a new inventory file named ``inventory.yaml`` in any directory and open it for editing. +#. Add a new group for your hosts then specify the IP address or fully qualified domain name (FQDN) of each managed node with the ``ansible_host`` field. + The following example adds the IP addresses of three virtual machines in KVM: + + .. literalinclude:: yaml/inventory_example_vms.yaml + :language: yaml + +#. Verify your inventory. + If you created your inventory in a directory other than your home directory, specify the full path with the ``-i`` option. + + .. code-block:: bash + + ansible-inventory -i inventory.yaml --list + +#. Ping the managed nodes in your inventory. + In this example, the group name is ``virtualmachines`` which you can specify with the ``ansible`` command instead of ``all``. + + .. code-block:: bash + + ansible virtualmachines -m ping -i inventory.yaml + + .. literalinclude:: ansible_output/ping_inventory_output.txt + :language: text + +Congratulations! You have successfully built an inventory. + +Tips for building inventories +============================= + +* Ensure that group names are meaningful and unique. Group names are also case sensitive. +* Avoid spaces, hyphens, and preceding numbers (use ``floor_19``, not ``19th_floor``) in group names. +* Group hosts in your inventory logically according to their **What**, **Where**, and **When**. + + What + Group hosts according to the topology, for example: db, web, leaf, spine. + Where + Group hosts by geographic location, for example: datacenter, region, floor, building. + When + Group hosts by stage, for example: development, test, staging, production. + +Use metagroups +-------------- + +Create a metagroup that organizes multiple groups in your inventory with the following syntax: + +.. code-block:: yaml + + metagroupname: + children: + +The following inventory illustrates a basic structure for a data center. +This example inventory contains a ``network`` metagroup that includes all network devices and a ``datacenter`` metagroup that includes the ``network`` group and all webservers. + +.. literalinclude:: yaml/inventory_group_structure.yaml + :language: yaml + +Create variables +---------------- + +Variables set values for managed nodes, such as the IP address, FQDN, operating system, and SSH user, so you do not need to pass them when running Ansible commands. + +Variables can apply to specific hosts. + +.. literalinclude:: yaml/inventory_variables_host.yaml + :language: yaml + +Variables can also apply to all hosts in a group. + +.. literalinclude:: yaml/inventory_variables_group.yaml + :language: yaml + +Now that you know how to build an inventory, continue by :ref:`learning how to create a playbook<get_started_playbook>`. + +.. seealso:: + + :ref:`intro_inventory` + Learn more about inventories in ``YAML`` or ``INI`` format. + :ref:`variables_in_inventory` + Find out more about inventory variables and their syntax. + :ref:`vault` + Find out how to encrypt sensitive content in your inventory such as passwords and keys. diff --git a/docs/docsite/rst/getting_started/get_started_playbook.rst b/docs/docsite/rst/getting_started/get_started_playbook.rst new file mode 100644 index 0000000..7ee1be6 --- /dev/null +++ b/docs/docsite/rst/getting_started/get_started_playbook.rst @@ -0,0 +1,70 @@ +.. _get_started_playbook: + +******************* +Creating a playbook +******************* + +Playbooks are automation blueprints, in ``YAML`` format, that Ansible uses to deploy and configure managed nodes. + +Playbook + A list of plays that define the order in which Ansible performs operations, from top to bottom, to achieve an overall goal. + +Play + An ordered list of tasks that maps to managed nodes in an inventory. + +Task + A list of one or more modules that defines the operations that Ansible performs. + +Module + A unit of code or binary that Ansible runs on managed nodes. + Ansible modules are grouped in collections with a :term:`Fully Qualified Collection Name (FQCN)` for each module. + +In the previous section, you used the ``ansible`` command to ping hosts in your inventory. +Now let's create a playbook that pings your hosts and also prints a "Hello world" message. + +Complete the following steps: + +#. Open a terminal window on your control node. +#. Create a new playbook file named ``playbook.yaml`` in any directory and open it for editing. +#. Add the following content to ``playbook.yaml``: + + .. literalinclude:: yaml/first_playbook.yaml + :language: yaml + +#. Run your playbook. + + .. code-block:: bash + + ansible-playbook -i inventory.yaml playbook.yaml + +Ansible returns the following output: + +.. literalinclude:: ansible_output/first_playbook_output.txt + :language: text + +In this output you can see: + +* The names that you give the play and each task. + You should always use descriptive names that make it easy to verify and troubleshoot playbooks. + +* The ``Gather Facts`` task runs implicitly. + By default Ansible gathers information about your inventory that it can use in the playbook. + +* The status of each task. + Each task has a status of ``ok`` which means it ran successfully. + +* The play recap that summarizes results of all tasks in the playbook per host. + In this example, there are three tasks so ``ok=3`` indicates that each task ran successfully. + +Congratulations! You have just created your first Ansible playbook. + +.. seealso:: + + :ref:`playbooks_intro` + Start building playbooks for real world scenarios. + :ref:`working_with_playbooks` + Go into more detail with Ansible playbooks. + :ref:`playbooks_best_practices` + Get tips and tricks for using playbooks. + :ref:`vars_and_facts` + Learn more about the ``gather_facts`` keyword in playbooks.
\ No newline at end of file diff --git a/docs/docsite/rst/getting_started/index.rst b/docs/docsite/rst/getting_started/index.rst new file mode 100644 index 0000000..818c7fb --- /dev/null +++ b/docs/docsite/rst/getting_started/index.rst @@ -0,0 +1,99 @@ +.. _getting_started_index: + +############################ +Getting started with Ansible +############################ + +Ansible automates the management of remote systems and controls their desired state. +A basic Ansible environment has three main components: + + +Control node + A system on which Ansible is installed. + You run Ansible commands such as ``ansible`` or ``ansible-inventory`` on a control node. + +Managed node + A remote system, or host, that Ansible controls. + +Inventory + A list of managed nodes that are logically organized. + You create an inventory on the control node to describe host deployments to Ansible. + +.. image:: ../images/ansible_basic.svg + :width: 400px + :align: center + :height: 200px + :alt: Basic components of an Ansible environment include a control node, an inventory of managed nodes, and a module copied to each managed node. + +Ready to start using Ansible? +Complete the following steps to get up and running: + +#. Install Ansible. Visit the :ref:`installation guide<installation_guide>` for complete details. + + .. code-block:: bash + + python3 -m pip install --user ansible + +#. Create an inventory by adding the IP address or fully qualified domain name (FQDN) of one or more remote systems to ``/etc/ansible/hosts``. + The following example adds the IP addresses of three virtual machines in KVM: + + .. code-block:: ini + + [myvirtualmachines] + 192.0.2.50 + 192.0.2.51 + 192.0.2.52 + +#. Verify the hosts in your inventory. + + .. code-block:: bash + + ansible all --list-hosts + + .. code-block:: ansible-output + + hosts (1): + 192.0.2.50 + 192.0.2.51 + 192.0.2.52 + +#. Set up SSH connections so Ansible can connect to the managed nodes. + + a. Add your public SSH key to the ``authorized_keys`` file on each remote system. + b. Test the SSH connections, for example: + + .. code-block:: bash + + ssh username@192.0.2.50 + + If the username on the control node is different on the host, you need to pass the ``-u`` option with the ``ansible`` command. + +#. Ping the managed nodes. + + .. code-block:: bash + + ansible all -m ping + + .. literalinclude:: ansible_output/ping_output.txt + :language: text + +Congratulations! You are now using Ansible. +Continue by :ref:`learning how to build an inventory<get_started_inventory>`. + +.. seealso:: + + `Ansible Demos <https://github.com/ansible/product-demos>`_ + Demonstrations of different Ansible usecases + `Ansible Labs <https://www.ansible.com/products/ansible-training>`_ + Labs to provide further knowledge on different topics + `Mailing List <https://groups.google.com/group/ansible-project>`_ + Questions? Help? Ideas? Stop by the list on Google Groups + :ref:`communication_irc` + How to join Ansible chat channels + +.. toctree:: + :maxdepth: 1 + + get_started_inventory + get_started_playbook + basic_concepts
\ No newline at end of file diff --git a/docs/docsite/rst/getting_started/yaml/first_playbook.yaml b/docs/docsite/rst/getting_started/yaml/first_playbook.yaml new file mode 100644 index 0000000..dd0ef63 --- /dev/null +++ b/docs/docsite/rst/getting_started/yaml/first_playbook.yaml @@ -0,0 +1,8 @@ +- name: My first play + hosts: virtualmachines + tasks: + - name: Ping my hosts + ansible.builtin.ping: + - name: Print message + ansible.builtin.debug: + msg: Hello world diff --git a/docs/docsite/rst/getting_started/yaml/inventory_example_vms.yaml b/docs/docsite/rst/getting_started/yaml/inventory_example_vms.yaml new file mode 100644 index 0000000..d5edbca --- /dev/null +++ b/docs/docsite/rst/getting_started/yaml/inventory_example_vms.yaml @@ -0,0 +1,8 @@ +virtualmachines: + hosts: + vm01: + ansible_host: 192.0.2.50 + vm02: + ansible_host: 192.0.2.51 + vm03: + ansible_host: 192.0.2.52
\ No newline at end of file diff --git a/docs/docsite/rst/getting_started/yaml/inventory_group_structure.yaml b/docs/docsite/rst/getting_started/yaml/inventory_group_structure.yaml new file mode 100644 index 0000000..93dd6a9 --- /dev/null +++ b/docs/docsite/rst/getting_started/yaml/inventory_group_structure.yaml @@ -0,0 +1,30 @@ +leafs: + hosts: + leaf01: + ansible_host: 192.0.2.100 + leaf02: + ansible_host: 192.0.2.110 + +spines: + hosts: + spine01: + ansible_host: 192.0.2.120 + spine02: + ansible_host: 192.0.2.130 + +network: + children: + leafs: + spines: + +webservers: + hosts: + webserver01: + ansible_host: 192.0.2.140 + webserver02: + ansible_host: 192.0.2.150 + +datacenter: + children: + network: + webservers:
\ No newline at end of file diff --git a/docs/docsite/rst/getting_started/yaml/inventory_variables_group.yaml b/docs/docsite/rst/getting_started/yaml/inventory_variables_group.yaml new file mode 100644 index 0000000..6f934aa --- /dev/null +++ b/docs/docsite/rst/getting_started/yaml/inventory_variables_group.yaml @@ -0,0 +1,10 @@ +webservers: + hosts: + webserver01: + ansible_host: 192.0.2.140 + http_port: 80 + webserver02: + ansible_host: 192.0.2.150 + http_port: 443 + vars: + ansible_user: my_server_user
\ No newline at end of file diff --git a/docs/docsite/rst/getting_started/yaml/inventory_variables_host.yaml b/docs/docsite/rst/getting_started/yaml/inventory_variables_host.yaml new file mode 100644 index 0000000..98ab165 --- /dev/null +++ b/docs/docsite/rst/getting_started/yaml/inventory_variables_host.yaml @@ -0,0 +1,8 @@ +webservers: + hosts: + webserver01: + ansible_host: 192.0.2.140 + http_port: 80 + webserver02: + ansible_host: 192.0.2.150 + http_port: 443
\ No newline at end of file |