From 5bf1b7063bac214ba668dcc443cec0cd246a1cba Mon Sep 17 00:00:00 2001 From: omnom62 Date: Fri, 19 Jun 2026 21:31:29 +1000 Subject: T8989: vyos_l3_interfaces doc --- docs/vyos.rest.vyos_l3_interfaces_module.rst | 494 +++++++++++++++++++++++++++ 1 file changed, 494 insertions(+) create mode 100644 docs/vyos.rest.vyos_l3_interfaces_module.rst (limited to 'docs') diff --git a/docs/vyos.rest.vyos_l3_interfaces_module.rst b/docs/vyos.rest.vyos_l3_interfaces_module.rst new file mode 100644 index 0000000..d251abb --- /dev/null +++ b/docs/vyos.rest.vyos_l3_interfaces_module.rst @@ -0,0 +1,494 @@ +.. _vyos.rest.vyos_l3_interfaces_module: + + +**************************** +vyos.rest.vyos_l3_interfaces +**************************** + +**Manage L3 interface configuration on VyOS devices via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages IPv4 and IPv6 address configuration on VyOS interfaces using the HTTPS REST API. +- Mirrors ``vyos.vyos.vyos_l3_interfaces`` but uses the HTTP API instead of CLI. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ config + +
+ list + / elements=dictionary +
+ 		+ +
List of L3 interface configurations.
+
+
+ ipv4 + +
+ list + / elements=dictionary +
+ 		+ +
List of IPv4 addresses of the interface.
+
+
+ address + +
+ string +
+ 		+ +
IPv4 address in CIDR notation or dhcp.
+
+
+ ipv6 + +
+ list + / elements=dictionary +
+ 		+ +
List of IPv6 addresses of the interface.
+
+
+ address + +
+ string +
+ 		+ +
IPv6 address in CIDR notation, dhcpv6, or auto-config.
+
+
+ name + +
+ string + / required +
+ 		+ +
Full name of the interface, e.g. eth0, lo.
+
+
+ vifs + +
+ list + / elements=dictionary +
+ 		+ +
List of virtual sub-interfaces (VLANs).
+
+
+ ipv4 + +
+ list + / elements=dictionary +
+ 		+ +
List of IPv4 addresses of the VIF.
+
+
+ address + +
+ string +
+ 		+ +
IPv4 address in CIDR notation or dhcp.
+
+
+ ipv6 + +
+ list + / elements=dictionary +
+ 		+ +
List of IPv6 addresses of the VIF.
+
+
+ address + +
+ string +
+ 		+ +
IPv6 address in CIDR notation, dhcpv6, or auto-config.
+
+
+ vlan_id + +
+ integer + / required +
+ 		+ +
VLAN identifier.
+
+
+ running_config + +
+ string +
+ 		+ +
Used only with state parsed.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
  • rendered
    • +
  • parsed
    • +
+ 		+
merged - Add addresses without removing existing ones.
+
replaced - Replace addresses for listed interfaces.
+
overridden - Replace addresses for all interfaces.
+
deleted - Remove listed or all interface addresses.
+
gathered - Read interface addresses from device without changes.
+
rendered - Return commands for provided config without connecting.
+
parsed - Parse running_config into structured data.
+
+
+ + + +See Also +-------- + +.. seealso:: + + :ref:`vyos.vyos.vyos_l3_interfaces_module` + The official documentation on the **vyos.vyos.vyos_l3_interfaces** module. + :ref:`vyos.rest.vyos_interfaces_module` + The official documentation on the **vyos.rest.vyos_interfaces** module. + + +Examples +-------- + +.. code-block:: yaml + + - name: Merge L3 interface configuration + vyos.rest.vyos_l3_interfaces: + config: + - name: eth0 + ipv4: + - address: 192.0.2.1/24 + - address: dhcp + - name: lo + ipv4: + - address: 10.0.0.1/32 + ipv6: + - address: 2001:db8::1/128 + state: merged + + - name: Add VLAN subinterface addresses + vyos.rest.vyos_l3_interfaces: + config: + - name: eth0 + vifs: + - vlan_id: 100 + ipv4: + - address: 192.0.2.100/24 + state: merged + + - name: Delete all interface addresses + vyos.rest.vyos_l3_interfaces: + state: deleted + + - name: Gather current L3 interface configuration + vyos.rest.vyos_l3_interfaces: + state: gathered + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ list +
+ 		when changed +
L3 interface configuration after this module ran.
+
+
+
+ before + +
+ list +
+ 		always +
L3 interface configuration before this module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
List of API command tuples sent to the device.
+
+
+
+ gathered + +
+ list +
+ 		when state is gathered +
Current L3 interface configuration as structured data.
+
+
+
+ parsed + +
+ list +
+ 		when state is parsed +
Structured data parsed from running_config (state=parsed).
+
+
+
+ rendered + +
+ list +
+ 		when state is rendered +
Commands for the provided config (state=rendered).
+
+
+
+ response + +
+ dictionary +
+ 		when changes are applied +
Raw API response.
+
+
+
+ saved + +
+ boolean +
+ 		when changes are applied +
Whether the config was saved after changes.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) -- cgit v1.2.3