diff options
Diffstat (limited to 'docs/docsite/rst/network/getting_started')
11 files changed, 1200 insertions, 0 deletions
diff --git a/docs/docsite/rst/network/getting_started/basic_concepts.rst b/docs/docsite/rst/network/getting_started/basic_concepts.rst new file mode 100644 index 0000000..980b144 --- /dev/null +++ b/docs/docsite/rst/network/getting_started/basic_concepts.rst @@ -0,0 +1,10 @@ +************** +Basic Concepts +************** + +These concepts are common to all uses of Ansible, including network automation. You need to understand them to use Ansible for network automation. This basic introduction provides the background you need to follow the examples in this guide. + +.. contents:: + :local: + +.. include:: ../../shared_snippets/basic_concepts.txt diff --git a/docs/docsite/rst/network/getting_started/first_inventory.rst b/docs/docsite/rst/network/getting_started/first_inventory.rst new file mode 100644 index 0000000..1562ed4 --- /dev/null +++ b/docs/docsite/rst/network/getting_started/first_inventory.rst @@ -0,0 +1,431 @@ +*********************************************** +Build Your Inventory +*********************************************** + +Running a playbook without an inventory requires several command-line flags. Also, running a playbook against a single device is not a huge efficiency gain over making the same change manually. The next step to harnessing the full power of Ansible is to use an inventory file to organize your managed nodes into groups with information like the ``ansible_network_os`` and the SSH user. A fully-featured inventory file can serve as the source of truth for your network. Using an inventory file, a single playbook can maintain hundreds of network devices with a single command. This page shows you how to build an inventory file, step by step. + +.. contents:: + :local: + +Basic inventory +================================================== + +First, group your inventory logically. Best practice is to group servers and network devices by their What (application, stack or microservice), Where (datacenter or region), and When (development stage): + +- **What**: db, web, leaf, spine +- **Where**: east, west, floor_19, building_A +- **When**: dev, test, staging, prod + +Avoid spaces, hyphens, and preceding numbers (use ``floor_19``, not ``19th_floor``) in your group names. Group names are case sensitive. + +This tiny example data center illustrates a basic group structure. You can group groups using the syntax ``[metagroupname:children]`` and listing groups as members of the metagroup. Here, the group ``network`` includes all leafs and all spines; the group ``datacenter`` includes all network devices plus all webservers. + +.. code-block:: yaml + + --- + + leafs: + hosts: + leaf01: + ansible_host: 10.16.10.11 + leaf02: + ansible_host: 10.16.10.12 + + spines: + hosts: + spine01: + ansible_host: 10.16.10.13 + spine02: + ansible_host: 10.16.10.14 + + network: + children: + leafs: + spines: + + webservers: + hosts: + webserver01: + ansible_host: 10.16.10.15 + webserver02: + ansible_host: 10.16.10.16 + + datacenter: + children: + network: + webservers: + + + +You can also create this same inventory in INI format. + +.. code-block:: ini + + [leafs] + leaf01 + leaf02 + + [spines] + spine01 + spine02 + + [network:children] + leafs + spines + + [webservers] + webserver01 + webserver02 + + [datacenter:children] + network + webservers + + +Add variables to the inventory +================================================================================ + +Next, you can set values for many of the variables you needed in your first Ansible command in the inventory, so you can skip them in the ``ansible-playbook`` command. In this example, the inventory includes each network device's IP, OS, and SSH user. If your network devices are only accessible by IP, you must add the IP to the inventory file. If you access your network devices using hostnames, the IP is not necessary. + +.. code-block:: yaml + + --- + + leafs: + hosts: + leaf01: + ansible_host: 10.16.10.11 + ansible_network_os: vyos.vyos.vyos + ansible_user: my_vyos_user + leaf02: + ansible_host: 10.16.10.12 + ansible_network_os: vyos.vyos.vyos + ansible_user: my_vyos_user + + spines: + hosts: + spine01: + ansible_host: 10.16.10.13 + ansible_network_os: vyos.vyos.vyos + ansible_user: my_vyos_user + spine02: + ansible_host: 10.16.10.14 + ansible_network_os: vyos.vyos.vyos + ansible_user: my_vyos_user + + network: + children: + leafs: + spines: + + webservers: + hosts: + webserver01: + ansible_host: 10.16.10.15 + ansible_user: my_server_user + webserver02: + ansible_host: 10.16.10.16 + ansible_user: my_server_user + + datacenter: + children: + network: + webservers: + + +Group variables within inventory +================================================================================ + +When devices in a group share the same variable values, such as OS or SSH user, you can reduce duplication and simplify maintenance by consolidating these into group variables: + +.. code-block:: yaml + + --- + + leafs: + hosts: + leaf01: + ansible_host: 10.16.10.11 + leaf02: + ansible_host: 10.16.10.12 + vars: + ansible_network_os: vyos.vyos.vyos + ansible_user: my_vyos_user + + spines: + hosts: + spine01: + ansible_host: 10.16.10.13 + spine02: + ansible_host: 10.16.10.14 + vars: + ansible_network_os: vyos.vyos.vyos + ansible_user: my_vyos_user + + network: + children: + leafs: + spines: + + webservers: + hosts: + webserver01: + ansible_host: 10.16.10.15 + webserver02: + ansible_host: 10.16.10.16 + vars: + ansible_user: my_server_user + + datacenter: + children: + network: + webservers: + +Variable syntax +================================================================================ + +The syntax for variable values is different in inventory, in playbooks, and in the ``group_vars`` files, which are covered below. Even though playbook and ``group_vars`` files are both written in YAML, you use variables differently in each. + +- In an ini-style inventory file you **must** use the syntax ``key=value`` for variable values: ``ansible_network_os=vyos.vyos.vyos``. +- In any file with the ``.yml`` or ``.yaml`` extension, including playbooks and ``group_vars`` files, you **must** use YAML syntax: ``key: value``. + +- In ``group_vars`` files, use the full ``key`` name: ``ansible_network_os: vyos.vyos.vyos``. +- In playbooks, use the short-form ``key`` name, which drops the ``ansible`` prefix: ``network_os: vyos.vyos.vyos``. + + +Group inventory by platform +================================================================================ + +As your inventory grows, you may want to group devices by platform. This allows you to specify platform-specific variables easily for all devices on that platform: + +.. code-block:: yaml + + --- + + leafs: + hosts: + leaf01: + ansible_host: 10.16.10.11 + leaf02: + ansible_host: 10.16.10.12 + + spines: + hosts: + spine01: + ansible_host: 10.16.10.13 + spine02: + ansible_host: 10.16.10.14 + + network: + children: + leafs: + spines: + vars: + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: vyos.vyos.vyos + ansible_user: my_vyos_user + + webservers: + hosts: + webserver01: + ansible_host: 10.16.10.15 + webserver02: + ansible_host: 10.16.10.16 + vars: + ansible_user: my_server_user + + datacenter: + children: + network: + webservers: + +With this setup, you can run ``first_playbook.yml`` with only two flags: + +.. code-block:: console + + ansible-playbook -i inventory.yml -k first_playbook.yml + +With the ``-k`` flag, you provide the SSH password(s) at the prompt. Alternatively, you can store SSH and other secrets and passwords securely in your group_vars files with ``ansible-vault``. See :ref:`network_vault` for details. + +Verifying the inventory +========================= + +You can use the :ref:`ansible-inventory` CLI command to display the inventory as Ansible sees it. + +.. code-block:: console + + $ ansible-inventory -i test.yml --list + { + "_meta": { + "hostvars": { + "leaf01": { + "ansible_connection": "ansible.netcommon.network_cli", + "ansible_host": "10.16.10.11", + "ansible_network_os": "vyos.vyos.vyos", + "ansible_user": "my_vyos_user" + }, + "leaf02": { + "ansible_connection": "ansible.netcommon.network_cli", + "ansible_host": "10.16.10.12", + "ansible_network_os": "vyos.vyos.vyos", + "ansible_user": "my_vyos_user" + }, + "spine01": { + "ansible_connection": "ansible.netcommon.network_cli", + "ansible_host": "10.16.10.13", + "ansible_network_os": "vyos.vyos.vyos", + "ansible_user": "my_vyos_user" + }, + "spine02": { + "ansible_connection": "ansible.netcommon.network_cli", + "ansible_host": "10.16.10.14", + "ansible_network_os": "vyos.vyos.vyos", + "ansible_user": "my_vyos_user" + }, + "webserver01": { + "ansible_host": "10.16.10.15", + "ansible_user": "my_server_user" + }, + "webserver02": { + "ansible_host": "10.16.10.16", + "ansible_user": "my_server_user" + } + } + }, + "all": { + "children": [ + "datacenter", + "ungrouped" + ] + }, + "datacenter": { + "children": [ + "network", + "webservers" + ] + }, + "leafs": { + "hosts": [ + "leaf01", + "leaf02" + ] + }, + "network": { + "children": [ + "leafs", + "spines" + ] + }, + "spines": { + "hosts": [ + "spine01", + "spine02" + ] + }, + "webservers": { + "hosts": [ + "webserver01", + "webserver02" + ] + } + } + +.. _network_vault: + +Protecting sensitive variables with ``ansible-vault`` +================================================================================ + +The ``ansible-vault`` command provides encryption for files and/or individual variables like passwords. This tutorial will show you how to encrypt a single SSH password. You can use the commands below to encrypt other sensitive information, such as database passwords, privilege-escalation passwords and more. + +First you must create a password for ansible-vault itself. It is used as the encryption key, and with this you can encrypt dozens of different passwords across your Ansible project. You can access all those secrets (encrypted values) with a single password (the ansible-vault password) when you run your playbooks. Here's a simple example. + +1. Create a file and write your password for ansible-vault to it: + +.. code-block:: console + + echo "my-ansible-vault-pw" > ~/my-ansible-vault-pw-file + +2. Create the encrypted ssh password for your VyOS network devices, pulling your ansible-vault password from the file you just created: + +.. code-block:: console + + ansible-vault encrypt_string --vault-id my_user@~/my-ansible-vault-pw-file 'VyOS_SSH_password' --name 'ansible_password' + +If you prefer to type your ansible-vault password rather than store it in a file, you can request a prompt: + +.. code-block:: console + + ansible-vault encrypt_string --vault-id my_user@prompt 'VyOS_SSH_password' --name 'ansible_password' + +and type in the vault password for ``my_user``. + +The :option:`--vault-id <ansible-playbook --vault-id>` flag allows different vault passwords for different users or different levels of access. The output includes the user name ``my_user`` from your ``ansible-vault`` command and uses the YAML syntax ``key: value``: + +.. code-block:: yaml + + ansible_password: !vault | + $ANSIBLE_VAULT;1.2;AES256;my_user + 66386134653765386232383236303063623663343437643766386435663632343266393064373933 + 3661666132363339303639353538316662616638356631650a316338316663666439383138353032 + 63393934343937373637306162366265383461316334383132626462656463363630613832313562 + 3837646266663835640a313164343535316666653031353763613037656362613535633538386539 + 65656439626166666363323435613131643066353762333232326232323565376635 + Encryption successful + +This is an example using an extract from a YAML inventory, as the INI format does not support inline vaults: + +.. code-block:: yaml + + ... + + vyos: # this is a group in yaml inventory, but you can also do under a host + vars: + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: vyos.vyos.vyos + ansible_user: my_vyos_user + ansible_password: !vault | + $ANSIBLE_VAULT;1.2;AES256;my_user + 66386134653765386232383236303063623663343437643766386435663632343266393064373933 + 3661666132363339303639353538316662616638356631650a316338316663666439383138353032 + 63393934343937373637306162366265383461316334383132626462656463363630613832313562 + 3837646266663835640a313164343535316666653031353763613037656362613535633538386539 + 65656439626166666363323435613131643066353762333232326232323565376635 + + ... + +To use an inline vaulted variables with an INI inventory you need to store it in a 'vars' file in YAML format, +it can reside in host_vars/ or group_vars/ to be automatically picked up or referenced from a play through ``vars_files`` or ``include_vars``. + +To run a playbook with this setup, drop the ``-k`` flag and add a flag for your ``vault-id``: + +.. code-block:: console + + ansible-playbook -i inventory --vault-id my_user@~/my-ansible-vault-pw-file first_playbook.yml + +Or with a prompt instead of the vault password file: + +.. code-block:: console + + ansible-playbook -i inventory --vault-id my_user@prompt first_playbook.yml + +To see the original value, you can use the debug module. Please note if your YAML file defines the `ansible_connection` variable (as we used in our example), it will take effect when you execute the command below. To prevent this, please make a copy of the file without the ansible_connection variable. + +.. code-block:: console + + cat vyos.yml | grep -v ansible_connection >> vyos_no_connection.yml + + ansible localhost -m debug -a var="ansible_password" -e "@vyos_no_connection.yml" --ask-vault-pass + Vault password: + + localhost | SUCCESS => { + "ansible_password": "VyOS_SSH_password" + } + + +.. warning:: + + Vault content can only be decrypted with the password that was used to encrypt it. If you want to stop using one password and move to a new one, you can update and re-encrypt existing vault content with ``ansible-vault rekey myfile``, then provide the old password and the new password. Copies of vault content still encrypted with the old password can still be decrypted with old password. + +For more details on building inventory files, see :ref:`the introduction to inventory<intro_inventory>`; for more details on ansible-vault, see :ref:`the full Ansible Vault documentation<vault>`. + +Now that you understand the basics of commands, playbooks, and inventory, it's time to explore some more complex Ansible Network examples. diff --git a/docs/docsite/rst/network/getting_started/first_playbook.rst b/docs/docsite/rst/network/getting_started/first_playbook.rst new file mode 100644 index 0000000..15a4ed1 --- /dev/null +++ b/docs/docsite/rst/network/getting_started/first_playbook.rst @@ -0,0 +1,212 @@ + +.. _first_network_playbook: + +*************************************************** +Run Your First Command and Playbook +*************************************************** + +Put the concepts you learned to work with this quick tutorial. Install Ansible, execute a network configuration command manually, execute the same command with Ansible, then create a playbook so you can execute the command any time on multiple network devices. + +.. contents:: + :local: + +Prerequisites +================================================== + +Before you work through this tutorial you need: + +- Ansible 2.10 (or higher) installed +- One or more network devices that are compatible with Ansible +- Basic Linux command line knowledge +- Basic knowledge of network switch & router configuration + +Install Ansible +================================================== + +Install Ansible using your preferred method. See :ref:`installation_guide`. Then return to this tutorial. + +Confirm the version of Ansible (must be >= 2.10): + +.. code-block:: bash + + ansible --version + + +Establish a manual connection to a managed node +================================================== + +To confirm your credentials, connect to a network device manually and retrieve its configuration. Replace the sample user and device name with your real credentials. For example, for a VyOS router: + +.. code-block:: bash + + ssh my_vyos_user@vyos.example.net + show config + exit + +This manual connection also establishes the authenticity of the network device, adding its RSA key fingerprint to your list of known hosts. (If you have connected to the device before, you have already established its authenticity.) + + +Run your first network Ansible command +================================================== + +Instead of manually connecting and running a command on the network device, you can retrieve its configuration with a single, stripped-down Ansible command: + +.. code-block:: bash + + ansible all -i vyos.example.net, -c ansible.netcommon.network_cli -u my_vyos_user -k -m vyos.vyos.vyos_facts -e ansible_network_os=vyos.vyos.vyos + +The flags in this command set seven values: + - the host group(s) to which the command should apply (in this case, all) + - the inventory (-i, the device or devices to target - without the trailing comma -i points to an inventory file) + - the connection method (-c, the method for connecting and executing ansible) + - the user (-u, the username for the SSH connection) + - the SSH connection method (-k, please prompt for the password) + - the module (-m, the Ansible module to run, using the fully qualified collection name (FQCN)) + - an extra variable ( -e, in this case, setting the network OS value) + +NOTE: If you use ``ssh-agent`` with ssh keys, Ansible loads them automatically. You can omit ``-k`` flag. + +.. note:: + + If you are running Ansible in a virtual environment, you will also need to add the variable ``ansible_python_interpreter=/path/to/venv/bin/python`` + + +Create and run your first network Ansible Playbook +================================================== + +If you want to run this command every day, you can save it in a playbook and run it with ``ansible-playbook`` instead of ``ansible``. The playbook can store a lot of the parameters you provided with flags at the command line, leaving less to type at the command line. You need two files for this - a playbook and an inventory file. + +1. Download :download:`first_playbook.yml <sample_files/first_playbook.yml>`, which looks like this: + +.. literalinclude:: sample_files/first_playbook.yml + :language: YAML + +The playbook sets three of the seven values from the command line above: the group (``hosts: all``), the connection method (``connection: ansible.netcommon.network_cli``) and the module (in each task). With those values set in the playbook, you can omit them on the command line. The playbook also adds a second task to show the config output. When a module runs in a playbook, the output is held in memory for use by future tasks instead of written to the console. The debug task here lets you see the results in your shell. + +2. Run the playbook with the command: + +.. code-block:: bash + + ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos.vyos.vyos first_playbook.yml + +The playbook contains one play with two tasks, and should generate output like this: + +.. code-block:: shell + + $ ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos.vyos.vyos first_playbook.yml + + PLAY [Network Getting Started First Playbook] + *************************************************************************************************************************** + + TASK [Get config for VyOS devices] + *************************************************************************************************************************** + ok: [vyos.example.net] + + TASK [Display the config] + *************************************************************************************************************************** + ok: [vyos.example.net] => { + "msg": "The hostname is vyos and the OS is VyOS 1.1.8" + } + +3. Now that you can retrieve the device config, try updating it with Ansible. Download :download:`first_playbook_ext.yml <sample_files/first_playbook_ext.yml>`, which is an extended version of the first playbook: + +.. literalinclude:: sample_files/first_playbook_ext.yml + :language: YAML + +The extended first playbook has five tasks in a single play. Run it with the same command you used above. The output shows you the change Ansible made to the config: + +.. code-block:: shell + + $ ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos.vyos.vyos first_playbook_ext.yml + + PLAY [Network Getting Started First Playbook Extended] + ************************************************************************************************************************************ + + TASK [Get config for VyOS devices] + ********************************************************************************************************************************** + ok: [vyos.example.net] + + TASK [Display the config] + ************************************************************************************************************************************* + ok: [vyos.example.net] => { + "msg": "The hostname is vyos and the OS is VyOS 1.1.8" + } + + TASK [Update the hostname] + ************************************************************************************************************************************* + changed: [vyos.example.net] + + TASK [Get changed config for VyOS devices] + ************************************************************************************************************************************* + ok: [vyos.example.net] + + TASK [Display the changed config] + ************************************************************************************************************************************* + ok: [vyos.example.net] => { + "msg": "The new hostname is vyos-changed and the OS is VyOS 1.1.8" + } + + PLAY RECAP + ************************************************************************************************************************************ + vyos.example.net : ok=5 changed=1 unreachable=0 failed=0 + + + +.. _network_gather_facts: + +Gathering facts from network devices +==================================== + +The ``gather_facts`` keyword now supports gathering network device facts in standardized key/value pairs. You can feed these network facts into further tasks to manage the network device. + +You can also use the new ``gather_network_resources`` parameter with the network ``*_facts`` modules (such as :ref:`arista.eos.eos_facts <ansible_collections.arista.eos.eos_facts_module>`) to return just a subset of the device configuration, as shown below. + +.. code-block:: yaml + + - hosts: arista + gather_facts: True + gather_subset: interfaces + module_defaults: + arista.eos.eos_facts: + gather_network_resources: interfaces + +The playbook returns the following interface facts: + +.. code-block:: yaml + + "network_resources": { + "interfaces": [ + { + "description": "test-interface", + "enabled": true, + "mtu": "512", + "name": "Ethernet1" + }, + { + "enabled": true, + "mtu": "3000", + "name": "Ethernet2" + }, + { + "enabled": true, + "name": "Ethernet3" + }, + { + "enabled": true, + "name": "Ethernet4" + }, + { + "enabled": true, + "name": "Ethernet5" + }, + { + "enabled": true, + "name": "Ethernet6" + }, + ] + } + + +Note that this returns a subset of what is returned by just setting ``gather_subset: interfaces``. + +You can store these facts and use them directly in another task, such as with the :ref:`eos_interfaces <ansible_collections.arista.eos.eos_interfaces_module>` resource module. diff --git a/docs/docsite/rst/network/getting_started/index.rst b/docs/docsite/rst/network/getting_started/index.rst new file mode 100644 index 0000000..bf9f2eb --- /dev/null +++ b/docs/docsite/rst/network/getting_started/index.rst @@ -0,0 +1,34 @@ +.. _network_getting_started: + +********************************** +Network Getting Started +********************************** + +Ansible collections support a wide range of vendors, device types, and actions, so you can manage your entire network with a single automation tool. With Ansible, you can: + +- Automate repetitive tasks to speed routine network changes and free up your time for more strategic work +- Leverage the same simple, powerful, and agentless automation tool for network tasks that operations and development use +- Separate the data model (in a playbook or role) from the execution layer (through Ansible modules) to manage heterogeneous network devices +- Benefit from community and vendor-generated sample playbooks and roles to help accelerate network automation projects +- Communicate securely with network hardware over SSH or HTTPS + +**Who should use this guide?** + +This guide is intended for network engineers using Ansible for the first time. If you understand networks but have never used Ansible, work through the guide from start to finish. + +This guide is also useful for experienced Ansible users automating network tasks for the first time. You can use Ansible commands, playbooks and modules to configure hubs, switches, routers, bridges and other network devices. But network modules are different from Linux/Unix and Windows modules, and you must understand some network-specific concepts to succeed. If you understand Ansible but have never automated a network task, start with the second section. + +This guide introduces basic Ansible concepts and guides you through your first Ansible commands, playbooks and inventory entries. + +.. toctree:: + :maxdepth: 2 + :caption: Getting Started Guide + + basic_concepts + network_differences + first_playbook + first_inventory + network_roles + intermediate_concepts + network_connection_options + network_resources diff --git a/docs/docsite/rst/network/getting_started/intermediate_concepts.rst b/docs/docsite/rst/network/getting_started/intermediate_concepts.rst new file mode 100644 index 0000000..3496f22 --- /dev/null +++ b/docs/docsite/rst/network/getting_started/intermediate_concepts.rst @@ -0,0 +1,39 @@ +***************** +Beyond the basics +***************** + +This page introduces some concepts that help you manage your Ansible workflow with directory structure and source control. Like the Basic Concepts at the beginning of this guide, these intermediate concepts are common to all uses of Ansible. + +.. contents:: + :local: + + +A typical Ansible filetree +========================== + +Ansible expects to find certain files in certain places. As you expand your inventory and create and run more network playbooks, keep your files organized in your working Ansible project directory like this: + +.. code-block:: console + + . + ├── backup + │ ├── vyos.example.net_config.2018-02-08@11:10:15 + │ ├── vyos.example.net_config.2018-02-12@08:22:41 + ├── first_playbook.yml + ├── inventory + ├── group_vars + │ ├── vyos.yml + │ └── eos.yml + ├── roles + │ ├── static_route + │ └── system + ├── second_playbook.yml + └── third_playbook.yml + +The ``backup`` directory and the files in it get created when you run modules like ``vyos_config`` with the ``backup: yes`` parameter. + + +Tracking changes to inventory and playbooks: source control with git +==================================================================== + +As you expand your inventory, roles and playbooks, you should place your Ansible projects under source control. We recommend ``git`` for source control. ``git`` provides an audit trail, letting you track changes, roll back mistakes, view history and share the workload of managing, maintaining and expanding your Ansible ecosystem. There are plenty of tutorials and guides to using ``git`` available. diff --git a/docs/docsite/rst/network/getting_started/network_connection_options.rst b/docs/docsite/rst/network/getting_started/network_connection_options.rst new file mode 100644 index 0000000..bdfb93c --- /dev/null +++ b/docs/docsite/rst/network/getting_started/network_connection_options.rst @@ -0,0 +1,48 @@ +.. _network_connection_options: + +*************************************** +Working with network connection options +*************************************** + +Network modules can support multiple connection protocols, such as ``ansible.netcommon.network_cli``, ``ansible.netcommon.netconf``, and ``ansible.netcommon.httpapi``. These connections include some common options you can set to control how the connection to your network device behaves. + +Common options are: + +* ``become`` and ``become_method`` as described in :ref:`privilege_escalation`. +* ``network_os`` - set to match your network platform you are communicating with. See the :ref:`platform-specific <platform_options>` pages. +* ``remote_user`` as described in :ref:`connection_set_user`. +* Timeout options - ``persistent_command_timeout``, ``persistent_connect_timeout``, and ``timeout``. + +.. _timeout_options: + +Setting timeout options +======================= + +When communicating with a remote device, you have control over how long Ansible maintains the connection to that device, as well as how long Ansible waits for a command to complete on that device. Each of these options can be set as variables in your playbook files, environment variables, or settings in your :ref:`ansible.cfg file <ansible_configuration_settings>`. + +For example, the three options for controlling the connection timeout are as follows. + +Using vars (per task): + +.. code-block:: yaml + + - name: save running-config + cisco.ios.ios_command: + commands: copy running-config startup-config + vars: + ansible_command_timeout: 30 + +Using the environment variable: + +.. code-block:: bash + + $export ANSIBLE_PERSISTENT_COMMAND_TIMEOUT=30 + +Using the global configuration (in :file:`ansible.cfg`) + +.. code-block:: ini + + [persistent_connection] + command_timeout = 30 + +See :ref:`ansible_variable_precedence` for details on the relative precedence of each of these variables. See the individual connection type to understand each option. diff --git a/docs/docsite/rst/network/getting_started/network_differences.rst b/docs/docsite/rst/network/getting_started/network_differences.rst new file mode 100644 index 0000000..2ae583f --- /dev/null +++ b/docs/docsite/rst/network/getting_started/network_differences.rst @@ -0,0 +1,68 @@ +************************************************************ +How Network Automation is Different +************************************************************ + +Network automation uses the basic Ansible concepts, but there are important differences in how the network modules work. This introduction prepares you to understand the exercises in this guide. + +.. contents:: + :local: + +Execution on the control node +================================================================================ + +Unlike most Ansible modules, network modules do not run on the managed nodes. From a user's point of view, network modules work like any other modules. They work with ad hoc commands, playbooks, and roles. Behind the scenes, however, network modules use a different methodology than the other (Linux/Unix and Windows) modules use. Ansible is written and executed in Python. Because the majority of network devices can not run Python, the Ansible network modules are executed on the Ansible control node, where ``ansible`` or ``ansible-playbook`` runs. + +Network modules also use the control node as a destination for backup files, for those modules that offer a ``backup`` option. With Linux/Unix modules, where a configuration file already exists on the managed node(s), the backup file gets written by default in the same directory as the new, changed file. Network modules do not update configuration files on the managed nodes, because network configuration is not written in files. Network modules write backup files on the control node, usually in the `backup` directory under the playbook root directory. + +Multiple communication protocols +================================================================================ + +Because network modules execute on the control node instead of on the managed nodes, they can support multiple communication protocols. The communication protocol (XML over SSH, CLI over SSH, API over HTTPS) selected for each network module depends on the platform and the purpose of the module. Some network modules support only one protocol; some offer a choice. The most common protocol is CLI over SSH. You set the communication protocol with the ``ansible_connection`` variable: + +.. csv-table:: + :header: "Value of ansible_connection", "Protocol", "Requires", "Persistent?" + :widths: 30, 10, 10, 10 + + "ansible.netcommon.network_cli", "CLI over SSH", "network_os setting", "yes" + "ansible.netcommon.netconf", "XML over SSH", "network_os setting", "yes" + "ansible.netcommon.httpapi", "API over HTTP/HTTPS", "network_os setting", "yes" + "local", "depends on provider", "provider setting", "no" + +.. note:: + ``ansible.netcommon.httpapi`` deprecates ``eos_eapi`` and ``nxos_nxapi``. See :ref:`httpapi_plugins` for details and an example. + +The ``ansible_connection: local`` has been deprecated. Please use one of the persistent connection types listed above instead. With persistent connections, you can define the hosts and credentials only once, rather than in every task. You also need to set the ``network_os`` variable for the specific network platform you are communicating with. For more details on using each connection type on various platforms, see the :ref:`platform-specific <platform_options>` pages. + + +Collections organized by network platform +================================================================================ + +A network platform is a set of network devices with a common operating system that can be managed by an Ansible collection, for example: + +- Arista: `arista.eos <https://galaxy.ansible.com/arista/eos>`_ +- Cisco: `cisco.ios <https://galaxy.ansible.com/cisco/ios>`_, `cisco.iosxr <https://galaxy.ansible.com/cisco/iosxr>`_, `cisco.nxos <https://galaxy.ansible.com/cisco/nxos>`_ +- Juniper: `junipernetworks.junos <https://galaxy.ansible.com/junipernetworks/junos>`_ +- VyOS `vyos.vyos <https://galaxy.ansible.com/vyos/vyos>`_ + +All modules within a network platform share certain requirements. Some network platforms have specific differences - see the :ref:`platform-specific <platform_options>` documentation for details. + +.. _privilege_escalation: + +Privilege Escalation: ``enable`` mode, ``become``, and ``authorize`` +================================================================================ + +Several network platforms support privilege escalation, where certain tasks must be done by a privileged user. On network devices this is called the ``enable`` mode (the equivalent of ``sudo`` in \*nix administration). Ansible network modules offer privilege escalation for those network devices that support it. For details of which platforms support ``enable`` mode, with examples of how to use it, see the :ref:`platform-specific <platform_options>` documentation. + +Using ``become`` for privilege escalation +----------------------------------------- + +Use the top-level Ansible parameter ``become: yes`` with ``become_method: enable`` to run a task, play, or playbook with escalated privileges on any network platform that supports privilege escalation. You must use either ``connection: network_cli`` or ``connection: httpapi`` with ``become: yes`` with ``become_method: enable``. If you are using ``network_cli`` to connect Ansible to your network devices, a ``group_vars`` file would look like: + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: cisco.ios.ios + ansible_become: yes + ansible_become_method: enable + +For more information, see :ref:`Become and Networks<become_network>` diff --git a/docs/docsite/rst/network/getting_started/network_resources.rst b/docs/docsite/rst/network/getting_started/network_resources.rst new file mode 100644 index 0000000..a69aba9 --- /dev/null +++ b/docs/docsite/rst/network/getting_started/network_resources.rst @@ -0,0 +1,47 @@ + +.. _network_resources: + +************************ +Resources and next steps +************************ + +.. contents:: + :local: + +Documents +========= + +Read more about Ansible for Network Automation: + +- :ref:`Network Platform Options <platform_options>` +- Network Automation on the `Ansible website <https://www.ansible.com/overview/networking>`_ +- Ansible Network `Blog posts <https://www.ansible.com/blog/topic/networks>`_ + +Events (on video and in person) +=============================== + +All sessions at Ansible events are recorded and include many Network-related topics (use Filter by Category to view only Network topics). You can also join us for future events in your area. See: + +- `Recorded AnsibleFests <https://www.ansible.com/resources/videos/ansiblefest>`_ +- `Recorded AnsibleAutomates <https://www.ansible.com/resources/webinars-training>`_ +- `Upcoming Ansible Events <https://www.ansible.com/community/events>`_ page. + +GitHub repos +============ + +Ansible hosts module code, examples, demonstrations, and other content on GitHub. Anyone with a GitHub account is able to create Pull Requests (PRs) or issues on these repos: + +- `Network-Automation <https://github.com/network-automation>`_ is an open community for all things network automation. Have an idea, some playbooks, or roles to share? Email ansible-network@redhat.com and we will add you as a contributor to the repository. + +- `Ansible collections <https://github.com/ansible-collections>`_ is the main repository for Ansible-maintained and community collections, including collections for network devices. + + + +Chat channels +============= + +Got questions? Chat with us on: + +* the ``#ansible-network`` channel (using Matrix at ansible.im or using IRC at `irc.libera.chat <https://libera.chat/>`_) + +* `Ansible Network Slack <https://join.slack.com/t/ansiblenetwork/shared_invite/zt-3zeqmhhx-zuID9uJqbbpZ2KdVeTwvzw>`_ - Network & Security Automation Slack community. Check out the #devel channel for discussions on module and plugin development. diff --git a/docs/docsite/rst/network/getting_started/network_roles.rst b/docs/docsite/rst/network/getting_started/network_roles.rst new file mode 100644 index 0000000..4ffb833 --- /dev/null +++ b/docs/docsite/rst/network/getting_started/network_roles.rst @@ -0,0 +1,267 @@ + +.. _using_network_roles: + +************************* +Use Ansible network roles +************************* + +Roles are sets of Ansible defaults, files, tasks, templates, variables, and other Ansible components that work together. As you saw on :ref:`first_network_playbook`, moving from a command to a playbook makes it easy to run multiple tasks and repeat the same tasks in the same order. Moving from a playbook to a role makes it even easier to reuse and share your ordered tasks. You can look at :ref:`Ansible Galaxy <ansible_galaxy>`, which lets you share your roles and use others' roles, either directly or as inspiration. + +.. contents:: + :local: + +Understanding roles +=================== + +So what exactly is a role, and why should you care? Ansible roles are basically playbooks broken up into a known file structure. Moving to roles from a playbook makes sharing, reading, and updating your Ansible workflow easier. Users can write their own roles. So for example, you don't have to write your own DNS playbook. Instead, you specify a DNS server and a role to configure it for you. + +To simplify your workflow even further, the Ansible Network team has written a series of roles for common network use cases. Using these roles means you don't have to reinvent the wheel. Instead of writing and maintaining your own ``create_vlan`` playbooks or roles, you can concentrate on designing, codifying and maintaining the parser templates that describe your network topologies and inventory, and let Ansible's network roles do the work. See the `network-related roles <https://galaxy.ansible.com/ansible-network>`_ on Ansible Galaxy. + +A sample DNS playbook +--------------------- + +To demonstrate the concept of what a role is, the example ``playbook.yml`` below is a single YAML file containing a two-task playbook. This Ansible Playbook configures the hostname on a Cisco IOS XE device, then it configures the DNS (domain name system) servers. + +.. code-block:: yaml + + --- + - name: configure cisco routers + hosts: routers + connection: ansible.netcommon.network_cli + gather_facts: no + vars: + dns: "8.8.8.8 8.8.4.4" + + tasks: + - name: configure hostname + cisco.ios.ios_config: + lines: hostname {{ inventory_hostname }} + + - name: configure DNS + cisco.ios.ios_config: + lines: ip name-server {{dns}} + +If you run this playbook using the ``ansible-playbook`` command, you'll see the output below. This example used ``-l`` option to limit the playbook to only executing on the **rtr1** node. + +.. code-block:: bash + + [user@ansible ~]$ ansible-playbook playbook.yml -l rtr1 + + PLAY [configure cisco routers] ************************************************* + + TASK [configure hostname] ****************************************************** + changed: [rtr1] + + TASK [configure DNS] *********************************************************** + changed: [rtr1] + + PLAY RECAP ********************************************************************* + rtr1 : ok=2 changed=2 unreachable=0 failed=0 + + +This playbook configured the hostname and DNS servers. You can verify that configuration on the Cisco IOS XE **rtr1** router: + +.. code-block:: bash + + rtr1#sh run | i name + hostname rtr1 + ip name-server 8.8.8.8 8.8.4.4 + +Convert the playbook into a role +--------------------------------- + +The next step is to convert this playbook into a reusable role. You can create the directory structure manually, or you can use ``ansible-galaxy init`` to create the standard framework for a role. + +.. code-block:: bash + + [user@ansible ~]$ ansible-galaxy init system-demo + [user@ansible ~]$ cd system-demo/ + [user@ansible system-demo]$ tree + . + ├── defaults + │ └── main.yml + ├── files + ├── handlers + │ └── main.yml + ├── meta + │ └── main.yml + ├── README.md + ├── tasks + │ └── main.yml + ├── templates + ├── tests + │ ├── inventory + │ └── test.yml + └── vars + └── main.yml + +This first demonstration uses only the **tasks** and **vars** directories. The directory structure would look as follows: + +.. code-block:: bash + + [user@ansible system-demo]$ tree + . + ├── tasks + │ └── main.yml + └── vars + └── main.yml + +Next, move the content of the ``vars`` and ``tasks`` sections from the original Ansible Playbook into the role. First, move the two tasks into the ``tasks/main.yml`` file: + +.. code-block:: bash + + [user@ansible system-demo]$ cat tasks/main.yml + --- + - name: configure hostname + cisco.ios.ios_config: + lines: hostname {{ inventory_hostname }} + + - name: configure DNS + cisco.ios.ios_config: + lines: ip name-server {{dns}} + +Next, move the variables into the ``vars/main.yml`` file: + +.. code-block:: bash + + [user@ansible system-demo]$ cat vars/main.yml + --- + dns: "8.8.8.8 8.8.4.4" + +Finally, modify the original Ansible Playbook to remove the ``tasks`` and ``vars`` sections and add the keyword ``roles`` with the name of the role, in this case ``system-demo``. You'll have this playbook: + +.. code-block:: yaml + + --- + - name: configure cisco routers + hosts: routers + connection: ansible.netcommon.network_cli + gather_facts: no + + roles: + - system-demo + +To summarize, this demonstration now has a total of three directories and three YAML files. There is the ``system-demo`` folder, which represents the role. This ``system-demo`` contains two folders, ``tasks`` and ``vars``. There is a ``main.yml`` is each respective folder. The ``vars/main.yml`` contains the variables from ``playbook.yml``. The ``tasks/main.yml`` contains the tasks from ``playbook.yml``. The ``playbook.yml`` file has been modified to call the role rather than specifying vars and tasks directly. Here is a tree of the current working directory: + +.. code-block:: bash + + [user@ansible ~]$ tree + . + ├── playbook.yml + └── system-demo + ├── tasks + │ └── main.yml + └── vars + └── main.yml + +Running the playbook results in identical behavior with slightly different output: + +.. code-block:: bash + + [user@ansible ~]$ ansible-playbook playbook.yml -l rtr1 + + PLAY [configure cisco routers] ************************************************* + + TASK [system-demo : configure hostname] **************************************** + ok: [rtr1] + + TASK [system-demo : configure DNS] ********************************************* + ok: [rtr1] + + PLAY RECAP ********************************************************************* + rtr1 : ok=2 changed=0 unreachable=0 failed=0 + +As seen above each task is now prepended with the role name, in this case ``system-demo``. When running a playbook that contains several roles, this will help pinpoint where a task is being called from. This playbook returned ``ok`` instead of ``changed`` because it has identical behavior for the single file playbook we started from. + +As before, the playbook will generate the following configuration on a Cisco IOS-XE router: + +.. code-block:: bash + + rtr1#sh run | i name + hostname rtr1 + ip name-server 8.8.8.8 8.8.4.4 + + +This is why Ansible roles can be simply thought of as deconstructed playbooks. They are simple, effective and reusable. Now another user can simply include the ``system-demo`` role instead of having to create a custom "hard coded" playbook. + +Variable precedence +------------------- + +What if you want to change the DNS servers? You aren't expected to change the ``vars/main.yml`` within the role structure. Ansible has many places where you can specify variables for a given play. See :ref:`playbooks_variables` for details on variables and precedence. There are actually 21 places to put variables. While this list can seem overwhelming at first glance, the vast majority of use cases only involve knowing the spot for variables of least precedence and how to pass variables with most precedence. See :ref:`ansible_variable_precedence` for more guidance on where you should put variables. + +Lowest precedence +^^^^^^^^^^^^^^^^^ + +The lowest precedence is the ``defaults`` directory within a role. This means all the other 20 locations you could potentially specify the variable will all take higher precedence than ``defaults``, no matter what. To immediately give the vars from the ``system-demo`` role the least precedence, rename the ``vars`` directory to ``defaults``. + +.. code-block:: bash + + [user@ansible system-demo]$ mv vars defaults + [user@ansible system-demo]$ tree + . + ├── defaults + │ └── main.yml + ├── tasks + │ └── main.yml + +Add a new ``vars`` section to the playbook to override the default behavior (where the variable ``dns`` is set to 8.8.8.8 and 8.8.4.4). For this demonstration, set ``dns`` to 1.1.1.1, so ``playbook.yml`` becomes: + +.. code-block:: yaml + + --- + - name: configure cisco routers + hosts: routers + connection: ansible.netcommon.network_cli + gather_facts: no + vars: + dns: 1.1.1.1 + roles: + - system-demo + +Run this updated playbook on **rtr2**: + +.. code-block:: bash + + [user@ansible ~]$ ansible-playbook playbook.yml -l rtr2 + +The configuration on the **rtr2** Cisco router will look as follows: + +.. code-block:: bash + + rtr2#sh run | i name-server + ip name-server 1.1.1.1 + +The variable configured in the playbook now has precedence over the ``defaults`` directory. In fact, any other spot you configure variables would win over the values in the ``defaults`` directory. + +Highest precedence +^^^^^^^^^^^^^^^^^^ + +Specifying variables in the ``defaults`` directory within a role will always take the lowest precedence, while specifying ``vars`` as extra vars with the ``-e`` or ``--extra-vars=`` will always take the highest precedence, no matter what. Re-running the playbook with the ``-e`` option overrides both the ``defaults`` directory (8.8.4.4 and 8.8.8.8) as well as the newly created ``vars`` within the playbook that contains the 1.1.1.1 dns server. + +.. code-block:: bash + + [user@ansible ~]$ ansible-playbook playbook.yml -e "dns=192.168.1.1" -l rtr3 + +The result on the Cisco IOS XE router will only contain the highest precedence setting of 192.168.1.1: + +.. code-block:: bash + + rtr3#sh run | i name-server + ip name-server 192.168.1.1 + +How is this useful? Why should you care? Extra vars are commonly used by network operators to override defaults. A powerful example of this is with the Job Template Survey feature on AWX or the :ref:`ansible_platform`. It is possible through the web UI to prompt a network operator to fill out parameters with a Web form. This can be really simple for non-technical playbook writers to execute a playbook using their Web browser. + + +Update an installed role +------------------------ + +The Ansible Galaxy page for a role lists all available versions. To update a locally installed role to a new or different version, use the ``ansible-galaxy install`` command with the version and ``--force`` option. You may also need to manually update any dependent roles to support this version. See the role **Read Me** tab in Galaxy for dependent role minimum version requirements. + +.. code-block:: bash + + [user@ansible]$ ansible-galaxy install mynamespace.my_role,v2.7.1 --force + +.. seealso:: + + `Ansible Galaxy documentation <https://galaxy.ansible.com/docs/>`_ + Ansible Galaxy user guide diff --git a/docs/docsite/rst/network/getting_started/sample_files/first_playbook.yml b/docs/docsite/rst/network/getting_started/sample_files/first_playbook.yml new file mode 100644 index 0000000..908b89f --- /dev/null +++ b/docs/docsite/rst/network/getting_started/sample_files/first_playbook.yml @@ -0,0 +1,15 @@ +--- + +- name: Network Getting Started First Playbook + connection: ansible.netcommon.network_cli + gather_facts: false + hosts: all + tasks: + + - name: Get config for VyOS devices + vyos.vyos.vyos_facts: + gather_subset: all + + - name: Display the config + debug: + msg: "The hostname is {{ ansible_net_hostname }} and the OS is {{ ansible_net_version }}" diff --git a/docs/docsite/rst/network/getting_started/sample_files/first_playbook_ext.yml b/docs/docsite/rst/network/getting_started/sample_files/first_playbook_ext.yml new file mode 100644 index 0000000..2d5f6a5 --- /dev/null +++ b/docs/docsite/rst/network/getting_started/sample_files/first_playbook_ext.yml @@ -0,0 +1,29 @@ +--- + +- name: Network Getting Started First Playbook Extended + connection: ansible.netcommon.network_cli + gather_facts: false + hosts: all + tasks: + + - name: Get config for VyOS devices + vyos.vyos.vyos_facts: + gather_subset: all + + - name: Display the config + debug: + msg: "The hostname is {{ ansible_net_hostname }} and the OS is {{ ansible_net_version }}" + + - name: Update the hostname + vyos.vyos.vyos_config: + backup: yes + lines: + - set system host-name vyos-changed + + - name: Get changed config for VyOS devices + vyos.vyos.vyos_facts: + gather_subset: all + + - name: Display the changed config + debug: + msg: "The new hostname is {{ ansible_net_hostname }} and the OS is {{ ansible_net_version }}" |