linode-api4 5.44.0__tar.gz → 5.45.0__tar.gz

{linode_api4-5.44.0/linode_api4.egg-info → linode_api4-5.45.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: linode_api4
-Version: 5.44.0
+Version: 5.45.0
 Summary: The official Python SDK for Linode API v4
 Author-email: Linode <devs@linode.com>
 License: BSD-3-Clause

{linode_api4-5.44.0 → linode_api4-5.45.0}/linode_api4/groups/linode.py

@@ -166,6 +166,7 @@ class LinodeGroup(Group):
         kernel: Optional[str] = None,
         boot_size: Optional[int] = None,
         authorized_users: Optional[List[str]] = None,
+        ipv4: Optional[List[str]] = None,
         **kwargs,
     ):
         """
@@ -355,6 +356,9 @@ class LinodeGroup(Group):
         :param boot_size: The size of the boot disk in MB. If provided, this will be used to create
                           the boot disk for the Instance.
         :type boot_size: int
+        :param ipv4: A list of reserved IPv4 addresses to assign to this Instance.
+                     NOTE: Reserved IP feature may not currently be available to all users.
+        :type ipv4: list[str]
 
         :returns: A new Instance object
         :rtype: Instance
@@ -401,6 +405,7 @@ class LinodeGroup(Group):
             "network_helper": network_helper,
             "kernel": kernel,
             "boot_size": boot_size,
+            "ipv4": ipv4,
         }
 
         params.update(kwargs)

{linode_api4-5.44.0 → linode_api4-5.45.0}/linode_api4/groups/monitor.py

@@ -8,11 +8,21 @@ from linode_api4.objects import (
     AlertDefinition,
     AlertDefinitionEntity,
     AlertScope,
+    LogsDestination,
+    LogsDestinationType,
+    LogsStream,
+    LogsStreamStatus,
+    LogsStreamType,
     MonitorDashboard,
     MonitorMetricsDefinition,
     MonitorService,
     MonitorServiceToken,
 )
+from linode_api4.objects.monitor import (
+    AkamaiObjectStorageLogsDestinationDetails,
+    CustomHTTPSLogsDestinationDetails,
+    LogsStreamDetails,
+)
 
 __all__ = [
     "MonitorGroup",
@@ -37,8 +47,6 @@ class MonitorGroup(Group):
             dashboard = client.load(MonitorDashboard, 1)
             dashboards_by_service = client.monitor.dashboards(service_type="dbaas")
 
-        .. note:: This endpoint is in beta. This will only function if base_url is set to `https://api.linode.com/v4beta`.
-
         API Documentation:
         - All Dashboards: https://techdocs.akamai.com/linode-api/reference/get-dashboards-all
         - Dashboards by Service: https://techdocs.akamai.com/linode-api/reference/get-dashboards
@@ -73,8 +81,6 @@ class MonitorGroup(Group):
             supported_services = client.monitor.services()
             service_details = client.monitor.load(MonitorService, "dbaas")
 
-        .. note:: This endpoint is in beta. This will only function if base_url is set to `https://api.linode.com/v4beta`.
-
         API Documentation: https://techdocs.akamai.com/linode-api/reference/get-monitor-services
         API Documentation: https://techdocs.akamai.com/linode-api/reference/get-monitor-services-for-service-type
 
@@ -100,7 +106,6 @@ class MonitorGroup(Group):
         Returns metrics for a specific service type.
 
             metrics = client.monitor.list_metric_definitions(service_type="dbaas")
-        .. note:: This endpoint is in beta. This will only function if base_url is set to `https://api.linode.com/v4beta`.
 
         API Documentation: https://techdocs.akamai.com/linode-api/reference/get-monitor-information
 
@@ -126,8 +131,6 @@ class MonitorGroup(Group):
         Returns a JWE Token for a specific service type.
             token = client.monitor.create_token(service_type="dbaas", entity_ids=[1234])
 
-        .. note:: This endpoint is in beta. This will only function if base_url is set to `https://api.linode.com/v4beta`.
-
         API Documentation: https://techdocs.akamai.com/linode-api/reference/post-get-token
 
         :param service_type: The service type to create token for.
@@ -165,7 +168,6 @@ class MonitorGroup(Group):
 
             alerts = client.monitor.alert_definitions()
             alerts_by_service = client.monitor.alert_definitions(service_type="dbaas")
-        .. note:: This endpoint is in beta and requires using the v4beta base URL.
 
         API Documentation:
             https://techdocs.akamai.com/linode-api/reference/get-alert-definitions
@@ -202,8 +204,6 @@ class MonitorGroup(Group):
         Examples:
             channels = client.monitor.alert_channels()
 
-        .. note:: This endpoint is in beta and requires using the v4beta base URL.
-
         API Documentation: https://techdocs.akamai.com/linode-api/reference/get-notification-channels
 
         :param filters: Optional filter expressions to apply to the collection.
@@ -232,8 +232,6 @@ class MonitorGroup(Group):
         The alert definition configures when alerts are fired and which channels
         are notified.
 
-        .. note:: This endpoint is in beta and requires using the v4beta base URL.
-
         API Documentation: https://techdocs.akamai.com/linode-api/reference/post-alert-definition-for-service-type
 
         :param service_type: Service type for which to create the alert definition
@@ -309,9 +307,7 @@ class MonitorGroup(Group):
 
         This endpoint supports pagination fields (`page`, `page_size`) in the API.
 
-        .. note:: This endpoint is in beta and requires using the v4beta base URL.
-
-        API Documentation: TODO
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/get-alert-definition-entities
 
         :param service_type: Service type for the alert definition (e.g. `dbaas`).
         :type service_type: str
@@ -332,3 +328,206 @@ class MonitorGroup(Group):
             *filters,
             endpoint=endpoint,
         )
+
+    def destinations(self, *filters) -> PaginatedList:
+        """
+        List available logs destinations.
+
+        Returns a paginated collection of :class:`LogsDestination` objects which
+        describe logs destinations. By default, this method returns all available
+        destinations; you can supply optional filter expressions to restrict
+        the results, for example::
+
+            # Get destinations created by username and with id 111
+            destinations = client.monitor.destinations(LogsDestination.created_by == "username",
+                                                        LogsDestination.id == 111)
+
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/get-destinations
+
+        :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 :class:`LogsDestination` objects matching the query.
+        :rtype: PaginatedList of LogsDestination
+        """
+
+        return self.client._get_and_filter(LogsDestination, *filters)
+
+    def destination_create(
+        self,
+        label: str,
+        type: Union[LogsDestinationType, str],
+        details: Union[
+            AkamaiObjectStorageLogsDestinationDetails,
+            CustomHTTPSLogsDestinationDetails,
+        ],
+    ) -> LogsDestination:
+        """
+        Creates a new :any:`LogsDestination` for logs on this account.
+
+        For an ``akamai_object_storage`` destination::
+
+           client = LinodeClient(TOKEN)
+
+           new_destination = client.monitor.destination_create(
+               label="OBJ_logs_destination",
+               type="akamai_object_storage",
+               details=AkamaiObjectStorageLogsDestinationDetails(
+                   access_key_id="1ABCD23EFG4HIJKLMNO5",
+                   access_key_secret="1aB2CD3e4fgHi5JK6lmnop7qR8STU9VxYzabcdefHh",
+                   bucket_name="primary-bucket",
+                   host="primary-bucket-1.us-east-12.linodeobjects.com",
+                   path="audit-logs",
+               )
+           )
+
+        For a ``custom_https`` destination::
+
+           new_destination = client.monitor.destination_create(
+               label="custom_logs_destination",
+               type="custom_https",
+               details=CustomHTTPSLogsDestinationDetails(
+                   endpoint_url="https://my-site.com/log-storage/basicAuth",
+                   authentication=DestinationAuthentication(
+                       type="basic",
+                       details=BasicAuthenticationDetails(
+                           basic_authentication_user="user",
+                           basic_authentication_password="pass",
+                       ),
+                   ),
+                   data_compression="gzip",
+                   content_type="application/json",
+               )
+           )
+
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/post-destination
+
+        :param label: The name for this logs destination.
+        :type label: str
+        :param type: The type of destination — ``akamai_object_storage`` or ``custom_https``.
+        :type type: str or LogsDestinationType
+        :param details: A typed details object matching the destination type.
+                        Use :class:`AkamaiObjectStorageLogsDestinationDetails` for
+                        ``akamai_object_storage`` or :class:`CustomHTTPSLogsDestinationDetails`
+                        for ``custom_https``.
+        :type details: AkamaiObjectStorageLogsDestinationDetails or CustomHTTPSLogsDestinationDetails
+
+        :returns: The newly created logs destination.
+        :rtype: LogsDestination
+        """
+
+        params = {
+            "label": label,
+            "type": type,
+            "details": details.dict,
+        }
+
+        result = self.client.post("/monitor/streams/destinations", data=params)
+
+        if "id" not in result:
+            raise UnexpectedResponseError(
+                "Unexpected response when creating destination!",
+                json=result,
+            )
+
+        return LogsDestination(self.client, result["id"], result)
+
+    def streams(self, *filters) -> PaginatedList:
+        """
+        List available logs streams.
+
+        Returns a paginated collection of :class:`LogsStream` objects which
+        describe logs streams. By default, this method returns all available
+        streams; you can supply optional filter expressions to restrict
+        the results, for example::
+
+            # Get all streams with status ``provisioning``
+            provisioning_streams = client.monitor.streams(LogsStream.status == "provisioning")
+
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/get-streams
+
+        :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 :class:`LogsStream` objects matching the query.
+        :rtype: PaginatedList of LogsStream
+        """
+
+        return self.client._get_and_filter(LogsStream, *filters)
+
+    def stream_create(
+        self,
+        destinations: list[int],
+        label: str,
+        type: Union[LogsStreamType, str],
+        status: Optional[Union[LogsStreamStatus, str]] = None,
+        details: Optional[LogsStreamDetails] = None,
+    ) -> LogsStream:
+        """
+        Creates a new :any:`LogsStream` for logs on this account. For example::
+
+           client = LinodeClient(TOKEN)
+
+           # audit_logs stream (no details required)
+           new_stream = client.monitor.stream_create(
+               destinations=[1234],
+               label="Linode_services",
+               status="active",
+               type="audit_logs"
+           )
+
+           # lke_audit_logs stream with specific clusters
+           lke_stream = client.monitor.stream_create(
+               destinations=[1234],
+               label="LKE_audit_stream",
+               type="lke_audit_logs",
+               details=LogsStreamDetails(
+                   cluster_ids=[1111, 2222],
+                   is_auto_add_all_clusters_enabled=False,
+               )
+           )
+
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/post-stream
+
+        :param destinations: The unique identifier for the sync point that will receive logs data.
+                            Run the List destinations operation and store the id values for each applicable destination.
+                            At the moment only single destination is supported.
+        :type destinations: list[int]
+        :param label: The name of the stream. This is used for display purposes in Akamai Cloud Manager.
+        :type label: str
+        :param type: The type of stream — ``audit_logs`` for Linode control plane logs,
+                     or ``lke_audit_logs`` for LKE enterprise cluster audit logs.
+        :type type: str or LogsStreamType
+        :param status: (Optional) The availability status of the stream. Possible values are: ``active``, ``inactive``.
+                        Defaults to ``active``.
+        :type status: str
+        :param details: (Optional) Additional stream details. Only applicable for
+                        ``lke_audit_logs`` streams. Omit for ``audit_logs`` streams.
+        :type details: LogsStreamDetails
+
+        :returns: The newly created logs stream.
+        :rtype: LogsStream
+        """
+
+        params = {
+            "label": label,
+            "type": type,
+            "destinations": destinations,
+        }
+
+        if status is not None:
+            params["status"] = status
+
+        if details is not None:
+            params["details"] = details.dict
+
+        result = self.client.post("/monitor/streams", data=params)
+
+        if "id" not in result:
+            raise UnexpectedResponseError(
+                "Unexpected response when creating logs stream!",
+                json=result,
+            )
+
+        return LogsStream(self.client, result["id"], result)

{linode_api4-5.44.0 → linode_api4-5.45.0}/linode_api4/groups/networking.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict, Optional, Union
+from typing import Any, Dict, List, Optional, Union
 
 from linode_api4.errors import UnexpectedResponseError
 from linode_api4.groups import Group
@@ -17,6 +17,8 @@ from linode_api4.objects import (
     Region,
 )
 from linode_api4.objects.base import _flatten_request_body_recursive
+from linode_api4.objects.networking import ReservedIPAddress, ReservedIPType
+from linode_api4.paginated_list import PaginatedList
 from linode_api4.util import drop_null_keys
 
 
@@ -328,10 +330,23 @@ class NetworkingGroup(Group):
             },
         )
 
-    def ip_allocate(self, linode, public=True):
+    def ip_allocate(
+        self,
+        linode: Optional[Union[Instance, int]] = None,
+        public: bool = True,
+        reserved: bool = False,
+        region: Optional[Union[Region, str]] = None,
+    ) -> IPAddress:
         """
