Network Getting started docs (#36337)

* first draft of getting started guide

docs/docsite/rst/index.rst

@@ -49,7 +49,6 @@ Ansible, Inc. releases a new major release of Ansible approximately every two mo
    :maxdepth: 2
    :caption: Scenario Guides
 
-   networking_guide/network
    scenario_guides/guide_aws
    scenario_guides/guide_azure
    scenario_guides/guide_rax
@@ -61,6 +60,13 @@ Ansible, Inc. releases a new major release of Ansible approximately every two mo
    scenario_guides/guide_packet
    scenario_guides/guide_rolling_upgrade
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Ansible for Network Automation
+
+   network/index
+   network/getting_started
+
 .. toctree::
    :maxdepth: 2
    :caption: Reference & Appendices

docs/docsite/rst/network/getting_started/basic_concepts.rst

@@ -0,0 +1,37 @@
+***************************************
+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:: Topics
+
+Control Node
+================================================================================
+
+Any machine with Ansible installed. You can run commands and playbooks, invoking ``/usr/bin/ansible`` or ``/usr/bin/ansible-playbook``, from any control node. You can use any computer that has Python installed on it as a control node - laptops, shared desktops, and servers can all run Ansible. However, you cannot use a Windows machine as a control node. You can have multiple control nodes.
+
+Managed Nodes
+================================================================================
+
+The network devices (and/or servers) you manage with Ansible. Managed nodes are also sometimes called "hosts". Ansible is not installed on managed nodes.
+
+Inventory
+================================================================================
+
+A list of managed nodes. An inventory file is also sometimes called a "hostfile". Your inventory can specify information like IP address for each managed node. An inventory can also organize managed nodes, creating and nesting groups for easier scaling. To learn more about inventory, see :doc:`the Working with Inventory<../../user_guide/intro_inventory>` pages.
+
+Modules
+================================================================================
+
+The units of code Ansible executes. Each module has a particular use, from administering users on a specific type of database to managing VLAN interfaces on a specific type of network device. 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 :doc:`list of all modules<../../modules/modules_by_category>` or the :doc:`list of network modules<../../modules/list_of_network_modules>`.
+
+Tasks
+================================================================================
+
+The units of action in Ansible. You can execute a single task once with an ad-hoc command. 
+
+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. To learn more about playbooks, see :doc:`../../user_guide/playbooks_intro`.

docs/docsite/rst/network/getting_started/first_inventory.rst

@@ -0,0 +1,253 @@
+***********************************************
+Build Your Inventory
+***********************************************
+
+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:: Topics
+
+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]
+   leaf01
+   leaf02
+
+   [spines]
+   spine01
+   spine02
+
+   [network:children]
+   leafs
+   spines
+
+   [webservers]
+   webserver01
+   webserver02
+
+   [datacenter:children]
+   network
+   webservers
+
+
+Add Variables to 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]
+   leaf01 ansible_host=10.16.10.11 ansible_network_os=vyos ansible_user=my_vyos_user
+   leaf02 ansible_host=10.16.10.12 ansible_network_os=vyos ansible_user=my_vyos_user
+
+   [spines]
+   spine01 ansible_host=10.16.10.13 ansible_network_os=vyos ansible_user=my_vyos_user
+   spine02 ansible_host=10.16.10.14 ansible_network_os=vyos ansible_user=my_vyos_user
+
+   [network:children]
+   leafs
+   spines
+
+   [servers]
+   server01 ansible_host=10.16.10.15 ansible_user=my_server_user
+   server02 ansible_host=10.16.10.16 ansible_user=my_server_user
+
+   [datacenter:children]
+   leafs
+   spines
+   servers
+
+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]
+   leaf01 ansible_host=10.16.10.11
+   leaf02 ansible_host=10.16.10.12
+
+   [leafs:vars]
+   ansible_network_os=vyos
+   ansible_user=my_vyos_user
+
+   [spines]
+   spine01 ansible_host=10.16.10.13
+   spine02 ansible_host=10.16.10.14
+
+   [spines:vars]
+   ansible_network_os=vyos
+   ansible_user=my_vyos_user
+
+   [network:children]
+   leafs
+   spines
+
+   [servers]
+   server01 ansible_host=10.16.10.15
+   server02 ansible_host=10.16.10.16
+
+   [datacenter:children]
+   leafs
+   spines
+   servers
+
+Variable Syntax
+================================================================================
+
+The syntax for variable values is different in inventory, in playbooks and in ``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 inventory file you **must** use the syntax ``key=value`` for variable values: ``ansible_network_os=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``. 
+  - In playbooks, use the short-form ``key`` name, which drops the ``ansible`` prefix: ``network_os: vyos``
+
+
+Move Group Variables to ``group_vars`` Files
+================================================================================
+
+As your inventory grows, you may want to group devices by platform and move shared variables out of the main inventory file into a set of group variable files. This reduces duplication further and sets the stage for managing devices on multiple platforms in a single inventory file. The directory tree for this setup looks like this:
+
+.. code-block:: console
+
+   .
+   ├── first_playbook.yml
+   ├── inventory
+   ├── group_vars
+       └── vyos.yml
+
+The group name must match the file name in your ``group_vars`` directory. In this example, Ansible will load the file ``group_vars/vyos.yml`` when it finds the group ``[vyos]`` in the inventory. So this inventory:
+
+.. code-block:: yaml
+
+   [vyos_leafs]
+   leaf01 ansible_host=10.16.10.11
+   leaf02 ansible_host=10.16.10.12
+
+   [vyos_spines]
+   spine01 ansible_host=10.16.10.13
+   spine02 ansible_host=10.16.10.14
+
+   [vyos:children]
+   vyos_leafs
+   vyos_spines
+
+   [network:children]
+   vyos
+
+   [servers]
+   server01 ansible_host=10.16.10.15
+   server02 ansible_host=10.16.10.16
+
+   [datacenter:children]
+   vyos
+   servers
+
+works with this ``group_vars/vyos.yml`` content:
+
+.. code-block:: yaml
+
+   ansible_connection: network_cli
+   ansible_network_os: vyos
+   ansible_user: my_vyos_user
+
+
+With this setup, you can run first_playbook.yml with only two flags:
+
+.. code-block:: bash
+
+   ansible-playbook -i inventory -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``. 
+
+
+Protecting Sensitive Variables with ``ansible-vault`` 
+================================================================================
+
+The ``ansible-vault`` command provides encryption for files and/or individual variables like passwords. This tutorial uses SSH passwords for an example. 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. Then you can encrypt dozens of different passwords across your Ansible project. You can access all those secrets with a single password (the ansible-vault password) when you run your playbooks. Here's a simple example.
+
+Create a file and write your password for ansible-vault to it:
+
+.. code-block:: bash
+
+   echo "my-ansible-vault-pw" > ~/my-ansible-vault-pw-file
+
+Encrypt the ssh password for your VyOS network devices, pulling your ansible-vault password from the file you just created:
+
+.. code-block:: bash
+
+   ansible-vault encrypt_string --vault-id my_user@~/my-ansible-vault-pw-file 'VyOS_SSH_password' --name 'ansible_ssh_pass'
+
+If you prefer to type your vault password rather than store it in a file, you can request a prompt:
+
+.. code-block:: bash
+
+   ansible-vault encrypt_string --vault-id my_user@prompt 'VyOS_SSH_password' --name 'ansible_ssh_pass'
+
+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:: bash
+
+   ansible_ssh_pass: !vault |
+          $ANSIBLE_VAULT;1.2;AES256;my_user
+          66386134653765386232383236303063623663343437643766386435663632343266393064373933
+          3661666132363339303639353538316662616638356631650a316338316663666439383138353032
+          63393934343937373637306162366265383461316334383132626462656463363630613832313562
+          3837646266663835640a313164343535316666653031353763613037656362613535633538386539
+          65656439626166666363323435613131643066353762333232326232323565376635
+   Encryption successful
+
+Copy this output into your ``group_vars/vyos.yml`` file, which now looks like this:
+
+.. code-block:: yaml
+
+   ansible_connection: network_cli
+   ansible_network_os: vyos
+   ansible_user: my_vyos_user
+   ansible_ssh_pass: !vault |
+          $ANSIBLE_VAULT;1.2;AES256;my_user
+          66386134653765386232383236303063623663343437643766386435663632343266393064373933
+          3661666132363339303639353538316662616638356631650a316338316663666439383138353032
+          63393934343937373637306162366265383461316334383132626462656463363630613832313562
+          3837646266663835640a313164343535316666653031353763613037656362613535633538386539
+          65656439626166666363323435613131643066353762333232326232323565376635
+
+To run a playbook with this setup, drop the ``-k`` flag and add a flag for your ``vault-id``:
+
+.. code-block:: bash
+
+   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:: bash
+
+   ansible-playbook -i inventory --vault-id my_user@prompt first_playbook.yml
+
+
+.. 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 :doc:`the introduction to inventory<../../user_guide/intro_inventory>`; for more details on ansible-vault, see :doc:`the full Ansible Vault documentation<../../user_guide/vault>`.
+
+Now that you understand the basics of commands, playbooks, and inventory, it's time to explore some more complex Ansible Network examples. 

