diff options
| -rw-r--r-- | changelogs/fragments/T6891-docsite.yaml | 3 | ||||
| -rw-r--r-- | docs/docsite/extra-docs.yml | 5 | ||||
| -rw-r--r-- | docs/docsite/links.yml | 42 | ||||
| -rw-r--r-- | docs/docsite/rst/platform_vyos.rst | 78 |
4 files changed, 128 insertions, 0 deletions
diff --git a/changelogs/fragments/T6891-docsite.yaml b/changelogs/fragments/T6891-docsite.yaml new file mode 100644 index 0000000..7667ac7 --- /dev/null +++ b/changelogs/fragments/T6891-docsite.yaml @@ -0,0 +1,3 @@ +--- +trivial: + - move docsite VyOS platform docs internal diff --git a/docs/docsite/extra-docs.yml b/docs/docsite/extra-docs.yml new file mode 100644 index 0000000..988aff0 --- /dev/null +++ b/docs/docsite/extra-docs.yml @@ -0,0 +1,5 @@ +--- +sections: + - title: Platform VyOS + toctree: + - platform_vyos diff --git a/docs/docsite/links.yml b/docs/docsite/links.yml new file mode 100644 index 0000000..61bea43 --- /dev/null +++ b/docs/docsite/links.yml @@ -0,0 +1,42 @@ +--- +# This will make sure that plugin and module documentation gets Edit on GitHub links +# that allow users to directly create a PR for this plugin or module in GitHub's UI. +# Remove this section if the collection repository is not on GitHub, or if you do not want this +# functionality for your collection. +edit_on_github: + repository: vyos/vyos.vyos + branch: main + # If your collection root (the directory containing galaxy.yml) does not coincide with your + # repository's root, you have to specify the path to the collection root here. For example, + # if the collection root is in a subdirectory ansible_collections/community/REPO_NAME + # in your repository, you have to set path_prefix to 'ansible_collections/community/REPO_NAME'. + path_prefix: "" + +# Here you can add arbitrary extra links. Please keep the number of links down to a +# minimum! Also please keep the description short, since this will be the text put on +# a button. +# +# Also note that some links are automatically added from information in galaxy.yml. +# The following are automatically added: +# 1. A link to the issue tracker (if `issues` is specified); +# 2. A link to the homepage (if `homepage` is specified and does not equal the +# `documentation` or `repository` link); +# 3. A link to the collection's repository (if `repository` is specified). + +extra_links: + - description: Report an issue + url: https://vyos.dev/maniphest/task/edit/form/3/?projectPHIDs=PHID-PROJ-aryfih5l65cgcdmx4sqp + +# Specify communication channels for your collection. We suggest to not specify more +# than one place for communication per communication tool to avoid confusion. +communication: + matrix_rooms: + - topic: General usage and support questions + room: "#users:ansible.im" + # You can also add a `subscribe` field with an URI that allows to subscribe + # to the mailing list. For lists on https://groups.google.com/ a subscribe link is + # automatically generated. + forums: + - topic: Ansible Forum + # The following URL directly points to the "Get Help" section + url: https://forum.ansible.com/c/help/6 diff --git a/docs/docsite/rst/platform_vyos.rst b/docs/docsite/rst/platform_vyos.rst new file mode 100644 index 0000000..6e51e4e --- /dev/null +++ b/docs/docsite/rst/platform_vyos.rst @@ -0,0 +1,78 @@ +.. _vyos_platform_options: + +*************************************** +VyOS Platform Options +*************************************** + +The `VyOS <https://galaxy.ansible.com/ui/repo/published/vyos/vyos>`_ collection supports the ``ansible.netcommon.network_cli`` connection type. +This page offers details on connection options to manage VyOS using Ansible. + +.. contents:: + :local: + +Connections available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol SSH + + Credentials uses SSH keys / SSH-agent if present + + accepts ``-u myuser -k`` if using password + + Indirect Access by a bastion (jump host) + + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` + + |enable_mode| not supported + + Returned Data Format Refer to individual module documentation + ==================== ========================================== + +.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) + + +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead. + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/vyos.yml`` +----------------------------------- + +.. code-block:: yaml + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: vyos.vyos.vyos + ansible_user: myuser + ansible_password: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. + +Example CLI task +---------------- + +.. code-block:: yaml + + - name: Retrieve VyOS version info + vyos.vyos.vyos_command: + commands: show version + when: ansible_network_os == 'vyos.vyos.vyos' + +.. warning:: + Never store passwords in plain text. We recommend using SSH keys to authenticate SSH connections. + Ansible supports ssh-agent to manage your SSH keys. If you must use passwords to authenticate SSH connections, + we recommend encrypting them with :ref:`Ansible Vault <playbooks_vault>`. + +.. seealso:: + + :ref:`timeout_options` |