TPT-4602: Added support for NAT Service #1033 (#738)

* Added support for NAT Gateway

* Fix lint

* Address CoPilot suggestions

* Added doc links

* Address CoPilot fixes

* Address more CoPilot suggestions

Author: ezilber-akamai

linode_api4/groups/networking.py

@@ -13,11 +13,18 @@
     IPAddress,
     IPv6Pool,
     IPv6Range,
+    NATGateway,
+    NATGatewayAddress,
     NetworkTransferPrice,
     Region,
 )
 from linode_api4.objects.base import _flatten_request_body_recursive
-from linode_api4.objects.networking import ReservedIPAddress, ReservedIPType
+from linode_api4.objects.networking import (
+    NATGatewaySettings,
+    NATGatewayType,
+    ReservedIPAddress,
+    ReservedIPType,
+)
 from linode_api4.paginated_list import PaginatedList
 from linode_api4.util import drop_null_keys
 
@@ -622,3 +629,116 @@ def reserved_ip_types(self, *filters) -> PaginatedList:
         return self.client._get_and_filter(
             ReservedIPType, *filters, endpoint="/networking/reserved/ips/types"
         )
+
+    def natgateways(self, *filters):
+        """
+        Retrieves the NAT Gateways your user has access to.
+
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/get-natgateways
+
+        :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
+
+        :returns: A list of NAT Gateways the acting user can access.
+        :rtype: PaginatedList of NATGateway
+        """
+        return self.client._get_and_filter(NATGateway, *filters)
+
+    def natgateway_create(
+        self,
+        region: Union[Region, str],
+        label: str,
+        addresses: Optional[
+            List[Union[NATGatewayAddress, Dict[str, Any]]]
+        ] = None,
+        default_ports_per_interface: Optional[int] = None,
+        use_autoscaling: Optional[bool] = None,
+        vpc_subnet_id: Optional[int] = None,
+        **kwargs,
+    ) -> NATGateway:
+        """
+        Create a NAT Gateway in the given region.
+
+        NOTE: NAT Gateways may not currently be available to all users.
+
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/post-natgateways
+
+        :param region: The region in which to create the NAT Gateway.
+        :type region: str or Region
+        :param label: The label of the NAT Gateway.
+        :type label: str
+        :param addresses: The reserved IP addresses to assign to this NAT Gateway.
+        :type addresses: list of NATGatewayAddress or list of dict
+        :param default_ports_per_interface: The default ports per interface to use.
+                                            Defaults to 4096 on the API side.
+        :type default_ports_per_interface: int
+        :param use_autoscaling: Whether the NAT Gateway should autoscale its address pool.
+        :type use_autoscaling: bool
+        :param vpc_subnet_id: The ID of the VPC subnet this NAT Gateway should attach to.
+        :type vpc_subnet_id: int
+
+        :returns: The new NAT Gateway.
+        :rtype: NATGateway
+        """
+        params = {
+            "region": region.id if isinstance(region, Region) else region,
+            "label": label,
+            "addresses": addresses,
+            "default_ports_per_interface": default_ports_per_interface,
+            "use_autoscaling": use_autoscaling,
+            "vpc_subnet_id": vpc_subnet_id,
+        }
+        params.update(kwargs)
+
+        result = self.client.post(
+            "/networking/natgateways",
+            data=drop_null_keys(_flatten_request_body_recursive(params)),
+        )
+
+        if "id" not in result:
+            raise UnexpectedResponseError(
+                "Unexpected response when creating NAT Gateway!", json=result
+            )
+
+        return NATGateway(self.client, result["id"], result)
+
+    def natgateway_types(self, *filters) -> PaginatedList:
+        """
+        Returns a list of NAT Gateway types with pricing information.
+
+        NOTE: NAT Gateways may not currently be available to all users.
+
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/get-natgateway-types
+
+        :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
+
+        :returns: A list of NAT Gateway types.
+        :rtype: PaginatedList of NATGatewayType
+        """
+        return self.client._get_and_filter(
+            NATGatewayType, *filters, endpoint="/networking/natgateways/types"
+        )
+
+    def natgateway_settings(self) -> NATGatewaySettings:
+        """
+        Returns the account-wide NAT Gateway settings and limits for the current user.
+
+        NOTE: NAT Gateways may not currently be available to all users.
+
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/get-natgateway-settings
+
+        :returns: The NAT Gateway settings for the current user.
+        :rtype: NATGatewaySettings
+        """
+        result = self.client.get("/networking/natgateways/settings")
+
+        if "allowed_ports_per_interface" not in result:
+            raise UnexpectedResponseError(
+                "Unexpected response when getting NAT Gateway settings!",
+                json=result,
+            )
+
+        return NATGatewaySettings.from_json(result)

