From 9db83a0117f01e048b5fc08c92aaff0905bd26f7 Mon Sep 17 00:00:00 2001
From: JORGE SASIAIN <jorge.sasiain@ehu.eus>
Date: Wed, 14 Jun 2023 12:08:47 +0000
Subject: [PATCH] Update IPAM README.md
---
gso/services/README.md | 223 +++++++++++++++++++++--------------------
1 file changed, 114 insertions(+), 109 deletions(-)
diff --git a/gso/services/README.md b/gso/services/README.md
index d393e74e..741fa16b 100644
--- a/gso/services/README.md
+++ b/gso/services/README.md
@@ -1,109 +1,114 @@
-## IPAM
-
-### Example configuration
-The following kind of configuration file needs to be exported in the variable OSS_PARAMS_FILENAME:
-
-```
- "LO": {
- "V4": {"containers": [], "networks": ["10.255.255.32/32", "10.255.255.0/28", "10.255.255.16/28"], "mask": 0},
- "V6": {"containers": [], "networks": ["dead:beef::/80", "dead:beef:0:1::/80"], "mask": 0},
- "domain_name": ".gso"
- },
- "TRUNK": {
- "V4": {"containers": ["10.255.255.0/24", "10.255.254.0/24"], "networks": [], "mask": 31},
- "V6": {"containers": ["dead:beef::/64", "dead:beee::/64"], "networks": [], "mask": 126},
- "domain_name": ".gso"
- },
-```
-Either a non-empty list of `networks` or a non-empty list of `containers` is required in the params file per service type. Having both is redundant, but in that case containers take precedence. The `mask` parameter is irrelevant if the service type uses networks instead of containers.
-
-### Host/network allocation
-Hosts can be allocated through `ipam.new_service_host()` resulting in a host record (IPv4, IPv6, A, AAAA) and zero or more cname records. This function can be called by passing domain name, hostname, and service type (mandatory). Optinally, you can pass either ipv4/ipv6 addresses, ipv4/ipv6 networks, or nothing. Passing nothing is considered default. In that case:
-
-- If the service type has any container specified in the params file, networks have to be allocated before allocating hosts (through `ipam.new_service_networks()`). The mask parameter is used to create the new networks. Containers are filled up in the order that they appear in the params file.
-- If the service type has any network specified in the params file, those networks are used directly to allocate hosts. Networks are filled up in the order that they appear in the params file.
-
-If you pass addresses or networks, the module will always attempt to use those, but will fail if they don't match the configuration in the params file for the service type (i.e. if you request an address or network that places outside of the configured containers/networks).
-
-Networks and hosts can be allocated with extensible attributes. Networks can be created with a comment. CNAME records can be optionally created.
-
-### Host/network deletion
-The code checks that the resource you are trying to delete is allocated (in terms of IP address space) to the service as per `containers` or `networks` in the service's configuration. If not, you are not allowed to delete it.
-
-No host or cname records are deleted via the `delete_service_host()` function until all passed arguments match the hostname, IP, and CNAME data of the host. If anything doesn't match, no record is deleted.
-
-### Usage examples
-
-#### Host/network allocation
- The following is a sample call flow to allocate two loopback interfaces and a trunk service. new_service_host() can be called passing networks, addresses, or nothing.
- - Host hA for service TRUNK uses a specific ipv4/ipv6 address pair.
- - Host hB for service TRUNK uses the ipv4/ipv6 network pair.
- - Service LO uses nothing.
-
-```
- hostname_A = 'hA'
- hostname_B = 'hB'
-
- # hA LO (loopback)
- loA_v4_host_address = ipaddress.ip_address('10.255.255.0')
- loA_v6_host_address = ipaddress.ip_address('dead:beef::0')
- loA_host_addresses = HostAddresses(v4=loA_v4_host_address,
- v6=loA_v6_host_address)
- new_service_host(hostname=hostname_A+"_LO",
- host_addresses=loA_host_addresses,
- cname_aliases=["alias1.hA", "alias2.hA"],
- service_type='LO')
-
- # hB LO (loopback)
- new_service_host(hostname=hostname_B+"_LO",
- cname_aliases=["alias1.hB"],
- service_type='LO')
-
- # hA-hB TRUNK
- trunkAB_network_extattrs = {
- "vrf_name": {"value": "dummy_vrf"},
- }
- trunkAB_host_extattrs = {
- "Site": {"value": "dummy_site"},
- }
- trunkAB_service_networks = new_service_networks(
- service_type='TRUNK',
- extattrs=trunkAB_network_extattrs,
- comment="Network for hA-hB TRUNK"
- )
-
- trunkAB_v4_host_address = trunkAB_service_networks.v4.network_address
- trunkAB_v6_host_address = trunkAB_service_networks.v6.network_address
- trunkAB_host_addresses = HostAddresses(v4=trunkAB_v4_host_address,
- v6=trunkAB_v6_host_address)
-
- new_service_host(hostname=hostname_A+"_TRUNK",
- service_type='TRUNK',
- host_addresses=trunkAB_host_addresses,
- extattrs=trunkAB_host_extattrs)
-
- new_service_host(hostname=hostname_B+"_TRUNK",
- service_type='TRUNK',
- service_networks=trunkAB_service_networks,
- extattrs=trunkAB_host_extattrs)
-```
-
-#### Host/network deletion
-```
- # Delete network
- service_network = ipam.delete_service_network(
- network=ipaddress.ip_network('10.255.255.0/26'), service_type='LO'
- )
-
- # Delete host
- input_host_addresses = ipam.HostAddresses(
- v4=ipaddress.ip_address('10.255.255.1'),
- v6=ipaddress.ip_address('dead:beef::1')
- )
- host_addresses = ipam.delete_service_host(
- hostname='ha_lo',
- host_addresses=input_host_addresses,
- cname_aliases=['alias1.ha', 'alias2.ha'],
- service_type='LO'
- )
-```
+## IPAM
+
+### Example configuration
+The following kind of configuration file needs to be exported in the variable `OSS_PARAMS_FILENAME`.
+
+```
+ "LO": {
+ "V4": {"containers": [], "networks": ["10.255.255.32/32", "10.255.255.0/28", "10.255.255.16/28"], "mask": 0},
+ "V6": {"containers": [], "networks": ["dead:beef::/80", "dead:beef:0:1::/80"], "mask": 0},
+ "domain_name": ".gso"
+ },
+ "TRUNK": {
+ "V4": {"containers": ["10.255.255.0/24", "10.255.254.0/24"], "networks": [], "mask": 31},
+ "V6": {"containers": ["dead:beef::/64", "dead:beee::/64"], "networks": [], "mask": 126},
+ "domain_name": ".gso"
+ },
+```
+Either a non-empty list of `networks` or a non-empty list of `containers` is required in the params file per service type. Having both is redundant, but in that case containers take precedence. The `mask` parameter is irrelevant if the service type uses networks instead of containers.
+
+### Host/network allocation
+Hosts can be allocated through `ipam.new_service_host()` resulting in a host record (IPv4, IPv6, A, AAAA) and zero or more cname records. This function can be called by passing domain name, hostname, and service type (mandatory). Optinally, you can pass either ipv4/ipv6 addresses, ipv4/ipv6 networks, or nothing. Passing nothing is considered default. In that case:
+
+- If the service type has any container specified in the params file, networks have to be allocated before allocating hosts (through `ipam.new_service_networks()`). The mask parameter is used to create the new networks. Containers are filled up in the order that they appear in the params file.
+- If the service type has any network specified in the params file, those networks are used directly to allocate hosts. Networks are filled up in the order that they appear in the params file.
+
+If you pass addresses or networks, the module will always attempt to use those, but will fail if they don't match the configuration in the params file for the service type (i.e. if you request an address or network that places outside of the configured containers/networks).
+
+Networks and hosts can be allocated with extensible attributes. Networks can be created with a comment. CNAME records can be optionally created.
+
+### Host/network deletion
+The code checks that the resource you are trying to delete is allocated (in terms of IP address space) to the service as per `containers` or `networks` in the service's configuration. If not, you are not allowed to delete it.
+
+No host or cname records are deleted via the `delete_service_host()` function until all passed arguments match the hostname, IP, and CNAME data of the host. If anything doesn't match, no record is deleted.
+
+### Usage examples
+
+#### Host/network allocation
+ The following is a sample call flow to allocate two loopback interfaces and a trunk service. It assumes the _Example configuration_ from the above section is used, where TRUNK has configured containers, and LO has configured networks.
+
+In this example:
+ - Host hA for service LO uses specific ipv4/ipv6 address pair.
+ - Host hB for service LO uses nothing (just the service type).
+ - Host hA for service TRUNK uses a specific ipv4/ipv6 address pair.
+ - Host hB for service TRUNK uses the ipv4/ipv6 network pair.
+
+ Because TRUNK has configured containers rather than networks, `new_service_networks()` must be called first to create a network for the hA-hB TRUNK. This is not needed for LO, which automatically uses the first configured network with available space to allocate new hosts.
+
+```
+ hostname_A = 'hA'
+ hostname_B = 'hB'
+
+ # hA LO (loopback)
+ loA_v4_host_address = ipaddress.ip_address('10.255.255.0')
+ loA_v6_host_address = ipaddress.ip_address('dead:beef::0')
+ loA_host_addresses = HostAddresses(v4=loA_v4_host_address,
+ v6=loA_v6_host_address)
+ new_service_host(hostname=hostname_A+"_LO",
+ host_addresses=loA_host_addresses,
+ cname_aliases=["alias1.hA", "alias2.hA"],
+ service_type='LO')
+
+ # hB LO (loopback)
+ new_service_host(hostname=hostname_B+"_LO",
+ cname_aliases=["alias1.hB"],
+ service_type='LO')
+
+ # hA-hB TRUNK
+ trunkAB_network_extattrs = {
+ "vrf_name": {"value": "dummy_vrf"},
+ }
+ trunkAB_host_extattrs = {
+ "Site": {"value": "dummy_site"},
+ }
+ trunkAB_service_networks = new_service_networks(
+ service_type='TRUNK',
+ extattrs=trunkAB_network_extattrs,
+ comment="Network for hA-hB TRUNK"
+ )
+
+ trunkAB_v4_host_address = trunkAB_service_networks.v4.network_address
+ trunkAB_v6_host_address = trunkAB_service_networks.v6.network_address
+ trunkAB_host_addresses = HostAddresses(v4=trunkAB_v4_host_address,
+ v6=trunkAB_v6_host_address)
+
+ new_service_host(hostname=hostname_A+"_TRUNK",
+ service_type='TRUNK',
+ host_addresses=trunkAB_host_addresses,
+ extattrs=trunkAB_host_extattrs)
+
+ new_service_host(hostname=hostname_B+"_TRUNK",
+ service_type='TRUNK',
+ service_networks=trunkAB_service_networks,
+ extattrs=trunkAB_host_extattrs)
+```
+
+#### Host/network deletion
+```
+ # Delete network
+ service_network = ipam.delete_service_network(
+ network=ipaddress.ip_network('10.255.255.0/26'), service_type='LO'
+ )
+
+ # Delete host
+ input_host_addresses = ipam.HostAddresses(
+ v4=ipaddress.ip_address('10.255.255.1'),
+ v6=ipaddress.ip_address('dead:beef::1')
+ )
+ host_addresses = ipam.delete_service_host(
+ hostname='ha_lo',
+ host_addresses=input_host_addresses,
+ cname_aliases=['alias1.ha', 'alias2.ha'],
+ service_type='LO'
+ )
+```
--
GitLab