New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add network roles info #49501

Open
wants to merge 1 commit into
base: devel
from

Conversation

3 participants
@samccann
Contributor

samccann commented Dec 4, 2018

SUMMARY

Ansible network documentation doesn't mention anything about the supported roles being developed in Galaxy. Created a short page to highlight their existence and how to find them etc.

ISSUE TYPE
  • Docs Pull Request
COMPONENT NAME

docs.ansible.com

ADDITIONAL INFORMATION

@samccann samccann added this to Docsite work in Network Documentation via automation Dec 4, 2018

@ansibot

This comment has been minimized.

Contributor

ansibot commented Dec 4, 2018

@acozine

Thanks @samccann, this is a great improvement. I made some comments to help make it even better.

These roles come in the following categories:
* **User roles** - You use these roles, such as `config_manager <https://galaxy.ansible.com/ansible-network/config_manager>`_ and `cloud_vpn <https://galaxy.ansible.com/ansible-network/cloud_vpn>`_, directly in your playbooks. These roles are platform/provider agnostic, allowing you to use the same roles and playbooks across different network platforms or cloud providers.

This comment has been minimized.

@acozine

acozine Dec 4, 2018

Contributor

I'd add a sentence at the beginning here to describe what user roles do - something like "User roles focus on tasks, such as managing configuration or ????." Then add the part about using these roles directly in playbooks. I'd also add an example (either here, or elsewhere with a link from here).

.. tip::
You need to install at least one platform provider role for your network user roles, and set ``ansible_network_provider`` to that provider (for example, ``ansible_network_provider: ansible-network.cisco_ios``). Galaxy automatically installs any other dependencies listed in the role details on Galaxy.

This comment has been minimized.

@acozine

acozine Dec 4, 2018

Contributor

Instead of a tip, I'd put an example/illustration here, to make this section more immediately useful. How do I install roles? How do I know which roles are "platform provider" roles? How do I check if I already have a role installed? Is there a naming convention?

This comment has been minimized.

@samccann

samccann Dec 5, 2018

Contributor

This is where I don't want to repeat what is already in the Galaxy documentation. I'm trying to focus just on 'hey we have roles...go see'. ...with a couple of gotchas I hit along the way like the network provider bit.

These roles come in the following categories:
* **User roles** - You use these roles, such as `config_manager <https://galaxy.ansible.com/ansible-network/config_manager>`_ and `cloud_vpn <https://galaxy.ansible.com/ansible-network/cloud_vpn>`_, directly in your playbooks. These roles are platform/provider agnostic, allowing you to use the same roles and playbooks across different network platforms or cloud providers.
* **Platform provider roles** - Network user roles depend on these provider roles to implement their functions. For example, the `config_manager <https://galaxy.ansible.com/ansible-network/config_manager>`_ role uses the `cisco_ios <https://galaxy.ansible.com/ansible-network/cisco_ios>`_ provider role to implement tasks on Cisco IOS network devices.

This comment has been minimized.

@acozine

acozine Dec 4, 2018

Contributor

I'd describe this in a more provider-role-centric way. Maybe something like "Provider roles translate between the user roles and the various network OSs, each of which has a different API. Each provider role accepts input from any user role and translates it for a specific network OS. For example, the cisco_ios provider role implements tasks on Cisco IOS network devices." Because that provider role accepts input from any user role, right? not just from config_manager.

This comment has been minimized.

@samccann

samccann Dec 5, 2018

Contributor

afaik the provider roles only support the user roles they are written to support. For example, cisco_ios provider role supports both config_manager and cloud_vpn, but cisco_iosxr doesn't support either. But I like the rest of your suggestion, and I'll change 'any user role' to supported user roles.

- 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)

This comment has been minimized.

@acozine

acozine Dec 4, 2018

Contributor

Sentence case?

Network roles release cycle
===========================
The Ansible network team releases updates and new roles every two weeks. The role details on Galaxy lists the role versions available, and you can look in the GitHub repository to find the changelog file (for example, `CHANGELOG.rst <https://github.com/ansible-network/cisco_ios/blob/devel/CHANGELOG.rst>`_ ) that lists what has changed in each version of the role.

This comment has been minimized.

@acozine

acozine Dec 4, 2018

Contributor

How do I update the role(s) I installed last month to get the latest version?

- `Recorded AnsibleAutomates <https://www.ansible.com/resources/webinars-training>`_
- `Upcoming Ansible Events <https://www.ansible.com/community/events>`_ page.
GitHub Repos

This comment has been minimized.

@acozine

acozine Dec 4, 2018

Contributor

Sentence case? (I know, I'm making you fix my mistakes . . .).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment