diff --git a/docs/docsite/rst/community/maintainers.rst b/docs/docsite/rst/community/maintainers.rst index 2f3a36a29a7..631e19a9a3d 100644 --- a/docs/docsite/rst/community/maintainers.rst +++ b/docs/docsite/rst/community/maintainers.rst @@ -51,7 +51,7 @@ Automated routing of pull requests is handled by a tool called `Ansibot `_. -* Ansibullbot: https://github.com/ansible/ansibullbot -* :doc:`development_process` +* `PRs in flight, organized by directory `_ +* `Ansibullbot `_ +* :ref:`community_development_process` diff --git a/docs/docsite/rst/network/getting_started/basic_concepts.rst b/docs/docsite/rst/network/getting_started/basic_concepts.rst index 57c78e66a7a..ec4c22359b2 100644 --- a/docs/docsite/rst/network/getting_started/basic_concepts.rst +++ b/docs/docsite/rst/network/getting_started/basic_concepts.rst @@ -19,19 +19,19 @@ The network devices (and/or servers) you manage with Ansible. Managed nodes are 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. +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 :ref:`the Working with Inventory` section. 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 :ref:`list of network 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 :ref:`list of all modules ` or the :ref:`list of network modules`. Tasks ================================================================================ -The units of action in Ansible. You can execute a single task once with an ad-hoc command. +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`. +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 :ref:`about_playbooks`. diff --git a/docs/docsite/rst/network/getting_started/first_inventory.rst b/docs/docsite/rst/network/getting_started/first_inventory.rst index 5196b319d17..a963baa47e6 100644 --- a/docs/docsite/rst/network/getting_started/first_inventory.rst +++ b/docs/docsite/rst/network/getting_started/first_inventory.rst @@ -45,7 +45,7 @@ This tiny example data center illustrates a basic group structure. You can group 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. +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:: ini @@ -109,12 +109,12 @@ When devices in a group share the same variable values, such as OS or SSH user, 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. +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 ini-style inventory file you **must** use the syntax ``key=value`` for variable values: ``ansible_network_os=vyos``. +- In an ini-style 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 ``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`` @@ -155,14 +155,14 @@ As your inventory grows, you may want to group devices by platform. This allows With this setup, you can run first_playbook.yml with only two flags: -.. code-block:: console +.. code-block:: console 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``. +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`` +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. @@ -187,7 +187,7 @@ If you prefer to type your ansible-vault password rather than store it in a file ansible-vault encrypt_string --vault-id my_user@prompt 'VyOS_SSH_password' --name 'ansible_password' -and type in the vault password for ``my_user``. +and type in the vault password for ``my_user``. The :option:`--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``: @@ -238,7 +238,7 @@ Or with a prompt instead of the vault password file: 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. +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 @@ -253,9 +253,9 @@ To see the original value, you can use the debug module. Please note if your YAM .. 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>`. +For more details on building inventory files, see :ref:`the introduction to inventory`; for more details on ansible-vault, see :ref:`the full Ansible Vault documentation`. -Now that you understand the basics of commands, playbooks, and inventory, it's time to explore some more complex Ansible Network examples. +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 index 2a48a230404..ba9d6520e77 100644 --- a/docs/docsite/rst/network/getting_started/first_playbook.rst +++ b/docs/docsite/rst/network/getting_started/first_playbook.rst @@ -22,7 +22,7 @@ Before you work through this tutorial you need: Install Ansible ================================================== -Install Ansible using your preferred method. See :doc:`../../installation_guide/intro_installation`. Then return to this tutorial. +Install Ansible using your preferred method. See :ref:`installation_guide`. Then return to this tutorial. Confirm the version of Ansible (must be >= 2.5): diff --git a/docs/docsite/rst/plugins/become.rst b/docs/docsite/rst/plugins/become.rst index f671d24d157..7bc181d06e4 100644 --- a/docs/docsite/rst/plugins/become.rst +++ b/docs/docsite/rst/plugins/become.rst @@ -54,17 +54,17 @@ Use ``ansible-doc -t become `` to see specific documentation and ex .. seealso:: - :doc:`../user_guide/playbooks` + :ref:`about_playbooks` An introduction to playbooks - :doc:`inventory` + :ref:`inventory_plugins` Ansible inventory plugins - :doc:`callback` + :ref:`callback_plugins` Ansible callback plugins - :doc:`../user_guide/playbooks_filters` + :ref:`playbooks_filters` Jinja2 filter plugins - :doc:`../user_guide/playbooks_tests` + :ref:`playbooks_tests` Jinja2 test plugins - :doc:`../user_guide/playbooks_lookups` + :ref:`playbooks_lookups` Jinja2 lookup plugins `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.5.rst b/docs/docsite/rst/porting_guides/porting_guide_2.5.rst index b1b01defb09..74cc2521568 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.5.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.5.rst @@ -274,7 +274,7 @@ other non-iterable types returned by a plugin were accepted without error or war Lookup ------- -A new option was added to lookup plugins globally named ``error`` which allows you to control how errors produced by the lookup are handled, before this option they were always fatal. Valid values for this option are ``warn``, ``ignore`` and ``strict``. See the :doc:`lookup <../plugins/lookup>` page for more details. +A new option was added to lookup plugins globally named ``error`` which allows you to control how errors produced by the lookup are handled, before this option they were always fatal. Valid values for this option are ``warn``, ``ignore`` and ``strict``. See the :ref:`lookup ` page for more details. Porting custom scripts diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index 7a4c91bae0e..99848ef2b08 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -280,7 +280,7 @@ Where does the configuration file live and what can I configure in it? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -See :doc:`../installation_guide/intro_configuration`. +See :ref:`intro_configuration`. .. _who_would_ever_want_to_disable_cowsay_but_ok_here_is_how: @@ -397,7 +397,7 @@ How do I access a variable of the first host in a group? What happens if we want the ip address of the first webserver in the webservers group? Well, we can do that too. Note that if we are using dynamic inventory, which host is the 'first' may not be consistent, so you wouldn't want to do this unless your inventory -is static and predictable. (If you are using :doc:`../reference_appendices/tower`, it will use database order, so this isn't a problem even if you are using cloud +is static and predictable. (If you are using :ref:`ansible_tower`, it will use database order, so this isn't a problem even if you are using cloud based inventory scripts). Anyway, here's the trick: @@ -479,7 +479,7 @@ Once the library is ready, SHA512 password values can then be generated as follo python -c "from passlib.hash import sha512_crypt; import getpass; print(sha512_crypt.using(rounds=5000).hash(getpass.getpass()))" Use the integrated :ref:`hash_filters` to generate a hashed version of a password. -You shouldn't put plaintext passwords in your playbook or host_vars; instead, use :doc:`../user_guide/playbooks_vault` to encrypt sensitive data. +You shouldn't put plaintext passwords in your playbook or host_vars; instead, use :ref:`playbooks_vault` to encrypt sensitive data. In OpenBSD, a similar option is available in the base system called encrypt(1): @@ -559,7 +559,7 @@ We also offer free web-based training classes on a regular basis. See our `webin Is there a web interface / REST API / etc? ++++++++++++++++++++++++++++++++++++++++++ -Yes! Ansible, Inc makes a great product that makes Ansible even more powerful and easy to use. See :doc:`../reference_appendices/tower`. +Yes! Ansible, Inc makes a great product that makes Ansible even more powerful and easy to use. See :ref:`ansible_tower`. .. _docs_contributions: @@ -575,7 +575,7 @@ Great question! Documentation for Ansible is kept in the main project git repos How do I keep secret data in my playbook? +++++++++++++++++++++++++++++++++++++++++ -If you would like to keep secret data in your Ansible content and still share it publicly or keep things in source control, see :doc:`../user_guide/playbooks_vault`. +If you would like to keep secret data in your Ansible content and still share it publicly or keep things in source control, see :ref:`playbooks_vault`. If you have a task that you don't want to show the results or command given to it when using -v (verbose) mode, the following task or playbook attribute can be useful:: @@ -685,9 +685,9 @@ Please see the section below for a link to IRC and the Google Group, where you c .. seealso:: - :doc:`../user_guide/playbooks` + :ref:`working_with_playbooks` An introduction to playbooks - :doc:`../user_guide/playbooks_best_practices` + :ref:`playbooks_best_practices` Best practices advice `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/scenario_guides/guide_alicloud.rst b/docs/docsite/rst/scenario_guides/guide_alicloud.rst index af4e45c8551..c91eaf7f325 100644 --- a/docs/docsite/rst/scenario_guides/guide_alicloud.rst +++ b/docs/docsite/rst/scenario_guides/guide_alicloud.rst @@ -26,7 +26,7 @@ Normally, you'll use the following pattern for plays that provision Alicloud res Authentication `````````````` - + You can specify your Alicloud authentication credentials (access key and secret key) by passing them as environment variables or by storing them in a vars file. @@ -35,7 +35,7 @@ To pass authentication credentials as environment variables:: export ALICLOUD_ACCESS_KEY='Alicloud123' export ALICLOUD_SECRET_KEY='AlicloudSecret123' -To store authentication credentials in a vars_file, encrypt them with :doc:`Ansible Vault<../user_guide/vault>` to keep them secure, then list them:: +To store authentication credentials in a vars_file, encrypt them with :ref:`Ansible Vault` to keep them secure, then list them:: --- alicloud_access_key: "--REMOVED--"