-        Allocates an IP to a Instance you own.  Additional IPs must be requested
-        by opening a support ticket first.
+        Allocates an IP to an Instance you own, or reserves a new IP address.
+
+        When ``reserved`` is False (default), ``linode`` is required and an
+        ephemeral IP is allocated and assigned to that Instance.
+
+        When ``reserved`` is True, either ``region`` or ``linode`` must be
+        provided.  Passing only ``region`` creates an unassigned reserved IP.
+        Passing ``linode`` (with or without ``region``) creates a reserved IP
+        in the Instance's region and assigns it to that Instance.
 
         API Documentation: https://techdocs.akamai.com/linode-api/reference/post-allocate-ip
 
@@ -339,18 +354,42 @@ class NetworkingGroup(Group):
         :type linode: Instance or int
         :param public: If True, allocate a public IP address.  Defaults to True.
         :type public: bool
+        :param reserved: If True, reserve the new IP address.
+                         NOTE: Reserved IP feature may not currently be available to all users.
+        :type reserved: bool
+        :param region: The region for the reserved IP (required when reserved=True and linode is not set).
+                       NOTE: Reserved IP feature may not currently be available to all users.
+        :type region: str or Region
 
         :returns: The new IPAddress.
         :rtype: IPAddress
         """
-        result = self.client.post(
-            "/networking/ips/",
-            data={
-                "linode_id": linode.id if isinstance(linode, Base) else linode,
-                "type": "ipv4",
-                "public": public,
-            },
-        )
+        if not reserved and linode is None:
+            raise ValueError("linode is required when reserved is False.")
+        if reserved and linode is None and region is None:
+            raise ValueError(
+                "Either linode or region must be provided when reserved is True."
+            )
+        if not reserved and region is not None:
+            raise ValueError("region is only valid when reserved is True.")
+
+        data = {
+            "type": "ipv4",
+            "public": public,
+        }
+
+        if linode is not None:
+            data["linode_id"] = (
+                linode.id if isinstance(linode, Base) else linode
+            )
+
+        if reserved:
+            data["reserved"] = True
+
+        if region is not None:
+            data["region"] = region.id if isinstance(region, Base) else region
+
+        result = self.client.post("/networking/ips/", data=data)
 
         if not "address" in result:
             raise UnexpectedResponseError(
@@ -510,3 +549,76 @@ class NetworkingGroup(Group):
             return False
 
         return True
+
+    def reserved_ips(self, *filters) -> PaginatedList:
+        """
+        Returns a list of reserved IPv4 addresses on your account.
+
+        NOTE: Reserved IP feature may not currently be available to all users.
+
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/get-reserved-ips
+
+        :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 reserved IP addresses on the account.
+        :rtype: PaginatedList of ReservedIPAddress
+        """
+        return self.client._get_and_filter(ReservedIPAddress, *filters)
+
+    def reserved_ip_create(
+        self,
+        region: Union[Region, str],
+        tags: Optional[List[str]] = None,
+        **kwargs,
+    ) -> ReservedIPAddress:
+        """
+        Reserves a new IPv4 address in the given region.
+
+        NOTE: Reserved IP feature may not currently be available to all users.
+
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/post-reserved-ip
+
+        :param region: The region in which to reserve the IP.
+        :type region: str or Region
+        :param tags: Tags to apply to the reserved IP.
+        :type tags: list of str
+
+        :returns: The new reserved IP address.
+        :rtype: ReservedIPAddress
+        """
+        params = {
+            "region": region.id if isinstance(region, Region) else region,
+        }
+        if tags is not None:
+            params["tags"] = tags
+        params.update(kwargs)
+
+        result = self.client.post("/networking/reserved/ips", data=params)
+
+        if "address" not in result:
+            raise UnexpectedResponseError(
+                "Unexpected response when reserving IP address!", json=result
+            )
+
+        return ReservedIPAddress(self.client, result["address"], result)
+
+    def reserved_ip_types(self, *filters) -> PaginatedList:
+        """
+        Returns a list of reserved IP types with pricing information.
+
+        NOTE: Reserved IP feature may not currently be available to all users.
+
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/get-reserved-ip-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 reserved IP types.
+        :rtype: PaginatedList of ReservedIPType
+        """
+        return self.client._get_and_filter(
+            ReservedIPType, *filters, endpoint="/networking/reserved/ips/types"
+        )

{linode_api4-5.44.0 → linode_api4-5.45.0}/linode_api4/groups/nodebalancer.py

@@ -32,20 +32,26 @@ class NodeBalancerGroup(Group):
 
         :param region: The Region in which to create the NodeBalancer.
         :type region: Region or str
+        :param ipv4: A reserved IPv4 address to assign to this NodeBalancer.
+                     NOTE: Reserved IP feature may not currently be available to all users.
+        :type ipv4: str
 
         :returns: The new NodeBalancer
         :rtype: NodeBalancer
         """