docs/docsite/rst/network/getting_started/first_playbook.rst

@@ -0,0 +1,157 @@
+***************************************************
+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:: Topics
+
+Prerequisites
+==================================================
+
+Before you work through this tutorial you need:
+
+- Ansible 2.5 (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 :doc:`../../installation_guide/intro_installation`. Then return to this tutorial.
+
+Confirm the version of Ansible (must be >= 2.5):
+
+.. 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 network_cli -u my_vyos_user -k -m vyos_facts -e ansible_network_os=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)
+  - 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.
+
+
+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: 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 first_playbook.yml
+
+The playbook contains one play with two tasks, and should generate output like this:
+
+.. code-block:: bash
+
+   $ ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos first_playbook.yml
+   
+   PLAY [First Playbook]
+   ***************************************************************************************************************************
+   
+   TASK [Gathering Facts]
+   ***************************************************************************************************************************
+   ok: [vyos.example.net]
+
+   TASK [Get config for VyOS devices]
+   ***************************************************************************************************************************
+   ok: [vyos.example.net]
+   
+   TASK [Display the config]
+   ***************************************************************************************************************************
+   ok: [vyos.example.net] => {
+       "failed": false, 
+       "msg": "The hostname is vyos and the OS is VyOS"
+   }
+
+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 four 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:: bash
+
+   $ ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos first_playbook_ext.yml 
+
+   PLAY [First Playbook]
+   ************************************************************************************************************************************
+   
+   TASK [Gathering Facts]
+   ***********************************************************************************************************************************
+   ok: [vyos.example.net]
+   
+   TASK [Get config for VyOS devices]
+   **********************************************************************************************************************************
+   ok: [vyos.example.net]
+
+   TASK [Display the config]
+   *************************************************************************************************************************************
+   ok: [vyos.example.net] => {
+       "failed": false, 
+       "msg": "The hostname is vyos and the OS is VyOS"
+   }
+   
+   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] => {
+       "failed": false, 
+       "msg": "The hostname is vyos-changed and the OS is VyOS"
+   }
+   
+   PLAY RECAP
+   ************************************************************************************************************************************
+   vyos.example.net           : ok=6    changed=1    unreachable=0    failed=0   
+
+
+This playbook is useful. However, running it still 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. 