linode_api4/groups/vpc.py

@@ -73,7 +73,6 @@ def create(
             "description": description,
             "ipv4": ipv4,
             "ipv6": ipv6,
-            "subnets": subnets,
         }
 
         if subnets is not None and len(subnets) > 0:
@@ -85,10 +84,30 @@ def create(
 
         params.update(kwargs)
 
-        result = self.client.post(
-            "/vpcs",
-            data=drop_null_keys(_flatten_request_body_recursive(params)),
-        )
+        data = drop_null_keys(_flatten_request_body_recursive(params))
+
+        # Recursively clean each subnet while preserving the ``{"id": null}``
+        # detach signal on any explicitly-supplied ``natgateway`` object.
+        if subnets is not None:
+            cleaned_subnets = []
+            for subnet in subnets:
+                flattened = _flatten_request_body_recursive(subnet)
+                cleaned = drop_null_keys(flattened)
+
+                # If the caller explicitly supplied a ``natgateway`` field,
+                # re-inject its flattened (but not null-stripped) form so
+                # the detach signal survives.
+                if (
+                    isinstance(flattened, dict)
+                    and "natgateway" in flattened
+                    and flattened["natgateway"] is not None
+                ):
+                    cleaned["natgateway"] = flattened["natgateway"]
+
+                cleaned_subnets.append(cleaned)
+            data["subnets"] = cleaned_subnets
+
+        result = self.client.post("/vpcs", data=data)
 
         if not "id" in result:
             raise UnexpectedResponseError(

linode_api4/objects/linode_interfaces.py

@@ -245,6 +245,38 @@ class LinodeInterfaceVPCIPv4Range(JSONObject):
     range: str = ""
 
 
+@dataclass
+class LinodeInterfaceVPCIPv4NATGatewayPortsetPort(JSONObject):
+    start: int = 0
+    end: int = 0
+
+
+@dataclass
+class LinodeInterfaceVPCIPv4NATGatewayPortset(JSONObject):
+    address: str = ""
+    ports: List[LinodeInterfaceVPCIPv4NATGatewayPortsetPort] = field(
+        default_factory=list
+    )
+
+
+@dataclass
+class LinodeInterfaceVPCIPv4NATGateway(JSONObject):
+    """
+    A NAT gateway under the IPv4 configuration of a VPC Linode Interface.
+    """
+
+    id: int = 0
+    label: str = ""
+    type: str = ""
+    url: str = ""
+    addresses: List[str] = field(default_factory=list)
+    portset_assignments: int = 0
+    portset_capacity: int = 0
+    portsets: List[LinodeInterfaceVPCIPv4NATGatewayPortset] = field(
+        default_factory=list
+    )  # NOTE: This field may not be available to all users.
+
+
 @dataclass
 class LinodeInterfaceVPCIPv4(JSONObject):
     """
@@ -255,6 +287,7 @@ class LinodeInterfaceVPCIPv4(JSONObject):
 
     addresses: List[LinodeInterfaceVPCIPv4Address] = field(default_factory=list)
     ranges: List[LinodeInterfaceVPCIPv4Range] = field(default_factory=list)
+    natgateway: Optional[LinodeInterfaceVPCIPv4NATGateway] = None
 
 
 @dataclass