+        ipv4 = kwargs.pop("ipv4", None)
         params = {
             "region": region.id if isinstance(region, Base) else region,
         }
+        if ipv4 is not None:
+            params["ipv4"] = ipv4
         params.update(kwargs)
 
         result = self.client.post("/nodebalancers", data=params)
 
         if not "id" in result:
             raise UnexpectedResponseError(
-                "Unexpected response when creating Nodebalaner!", json=result
+                "Unexpected response when creating NodeBalancer!", json=result
             )
 
         n = NodeBalancer(self.client, result["id"], result)

{linode_api4-5.44.0 → linode_api4-5.45.0}/linode_api4/groups/object_storage.py

@@ -539,7 +539,7 @@ class ObjectStorageGroup(Group):
         """
         Lists the active account-level Object Storage quotas applied to your account.
 
-        API Documentation: TBD
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/get-object-storage-global-quotas
 
         :param filters: Any number of filters to apply to this query.
                         See :doc:`Filtering Collections</linode_api4/objects/filtering>`

{linode_api4-5.44.0 → linode_api4-5.45.0}/linode_api4/groups/tag.py

@@ -32,7 +32,8 @@ class TagGroup(Group):
         domains=None,
         nodebalancers=None,
         volumes=None,
-        entities=[],
+        entities=None,
+        reserved_ipv4_addresses=None,
     ):
         """
         Creates a new Tag and optionally applies it to the given entities.
