From 4662d6d03742ecc2fd09c530cf4b70217975e5bb Mon Sep 17 00:00:00 2001 From: GomathiselviS Date: Thu, 17 Feb 2022 10:10:20 -0500 Subject: Add Vyos hostname resource module (#237) Add Vyos hostname resource module SUMMARY ISSUE TYPE New Module Pull Request COMPONENT NAME ADDITIONAL INFORMATION Reviewed-by: Nilashish Chakraborty Reviewed-by: None --- docs/vyos.vyos.vyos_hostname_module.rst | 386 ++++++++++++++++++++++++++++++++ 1 file changed, 386 insertions(+) create mode 100644 docs/vyos.vyos.vyos_hostname_module.rst (limited to 'docs') diff --git a/docs/vyos.vyos.vyos_hostname_module.rst b/docs/vyos.vyos.vyos_hostname_module.rst new file mode 100644 index 00000000..569017ab --- /dev/null +++ b/docs/vyos.vyos.vyos_hostname_module.rst @@ -0,0 +1,386 @@ +.. _vyos.vyos.vyos_hostname_module: + + +*********************** +vyos.vyos.vyos_hostname +*********************** + +**Manages hostname resource module** + + +Version added: 2.8.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- This module manages the hostname attribute of Vyos network devices + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ config + +
+ dictionary +
+ 		+ +
Hostname configuration.
+
+
+ hostname + +
+ string +
+ 		+ +
set hostname for VYOS.
+
+
+ running_config + +
+ string +
+ 		+ +
This option is used only with state parsed.
+
The value of this option should be the output received from the vyos device by executing the command "show configuration commands | grep host-name".
+
The state parsed reads the configuration from running_config option and transforms it into Ansible structured data as per the resource module's argspec and the value is then returned in the parsed key within the result.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
  • parsed
    • +
  • rendered
    • +
+ 		+
The state the configuration should be left in
+
The states rendered, gathered and parsed does not perform any change on the device.
+
The state rendered will transform the configuration in config option to platform specific CLI commands which will be returned in the rendered key within the result. For state rendered active connection to remote host is not required.
+
The states merged, replaced and overridden have identical behaviour for this module.
+
The state gathered will fetch the running configuration from device and transform it into structured data in the format as per the resource module argspec and the value is returned in the gathered key within the result.
+
The state parsed reads the configuration from running_config option and transforms it into JSON format as per the resource module parameters and the value is returned in the parsed key within the result. The value of running_config option should be the same format as the output of command show configuration commands | grep host-name executed on device. For state parsed active connection to remote host is not required.
+
+
+ + +Notes +----- + +.. note:: + - Tested against vyos 1.1.8 + - This module works with connection ``network_cli``. + - The Configuration defaults of the Vyos network devices are supposed to hinder idempotent behavior of plays + + + +Examples +-------- + +.. code-block:: yaml + + # Using state: merged + # Before state: + # ------------- + # test#show configuration commands | grep host-name + # set system host-name 'vyostest' + # Merged play: + # ------------ + - name: Apply the provided configuration + vyos.vyos.vyos_hostname: + config: + hostname: vyos + state: merged + # Commands Fired: + # --------------- + # "commands": [ + # "hostname vyos", + # ], + # After state: + # ------------ + # test#show configuration commands | grep host-name + # set system host-name 'vyos' + + # Using state: deleted + # Before state: + # ------------- + # test#show configuration commands | grep host-name + # set system host-name 'vyos' + # Deleted play: + # ------------- + - name: Remove all existing configuration + vyos.vyos.vyos_hostname: + state: deleted + # Commands Fired: + # --------------- + # "commands": [ + # "no hostname vyosTest", + # ], + # After state: + # ------------ + # test#show configuration commands | grep host-name + + # Using state: overridden + # Before state: + # ------------- + # test#show configuration commands | grep host-name + # set system host-name 'vyos' + # Overridden play: + # ---------------- + - name: Override commands with provided configuration + vyos.vyos.vyos_hostname: + config: + hostname: vyosTest + state: overridden + # Commands Fired: + # --------------- + # "commands": [ + # "hostname vyosTest", + # ], + # After state: + # ------------ + # test#show configuration commands | grep host-name + # set system host-name 'vyosTest' + + # Using state: replaced + # Before state: + # ------------- + # test#show configuration commands | grep host-name + # set system host-name 'vyosTest' + # Replaced play: + # -------------- + - name: Replace commands with provided configuration + vyos.vyos.vyos_hostname: + config: + hostname: vyos + state: replaced + # After state: + # ------------ + # test#show configuration commands | grep host-name + # set system host-name 'vyos' + + # Using state: gathered + # Before state: + # ------------- + #test#show configuration commands | grep host-name + # set system host-name 'vyos' + # Gathered play: + # -------------- + - name: Gather listed hostname config + vyos.vyos.vyos_hostname: + state: gathered + # Module Execution Result: + # ------------------------ + # "gathered": { + # "hostname": "vyos" + # }, + + # Using state: rendered + # Rendered play: + # -------------- + - name: Render the commands for provided configuration + vyos.vyos.vyos_hostname: + config: + hostname: vyosTest + state: rendered + # Module Execution Result: + # ------------------------ + # "rendered": [ + # "set system host-name vyosTest", + # ] + + # Using state: parsed + # File: parsed.cfg + # ---------------- + # set system host-name 'vyos' + # Parsed play: + # ------------ + - name: Parse the provided configuration with the existing running configuration + vyos.vyos.vyos_hostname: + running_config: "{{ lookup('file', 'parsed.cfg') }}" + state: parsed + # Module Execution Result: + # ------------------------ + # "parsed": { + # "hostname": "vyos" + # } + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ dictionary +
+ 		when changed +
The resulting configuration after module execution.
+
+
Sample:
+
This output will always be in the same format as the module argspec.
+
+
+ before + +
+ dictionary +
+ 		when state is merged, replaced, overridden, deleted or purged +
The configuration prior to the module execution.
+
+
Sample:
+
This output will always be in the same format as the module argspec.
+
+
+ commands + +
+ list +
+ 		when state is merged, replaced, overridden, deleted or purged +
The set of commands pushed to the remote device.
+
+
Sample:
+
['sample command 1', 'sample command 2', 'sample command 3']
+
+
+ gathered + +
+ list +
+ 		when state is gathered +
Facts about the network resource gathered from the remote device as structured data.
+
+
Sample:
+
This output will always be in the same format as the module argspec.
+
+
+ parsed + +
+ list +
+ 		when state is parsed +
The device native config provided in running_config option parsed into structured data as per module argspec.
+
+
Sample:
+
This output will always be in the same format as the module argspec.
+
+
+ rendered + +
+ list +
+ 		when state is rendered +
The provided configuration in the task rendered in device-native format (offline).
+
+
Sample:
+
['sample command 1', 'sample command 2', 'sample command 3']
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- Gomathi Selvi Srinivasan (@GomathiselviS) -- cgit v1.2.3