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

{linode_api4-5.43.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.43.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.43.0 → linode_api4-5.45.0}/linode_api4/groups/linode.py

@@ -162,6 +162,11 @@ class LinodeGroup(Group):
         interface_generation: Optional[Union[InterfaceGeneration, str]] = None,
         network_helper: Optional[bool] = None,
         maintenance_policy: Optional[str] = None,
+        root_pass: Optional[str] = None,
+        kernel: Optional[str] = None,
+        boot_size: Optional[int] = None,
+        authorized_users: Optional[List[str]] = None,
+        ipv4: Optional[List[str]] = None,
         **kwargs,
     ):
         """
@@ -172,27 +177,26 @@ class LinodeGroup(Group):
         To create an Instance from an :any:`Image`, call `instance_create` with
         a :any:`Type`, a :any:`Region`, and an :any:`Image`.  All three of
         these fields may be provided as either the ID or the appropriate object.
-        In this mode, a root password will be generated and returned with the
-        new Instance object.
+        When an Image is provided, at least one of ``root_pass``, ``authorized_users``, or
+        ``authorized_keys`` must also be given.
 
         For example::
 
-           new_linode, password = client.linode.instance_create(
+           new_linode = client.linode.instance_create(
                "g6-standard-2",
                "us-east",
-               image="linode/debian9")
+               image="linode/debian13",
+               root_pass="aComplex@Password123")
 
            ltype = client.linode.types().first()
            region = client.regions().first()
            image = client.images().first()
 
-           another_linode, password = client.linode.instance_create(
+           another_linode = client.linode.instance_create(
                ltype,
                region,
-               image=image)
-
-        To output the password from the above example:
-            print(password)
+               image=image,
+               authorized_keys="ssh-rsa AAAA")
 
         To output the first IPv4 address of the new Linode:
             print(new_linode.ipv4[0])
@@ -210,10 +214,11 @@ class LinodeGroup(Group):
 
            stackscript = StackScript(client, 10079)
 
-           new_linode, password = client.linode.instance_create(
+           new_linode = client.linode.instance_create(
               "g6-standard-2",
               "us-east",
-              image="linode/debian9",
+              image="linode/debian13",
+              root_pass="aComplex@Password123",
               stackscript=stackscript,
               stackscript_data={"gh_username": "example"})
 
@@ -244,10 +249,11 @@ class LinodeGroup(Group):
         To create a new Instance with explicit interfaces, provide list of
         LinodeInterfaceOptions objects or dicts to the "interfaces" field::
 
-        linode, password = client.linode.instance_create(
+        linode = client.linode.instance_create(
             "g6-standard-1",
             "us-mia",
             image="linode/ubuntu24.04",
+            root_pass="aComplex@Password123",
 
             # This can be configured as an account-wide default
             interface_generation=InterfaceGeneration.LINODE,
@@ -280,10 +286,14 @@ class LinodeGroup(Group):
         :type ltype: str or Type
         :param region: The Region in which we are creating the Instance
         :type region: str or Region
-        :param image: The Image to deploy to this Instance. If this is provided
-                      and no root_pass is given, a password will be generated
-                      and returned along with the new Instance.
+        :param image: The Image to deploy to this Instance. If this is provided,
+                      at least one of root_pass, authorized_users, or authorized_keys must also be
+                      provided.
         :type image: str or Image
+        :param root_pass: The root password for the new Instance. Required when
+                          an image is provided and neither authorized_users nor
+                          authorized_keys are given.
+        :type root_pass: str
         :param stackscript: The StackScript to deploy to the new Instance.  If
                             provided, "image" is required and must be compatible
                             with the chosen StackScript.
@@ -300,6 +310,11 @@ class LinodeGroup(Group):
                                 be a single key, or a path to a file containing
                                 the key.
         :type authorized_keys: list or str
+        :param authorized_users: A list of usernames whose keys should be installed
+                                 as trusted for the root user.  These user's keys
+                                 should already be set up, see :any:`ProfileGroup.ssh_keys`
+                                 for details.
+        :type authorized_users: list[str]
         :param label: The display label for the new Instance
         :type label: str
         :param group: The display group for the new Instance
@@ -335,26 +350,42 @@ class LinodeGroup(Group):
         :param maintenance_policy: The slug of the maintenance policy to apply during maintenance.
                                       If not provided, the default policy (linode/migrate) will be applied.
         :type maintenance_policy: str
-
-        :returns: A new Instance object, or a tuple containing the new Instance and
-                  the generated password.
-        :rtype: Instance or tuple(Instance, str)
+        :param kernel: The kernel to boot the Instance with. If provided, this will be used as the
+                       kernel for the default configuration profile.
+        :type kernel: str
+        :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
         :raises ApiError: If contacting the API fails
         :raises UnexpectedResponseError: If the API response is somehow malformed.
                                          This usually indicates that you are using
                                          an outdated library.
         """
 
-        ret_pass = None
-        if image and not "root_pass" in kwargs:
-            ret_pass = Instance.generate_root_password()
-            kwargs["root_pass"] = ret_pass
+        if (
+            image
+            and not root_pass
+            and not authorized_keys
+            and not authorized_users
+        ):
+            raise ValueError(
+                "When creating an Instance from an Image, at least one of "
+                "root_pass, authorized_users, or authorized_keys must be provided."
+            )
 
         params = {
             "type": ltype,
             "region": region,
             "image": image,
+            "root_pass": root_pass,
             "authorized_keys": load_and_validate_keys(authorized_keys),
+            "authorized_users": authorized_users,
             # These will automatically be flattened below
             "firewall_id": firewall,
             "backup_id": backup,
@@ -372,6 +403,9 @@ class LinodeGroup(Group):
             "interfaces": interfaces,
             "interface_generation": interface_generation,
             "network_helper": network_helper,
+            "kernel": kernel,
+            "boot_size": boot_size,
+            "ipv4": ipv4,
         }
 
         params.update(kwargs)
@@ -386,10 +420,7 @@ class LinodeGroup(Group):
                 "Unexpected response when creating linode!", json=result
             )
 
-        l = Instance(self.client, result["id"], result)
-        if not ret_pass:
-            return l
-        return l, ret_pass
+        return Instance(self.client, result["id"], result)
 
     @staticmethod
     def build_instance_metadata(user_data=None, encode_user_data=True):
@@ -398,10 +429,11 @@ class LinodeGroup(Group):
         the :any:`instance_create` method. This helper can also be used
         when cloning and rebuilding Instances.
         **Creating an Instance with User Data**::
-            new_linode, password = client.linode.instance_create(
+            new_linode = client.linode.instance_create(
                 "g6-standard-2",
                 "us-east",
                 image="linode/ubuntu22.04",
+                root_pass="aComplex@Password123",
                 metadata=client.linode.build_instance_metadata(user_data="myuserdata")
             )
         :param user_data: User-defined data to provide to the Linode Instance through

{linode_api4-5.43.0 → linode_api4-5.45.0}/linode_api4/groups/lock.py

@@ -24,7 +24,7 @@ class LockGroup(Group):
 
            locks = client.locks()
 
-        API Documentation: TBD
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/get-resource-locks
 
         :param filters: Any number of filters to apply to this query.
                         See :doc:`Filtering Collections</linode_api4/objects/filtering>`
@@ -44,7 +44,7 @@ class LockGroup(Group):
         """
         Creates a new Resource Lock for the specified entity.
 
-        API Documentation: TBD
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/post-resource-lock
 
         :param entity_type: The type of entity to lock (e.g., "linode").
         :type entity_type: str

{linode_api4-5.43.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)