docs/docsite/rst/network/getting_started/index.rst

@@ -0,0 +1,23 @@
+**************************************************
+An Introduction to Network Automation with Ansible
+**************************************************
+
+Ansible modules 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 (via 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

docs/docsite/rst/network/getting_started/intermediate_concepts.rst

@@ -0,0 +1,85 @@
+******************************************
+Beyond the Basics
+******************************************
+
+This page introduces some concepts that help you manage your Ansible workflow: roles, 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. This page also offers resources for learning more.
+
+.. contents:: Topics
+
+Beyond Playbooks: Moving Tasks and Variables into Roles
+================================================================================
+
+Roles are sets of Ansible defaults, files, tasks, templates, variables, and other Ansible components that work together. As you saw on the Working with Playbooks page, 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. For more details, see the :doc:`documentation on roles<../../user_guide/playbooks_reuse_roles>`. You can also look at :doc:`Ansible Galaxy<../../reference_appendices/galaxy>`, which lets you share your roles and use others' roles, either directly or as inspiration.
+
+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 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.
+
+Resources and Next Steps
+================================================================================
+
+Text
+--------
+
+Read more about Ansible for Network Automation:
+
+- Network Automation on the `Ansible website <http://ansible.com/overview/networking>`_
+- Ansible Network `Blog posts <http://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>`_ 
+- `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
+- `Ansible <https://github.com/ansible/ansible>`_ is the main codebase, including code for network modules
+
+Email
+--------
+
+Join the Ansible Network Community email list:
+
+- email ansible-network@redhat.com and we will get you added right away
+
+IRC
+--------
+
+Join us on Freenode IRC:
+
+- ``#ansible-network`` Freenode channel
+

docs/docsite/rst/network/getting_started/network_differences.rst

@@ -0,0 +1,94 @@
+************************************************************
+How Network Automation is Different
+************************************************************
+
+Network automation leverages 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:: Topics
+
+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. 
+
+Execution on the control node shapes two other differences in how network modules function:
+
+- Network modules do not run every task in a playbook. They request current config first, compare current config to the state described by the task or playbook, and execute a task only if it changes the state of the managed node.
+
+- Network modules that offer a backup option write the backup files onto the control node. 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, 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"
+   :widths: 30, 10, 10
+
+   "network_cli", "CLI over SSH", "network_os setting"
+   "netconf", "XML over SSH", "network_os setting"
+   "local", "depends on provider", "provider setting"
+
+Beginning with Ansible 2.5, we recommend using ``network_cli`` or ``netconf`` for ``ansible_connection`` whenever possible. For details on using API over HTTPS connections, see the platform-specific pages.
+
+
+Modules Organized by Network Platform
+================================================================================
+
+A network platform is a set of network devices with a common operating system that can be managed by a collection of modules.  The modules for each network platform share a prefix, for example: 
+
+- Arista: ``eos_``
+- Cisco: ``ios_``, ``iosxr_``, ``nxos_``
+- Juniper: ``junos_``
+- VyOS ``vyos_``
+
+All modules within a network platform share certain requirements. Some network platforms have specific differences - see the platform-specific documentation for details.
+
+
+Privilege Escalation: `authorize` and `become`
+================================================================================
+
+Several network platforms support privilege escalation, where certain tasks must be done by a privileged user. This is generally known as ``enable`` mode (the equivalent of ``sudo`` in \*nix administration). Ansible network modules offer privilege escalation for those network devices that support it. However, different platforms use privilege escalation in different ways. 
+
+Network platforms that support ``connection: network_cli`` and privilege escalation use the top-level Ansible parameter ``become: yes`` with ``become_method: enable``. For modules in these platforms, a ``group_vars`` file would look like:
+
+.. code-block:: yaml
+
+   ansible_connection: network_cli
+   ansible_network_os: ios
+   ansible_become: yes
+   ansible_become_method: enable
+
+We recommend using ``network_cli`` connections whenever possible. 
+
+Some network platforms support privilege escalation but cannot use ``network_cli`` connections yet. This includes all platforms in older versions of Ansible (< 2.5) and HTTPS connections using ``eapi`` in version 2.5. With these connections, you must use a ``provider`` dictionary and include ``authorize: yes`` and ``auth_pass: my_enable_password``. For that use case, a ``group_vars`` file looks like:
+
+.. code-block:: yaml
+
+   ansible_connection: local
+   ansible_network_os: eos
+   # provider settings
+   eapi:
+     authorize: yes
+     auth_pass: " {{ secret_auth_pass }}"
+     port: 80
+     transport: eapi
+     use_ssl: no
+
+And you use the ``setting`` variable in your play(s) or task(s):
+
+.. code-block:: yaml
+
+   tasks:
+   - name: provider demo with eos
+     eos_banner:
+       banner: motd
+       text: |
+         this is test
+         of multiline
+         string
+       state: present
+       provider: "{{ eapi }}"
+
+For more information, see :ref:`Become and Networks<become-network>`

docs/docsite/rst/network/getting_started/sample_files/first_playbook.yml

@@ -0,0 +1,14 @@
+---
+
+- name: Network Getting Started First Playbook
+  connection: network_cli
+  hosts: all
+  tasks:
+
+    - name: Get config for VyOS devices
+      vyos_facts:
+        gather_subset: all
+
+    - name: Display the config
+      debug:
+        msg: "The hostname is {{ ansible_net_hostname }} and the OS is {{ ansible_net_version }}"

docs/docsite/rst/network/getting_started/sample_files/first_playbook_ext.yml

@@ -0,0 +1,28 @@
+---
+
+- name: Network Getting Started First Playbook Extended
+  connection: network_cli
+  hosts: all
+  tasks:
+
+    - name: Get config for VyOS devices
+      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_config:
+        backup: yes
+        lines:
+          - set system host-name vyos-changed
+
+    - name: Get changed config for VyOS devices
+      vyos_facts:
+        gather_subset: all
+
+    - name: Display the changed config
+      debug:
+        msg: "The hostname is {{ ansible_net_hostname }} and the OS is {{ ansible_net_version }}"

docs/docsite/rst/network/index.rst

@@ -0,0 +1,36 @@
+******************************
+Ansible for Network Automation
+******************************
+
+Introduction
+============
+
+Ansible Network modules extend the benefits of simple, powerful, agentless automation to network administrators and teams. Ansible Network modules can configure your network stack, test and validate existing network state, and discover and correct network configuration drift.
+
+If you're new to Ansible, or new to using Ansible for network management, start with the Getting Started Guide.
+
+For documentation on using a particular network module, consult the :doc:`list of all network modules<../modules/list_of_network_modules>`. Some network modules are maintained by the Ansible community - here's a list of :doc:`network modules maintained by the Ansible Network Team<../modules/network_maintained>`.
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Getting Started
+
+   getting_started/index
+   getting_started/basic_concepts
+   getting_started/network_differences
+   getting_started/first_playbook
+   getting_started/first_inventory
+   getting_started/intermediate_concepts
+
+
+
+
+.. toctree::
+   :maxdepth: 3
+   :caption: User Guide
+
+   user_guide/index
+   user_guide/network_best_practices_2.5
+   user_guide/network_debug_troubleshooting
+   user_guide/network_working_with_command_output
+

docs/docsite/rst/network/user_guide/index.rst

@@ -0,0 +1,15 @@
+************************************************
+User Guide to to Network Automation with Ansible
+************************************************
+
+More content coming soon!
+
+Who should use this guide?
+================================================================================
+
+This guide is intended for network engineers using Ansible for automation. It covers advanced topics. If you understand networks and Ansible, this guide is for you. You may read through the entire guide if you choose, or use the links below to find the specific information you need.
+
+If you're new to Ansible, or new to using Ansible for network automation, start with the :doc:`Getting Started Guide<../getting_started/index>`.
+
+.. toctree::
+   :maxdepth: 2

docs/docsite/rst/network/user_guide/network_best_practices_2.5.rst

@@ -22,10 +22,10 @@ Prerequisites
 
 This example requires the following:
 
-* **Ansible 2.5** (or higher) installed. See :doc:`intro_installation` for more information.
+* **Ansible 2.5** (or higher) installed. See :doc:`../installation_guide/intro_installation` for more information.
 * One or more network devices that are compatible with Ansible.
-* Basic understanding of YAML :doc:`YAMLSyntax`.
+* Basic understanding of YAML :doc:`../reference_appendices/YAMLSyntax`.
-* Basic understanding of Jinja2 Templates. See :doc:`playbooks_templating` for more information.
+* Basic understanding of Jinja2 Templates. See :doc:`../user_guide/playbooks_templating` for more information.
 * Basic Linux command line use.
 * Basic knowledge of network switch & router configurations.
 
@@ -118,7 +118,7 @@ Because Ansible is a flexible tool, there are a number of ways to specify connec
 
 .. warning:: Never store passwords in plain text.
 
-The "Vault" feature of Ansible allows you to keep sensitive data such as passwords or keys in encrypted files, rather than as plain text in your playbooks or roles. These vault files can then be distributed or placed in source control. See :doc:`playbooks_vault` for more information.
+The "Vault" feature of Ansible allows you to keep sensitive data such as passwords or keys in encrypted files, rather than as plain text in your playbooks or roles. These vault files can then be distributed or placed in source control. See :doc:`../user_guide/playbooks_vault` for more information.
 
 :ansible_connection:
 
@@ -148,7 +148,7 @@ Certain network platforms, such as eos and ios, have the concept of different pr
    ansible_become: yes
    ansible_become_method: enable
 
-For more information, see the :ref:`using become with network modules<become-and-networks>` guide.
+For more information, see the :ref:`using become with network modules<become-network>` guide.
 
 
 Jump hosts
@@ -361,9 +361,9 @@ If you receive an connection error please double check the inventory and Playboo
 
 .. seealso::
 
-  * :doc:`intro_network`
+  * :doc:`../network/index`
-  * :doc:`intro_inventory`
+  * :doc:`../user_guide/intro_inventory`
-  * :ref:`Vault best practices <best-practices-for-variables-and-vaults>`
+  * :ref:`Vault best practices <best_practices_for_variables_and_vaults>`
 
 
 

docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst

@@ -201,7 +201,7 @@ Category "Unable to open shell"
 
 **Platforms:** Any
 
-The ``unable to open shell`` message is new in Ansible 2.3. This message means that the ``ansible-connection`` daemon has not been able to successfully talk to the remote network device. This generally means that there is an authentication issue. It is a "catch all" message, meaning you need to enable :ref:`log_path` to find the underlying issues.
+The ``unable to open shell`` message is new in Ansible 2.3. This message means that the ``ansible-connection`` daemon has not been able to successfully talk to the remote network device. This generally means that there is an authentication issue. It is a "catch all" message, meaning you need to enable :ref:logging`a_note_about_logging` to find the underlying issues.
 
 
 
@@ -280,7 +280,7 @@ For example:
 
 Suggestions to resolve:
 
-If you are specifying credentials via ``password:`` (either directly or via ``provider:``) or the environment variable :envvar:`ANSIBLE_NET_PASSWORD` it is possible that ``paramiko`` (the Python SSH library that Ansible uses) is using ssh keys, and therefore the credentials you are specifying are being ignored. To find out if this is the case, disable "look for keys". This can be done like this:
+If you are specifying credentials via ``password:`` (either directly or via ``provider:``) or the environment variable `ANSIBLE_NET_PASSWORD` it is possible that ``paramiko`` (the Python SSH library that Ansible uses) is using ssh keys, and therefore the credentials you are specifying are being ignored. To find out if this is the case, disable "look for keys". This can be done like this:
 
 .. code-block:: yaml
 
@@ -501,7 +501,7 @@ Network modules require that the connection is set to ``local``.  Any other
 connection setting will cause the playbook to fail.  Ansible will now detect
 this condition and return an error message:
 
-.. code-block:: yaml
+.. code-block:: console
 
     fatal: [nxos01]: FAILED! => {
         "changed": false,
@@ -526,7 +526,7 @@ This occurs when you attempt to run a task that requires privileged mode in a us
 
 For example:
 
-.. code-block:: yaml
+.. code-block:: console
 
   TASK [ios_system : configure name_servers] *****************************************************************************
   task path:
@@ -549,7 +549,7 @@ Add ``authorize: yes`` to the task. For example:
         authorize: yes
     register: result
 
-If the user requires a password to go into privileged mode, this can be specified with ``auth_pass``; if ``auth_pass`` isn't set, the environment variable :envvar:`ANSIBLE_NET_AUTHORIZE` will be used instead.
+If the user requires a password to go into privileged mode, this can be specified with ``auth_pass``; if ``auth_pass`` isn't set, the environment variable `ANSIBLE_NET_AUTHORIZE` will be used instead.
 
 
 Add ``authorize: yes`` to the task. For example:

docs/docsite/rst/networking_guide/network.rst

@@ -1,21 +0,0 @@
-************************
-Ansible Networking Guide
-************************
-
-Introduction
-============
-
-Ansible Network extends the benefits of simple, powerful, agentless automation to network administrators and teams. Ansible Network modules can configure your network stack, test and validate existing network state, and discover and correct network configuration drift.
-
-If you're new to Ansible, or new to using Ansible for network management, start with the Getting Started Guide (under development). 
-
-For documentation on using a particular network module, consult the :doc:`list of all network modules<module_docs/list_of_network_modules>`. Some network modules are maintained by the Ansible community - here's a list of :doc:`network modules maintained by the Ansible Network Team<module_docs/network_maintained>`.
-
-
-.. toctree::
-   :maxdepth: 3
-
-   network_best_practices_2.5
-   network_debug_troubleshooting
-   network_working_with_command_output
-