@@ -61,10 +62,14 @@ class TagGroup(Group):
         :param volumes: A list of Volumes to apply this Tag to upon
                         creation
         :type volumes: list of Volumes or list of int
+        :param reserved_ipv4_addresses: A list of reserved IPv4 addresses to apply
+                        this Tag to upon creation.
+        :type reserved_ipv4_addresses: list of str
 
         :returns: The new Tag
         :rtype: Tag
         """
+        entities = entities or []
         linode_ids, nodebalancer_ids, domain_ids, volume_ids = [], [], [], []
 
         # filter input into lists of ids
@@ -103,6 +108,7 @@ class TagGroup(Group):
             "nodebalancers": nodebalancer_ids or None,
             "domains": domain_ids or None,
             "volumes": volume_ids or None,
+            "reserved_ipv4_addresses": reserved_ipv4_addresses or None,
         }
 
         result = self.client.post("/tags", data=params)

{linode_api4-5.44.0 → linode_api4-5.45.0}/linode_api4/objects/linode.py

@@ -1584,7 +1584,7 @@ class Instance(Base):
         b = Backup(self._client, result["id"], self.id, result)
         return b
 
-    def ip_allocate(self, public=False):
+    def ip_allocate(self, public=False, address=None):
         """
         Allocates a new :any:`IPAddress` for this Instance.  Additional public
         IPs require justification, and you may need to open a :any:`SupportTicket`
@@ -1596,17 +1596,26 @@ class Instance(Base):
         :param public: If the new IP should be public or private.  Defaults to
                        private.
         :type public: bool
+        :param address: A reserved IPv4 address to assign to this Instance instead
+                        of allocating a new ephemeral IP.  The address must be an
+                        unassigned reserved IP owned by this account.
+                        NOTE: Reserved IP feature may not currently be available to all users.
+        :type address: str
 
         :returns: The new IPAddress
         :rtype: IPAddress
         """
+        data = {
+            "type": "ipv4",
+            "public": public,
+        }
+        if address is not None:
+            data["address"] = address
+
         result = self._client.post(
             "{}/ips".format(Instance.api_endpoint),
             model=self,
-            data={
-                "type": "ipv4",
-                "public": public,
-            },
+            data=data,
         )
 
         if not "address" in result: