Skip to content

Commit

Permalink
T6987: update vyos_logging_global for 1.4+ (#370)
Browse files Browse the repository at this point in the history
* T68987: update for 1.4+
* chore: remove redundant vars
* tests: fix vyos_facts integration tests
* tests: fix integration tests for vyos_config
* fix: restore documentation samples
* chore: update readme
  • Loading branch information
gaige authored Jan 4, 2025
1 parent 9e15999 commit c14a524
Show file tree
Hide file tree
Showing 19 changed files with 337 additions and 159 deletions.
51 changes: 33 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,21 @@

# VyOS Collection

[![Codecov](https://codecov.io/gh/ansible-collections/vyos.vyos/branch/main/graph/badge.svg)](https://codecov.io/gh/ansible-collections/vyos.vyos)
[![CI](https://github.com/ansible-collections/vyos.vyos/actions/workflows/tests.yml/badge.svg?branch=main&event=schedule)](https://github.com/ansible-collections/vyos.vyos/actions/workflows/tests.yml)
[![Codecov](https://codecov.io/gh/vyos/vyos.vyos/branch/main/graph/badge.svg)](https://codecov.io/gh/ansible-collections/vyos.vyos)
[![CI](https://github.com/vyos/vyos.vyos/actions/workflows/tests.yml/badge.svg?branch=main&event=schedule)](https://github.com/vyos/vyos.vyos/actions/workflows/tests.yml)

The Ansible VyOS collection includes a variety of Ansible content to help automate the management of VyOS network appliances.

This collection has been tested against VyOS 1.1.8 (helium).
This collection has been tested against VyOS 1.3.8, 1.4.1 and the current rolling release for 1.5. Where possible,
compatibility with older versions of VyOS are maintained but not guaranteed.

## Communication

* Join the Ansible forum:
* [Get Help](https://forum.ansible.com/c/help/6): get help or help others.
* [Posts tagged with 'vyos'](https://forum.ansible.com/tag/vyos): subscribe to participate in collection-related conversations.
* [Social Spaces](https://forum.ansible.com/c/chat/4): gather and interact with fellow enthusiasts.
* [News & Announcements](https://forum.ansible.com/c/news/5): track project-wide announcements including social events.
* Join the VyOS forum:
* [FAQ](https://forum.vyos.io/faq): find answers to frequently asked questions.
* [Guides and How To](https://forum.vyos.io/c/howto-guies/27): find guides and how-to articles.
* [News & Announcements](https://forum.vyos.io/c/announcements/6): track project-wide announcements .

* The Ansible [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn): used to announce releases and important changes.

For more information about communication, see the [Ansible communication guide](https://docs.ansible.com/ansible/devel/community/communication.html).

<!--start requires_ansible-->
## Ansible version compatibility
Expand Down Expand Up @@ -141,14 +138,13 @@ The following example task replaces configuration changes in the existing config

## Contributing to this collection

We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the [VyOS collection repository](https://github.com/ansible-collections/vyos). See [Contributing to Ansible-maintained collections](https://docs.ansible.com/ansible/devel/community/contributing_maintained_collections.html#contributing-maintained-collections) for complete details.
We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the [VyOS collection repository](https://github.com/vyos/vyos.vyos). See [Contributing to VyOS](https://vyos.net/contribute/) for complete details.

You can also join us on:

- IRC - the ``#ansible-network`` [irc.libera.chat](https://libera.chat/) channel
- Slack - https://ansiblenetwork.slack.com
- Forum - https://forum.vyos.io

See the [Ansible Community Guide](https://docs.ansible.com/ansible/latest/community/index.html) for details on contributing to Ansible.
See the [Contributing to VyOS](https://vyos.net/contribute/) for details on contributing to Ansible.

### Code of Conduct
This collection follows the Ansible project's
Expand Down Expand Up @@ -197,8 +193,6 @@ ansible-playbook -e rm_dest=`pwd` \

Unlike the `resource_module_builder`, the `cli_rm_builder` does not require the `model` parameter. Instead, it uses the `resource` parameter to specify the resource to build.



### Testing playbooks

You can use `ANSIBLE_COLLECTIONS_PATH` to test the collection locally. For example:
Expand All @@ -211,14 +205,35 @@ ANSIBLE_COLLECTIONS_PATHS=~/my_dev_path ansible-playbook -i inventory.network te

## Release notes

Release notes are available [here](https://github.com/ansible-collections/vyos.vyos/blob/main/CHANGELOG.rst).
Release notes are available [here](https://github.com/vyos/vyos.vyos/blob/main/CHANGELOG.rst).

## Roadmap

<!-- Optional. Include the roadmap for this collection, and the proposed release/versioning strategy so users can anticipate the upgrade/update cycle. -->

Major Version | Ansible Support | VyOS Support | Details
--- | --- | --- | ---
4.1.0 | 2.15 | 1.1.2 | Final release for the 4.x series
5.0.0 | 2.16 | 1.1.2 | First relase under VyOS control as a separate collection
6.0.0 | 2.18 | 1.3.8 | *Planned* release for supporting VyOS 1.3.8+
7.0.0 | x.xx | 1.4.x | *Prospective* release deprecating incompatible 1.3.x modules

Note:
- Unreleased versions are not guaranteed to be released as described.
- Some modules may support a wider variety of versions depending upon the compatibility
with prior versions of VyOS.
- The roadmap is subject to change based on community feedback and contributions.


## More information

VyOS resources
- [Contributing to VyOS](https://vyos.net/contribute)
- [VyOS documentation](https://docs.vyos.io/en/latest/)
- [VyOS forum](https://forum.vyos.io)


Ansible Resources
- [Ansible network resources](https://docs.ansible.com/ansible/latest/network/getting_started/network_resources.html)
- [Ansible Collection overview](https://github.com/ansible-collections/overview)
- [Ansible User guide](https://docs.ansible.com/ansible/latest/user_guide/index.html)
Expand Down
15 changes: 15 additions & 0 deletions changelogs/fragments/T6987-logging-changes.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
minor_changes:
- deprecating items for 1.4+ that have moved locations
- For 1.4, `protocol` is an attribute of the syslog host, not the facility
- Fixed v1.3 and before when `protocol` and `level` were set for the same host
- Fixed integration test for `vyos_facts` which was brittle due to line dependencies in checks
- Fixed integration test for `vyos_config` due to bad commands. 1.3 frequently won't finish due
to timeouts or system failures during the tests, but 1.4 and 1.5

breaking_changes:
- none yet

known_issues:
- existing code for 1.3 facility protocol and facility level are not compatible,
only one will be set and level is the priority.
27 changes: 24 additions & 3 deletions docs/vyos.vyos.vyos_logging_global_module.rst
Original file line number Diff line number Diff line change
Expand Up @@ -719,7 +719,7 @@ Parameters
</ul>
</td>
<td>
<div>syslog communication protocol</div>
<div>syslog communication protocol. Version 1.3 and below.</div>
</td>
</tr>
<tr>
Expand Down Expand Up @@ -786,6 +786,27 @@ Parameters
<div>Destination port (1-65535)</div>
</td>
</tr>
<tr>
<td class="elbow-placeholder"></td>
<td class="elbow-placeholder"></td>
<td colspan="2">
<div class="ansibleOptionAnchor" id="parameter-"></div>
<b>protocol</b>
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">string</span>
</div>
</td>
<td>
<ul style="margin: 0; padding: 0"><b>Choices:</b>
<li>udp</li>
<li>tcp</li>
</ul>
</td>
<td>
<div>syslog communication protocol. Version 1.4+</div>
</td>
</tr>

<tr>
<td class="elbow-placeholder"></td>
Expand Down Expand Up @@ -1003,7 +1024,7 @@ Notes
-----

.. note::
- Tested against vyos 1.2
- Tested against vyos 1.3.8+
- This module works with connection ``network_cli``.
- The Configuration defaults of the Vyos network devices are supposed to hinder idempotent behavior of plays

Expand Down Expand Up @@ -1632,7 +1653,7 @@ Common return values are documented `here <https://docs.ansible.com/ansible/late
<div>The provided configuration in the task rendered in device-native format (offline).</div>
<br/>
<div style="font-size: smaller"><b>Sample:</b></div>
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">[&#x27;set system syslog host 172.16.0.1 port 223&#x27;, &#x27;set system syslog user vyos facility local7 level debug&#x27;, &#x27;set system syslog global facility cron level debug&#x27;]</div>
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">[&#x27;set system syslog host 172.16.0.1 port 223&#x27;, &#x27;set system syslog user vyos facility local7 level debug&#x27;, &#x27;set system syslog global facility cron level debu&#x27;]</div>
</td>
</tr>
</table>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,8 @@ class Logging_globalArgs(object): # pylint: disable=R0903
"file_num": {"type": "int"},
"size": {"type": "int"},
},
"removed_in_version": "7.0.0",
"removed_from_collection": "vyos.vyos",
},
"facilities": {
"type": "list",
Expand Down Expand Up @@ -282,10 +284,16 @@ class Logging_globalArgs(object): # pylint: disable=R0903
"protocol": {
"type": "str",
"choices": ["udp", "tcp"],
"removed_in_version": "7.0.0",
"removed_from_collection": "vyos.vyos",
},
},
},
"hostname": {"type": "str"},
"protocol": {
"type": "str",
"choices": ["udp", "tcp"],
},
},
},
"syslog": {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,8 @@ def __init__(self, module):
"files.archive.file_num",
"files",
"hosts.port",
"hosts.facility.protocol", # 1.3 and below
"hosts.protocol",
"hosts",
"users",
]
Expand Down
56 changes: 52 additions & 4 deletions plugins/module_utils/network/vyos/rm_templates/logging_global.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ def templt_common(val, tmplt):
tmplt += " facility {facility}".format(facility=val["facility"])
if val.get("severity"):
tmplt += " level {level}".format(level=val["severity"])
if val.get("protocol"):
elif val.get("protocol"):
tmplt += " protocol {protocol}".format(protocol=val["protocol"])
return tmplt

Expand All @@ -50,7 +50,12 @@ def templt_common(val, tmplt):
tmplt = templt_common(val.get("facilities"), tmplt)
elif config_data.get("hosts"):
val = config_data.get("hosts")
if val.get("hostname") and not val.get("archive") and not val.get("port"):
if (
val.get("hostname")
and not val.get("archive")
and not val.get("port")
and not val.get("protocol")
):
tmplt += "system syslog host {hostname}".format(hostname=val["hostname"])
if val.get("facilities"):
tmplt = templt_common(val.get("facilities"), tmplt)
Expand Down Expand Up @@ -351,6 +356,51 @@ def __init__(self, lines=None, module=None):
},
},
},
{
"name": "hosts.protocol",
"getval": re.compile(
r"""
^set\ssystem\ssyslog\shost
(\s(?P<hostname>\S+))
(\sprotocol\s(?P<protocol>'(udp|tcp)'))
$""", re.VERBOSE,
),
"setval": "system syslog host {{ hosts.hostname }} protocol {{ hosts.protocol }}",
"result": {
"hosts": {
"{{ hostname }}": {
"hostname": "{{ hostname }}",
"protocol": "{{ protocol }}",
},
},
},
},
{
# Version 1.3 and below
"name": "hosts.facility.protocol",
"getval": re.compile(
r"""
^set\ssystem\ssyslog\shost
(\s(?P<hostname>\S+))
(\sfacility\s(?P<facility>all|auth|authpriv|cron|daemon|kern|lpr|mail|mark|news|protocols|security|syslog|user|uucp|local[0-7]))
(\sprotocol\s(?P<protocol>'(udp|tcp)'))
$""", re.VERBOSE,
),
"setval": "system syslog host {{ hosts.hostname }} facility {{ hosts.facility }} protocol {{ hosts.protocol }}",
"remval": "system syslog host {{ hosts.hostname }} facility {{ hosts.facility }} protocol {{ hosts.protocol }}",
"result": {
"hosts": {
"{{ hostname }}": {
"hostname": "{{ hostname }}",
"facilities": [
{
"facility": "{{ facility }}",
"protocol": "{{ protocol }}",
}, ],
},
},
},
},
{
"name": "hosts",
"getval": re.compile(
Expand All @@ -359,7 +409,6 @@ def __init__(self, lines=None, module=None):
(\s(?P<hostname>\S+))
(\sfacility\s(?P<facility>all|auth|authpriv|cron|daemon|kern|lpr|mail|mark|news|protocols|security|syslog|user|uucp|local[0-7]))
(\slevel\s(?P<level>'(emerg|alert|crit|err|warning|notice|info|debug|all)'))?
(\sprotocol\s(?P<protocol>'(udp|tcp)'))?
$""", re.VERBOSE,
),
"setval": tmplt_params,
Expand All @@ -372,7 +421,6 @@ def __init__(self, lines=None, module=None):
{
"facility": "{{ facility }}",
"severity": "{{ level }}",
"protocol": "{{ protocol }}",
}, ],
},
},
Expand Down
22 changes: 14 additions & 8 deletions plugins/modules/vyos_logging_global.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
description: This module manages the logging attributes of Vyos network devices
author: Sagar Paul (@KB-perByte)
notes:
- Tested against vyos 1.2
- Tested against vyos 1.3.8+
- This module works with connection C(network_cli).
- The Configuration defaults of the Vyos network devices
are supposed to hinder idempotent behavior of plays
Expand Down Expand Up @@ -139,14 +139,20 @@
facility: *facility
severity: *severity
protocol:
description: syslog communication protocol
description: syslog communication protocol. Version 1.3 and below.
type: str
choices:
- udp
- tcp
hostname:
description: Remote host name or IP address
type: str
protocol:
description: syslog communication protocol. Version 1.4+
type: str
choices:
- udp
- tcp
syslog:
description: logging syslog
type: dict
Expand Down Expand Up @@ -715,17 +721,17 @@
returned: when I(state) is C(merged), C(replaced), C(overridden), C(deleted) or C(purged)
type: list
sample:
- "set system syslog console facility local7 level err"
- "set system syslog host 172.16.0.1 port 223"
- "set system syslog global archive size 111"
- set system syslog console facility local7 level err
- set system syslog host 172.16.0.1 port 223
- set system syslog global archive size 111
rendered:
description: The provided configuration in the task rendered in device-native format (offline).
returned: when I(state) is C(rendered)
type: list
sample:
- "set system syslog host 172.16.0.1 port 223"
- "set system syslog user vyos facility local7 level debug"
- "set system syslog global facility cron level debug"
- set system syslog host 172.16.0.1 port 223
- set system syslog user vyos facility local7 level debug
- set system syslog global facility cron level debu
gathered:
description: Facts about the network resource gathered from the remote device as structured data.
returned: when I(state) is C(gathered)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,9 @@
register: result
vyos.vyos.vyos_config:
lines:
- set system login user esa level admin
- set system login user esa full-name 'ESA admin'
- set system login user esa authentication encrypted-password '!abc!'
- set system login user vyos level admin
- set system login user vyos full-name 'VyOS admin'
- set system login user vyos authentication encrypted-password 'abc'

- assert:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,9 @@
register: result
vyos.vyos.config:
lines:
- set system login user esa level admin
- set system login user esa full-name 'ESA admin'
- set system login user esa authentication encrypted-password '!abc!'
- set system login user vyos level admin
- set system login user vyos full-name 'VyOS admin'
- set system login user vyos authentication encrypted-password 'abc'

- assert:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,9 @@
- name: check that version info is present
assert:
that:
- result.ansible_facts.ansible_net_version in vyos_version.stdout_lines[0][0]
- result.ansible_facts.ansible_net_model in vyos_version.stdout_lines[0][9]
- result.ansible_facts.ansible_net_serialnum in vyos_version.stdout_lines[0][10]
- result.ansible_facts.ansible_net_version in (vyos_version.stdout_lines[0] | select('search', 'Version:') | list | first)
- result.ansible_facts.ansible_net_model in (vyos_version.stdout_lines[0] | select('search', 'Hardware model:') | list | first)
- result.ansible_facts.ansible_net_serialnum in (vyos_version.stdout_lines[0] | select('search', 'Hardware S/N:') | list | first)

- name: check that config info is present
assert:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,9 @@
- name: check that version info is present
assert:
that:
- result.ansible_facts.ansible_net_version in vyos_version.stdout_lines[0][0]
- result.ansible_facts.ansible_net_model in vyos_version.stdout_lines[0][9]
- result.ansible_facts.ansible_net_serialnum in vyos_version.stdout_lines[0][10]
- result.ansible_facts.ansible_net_version in (vyos_version.stdout_lines[0] | select('search', 'Version:') | list | first)
- result.ansible_facts.ansible_net_model in (vyos_version.stdout_lines[0] | select('search', 'Hardware model:') | list | first)
- result.ansible_facts.ansible_net_serialnum in (vyos_version.stdout_lines[0] | select('search', 'Hardware S/N:') | list | first)

- name: check that config info is present
assert:
Expand Down
Loading

0 comments on commit c14a524

Please sign in to comment.