doc: Add deprecation notice to OBJ cluster-related modules & fields

README.md

@@ -70,7 +70,7 @@ Name | Description |
 [linode.cloud.ipv6_range_info](./docs/modules/ipv6_range_info.md)|Get info about a Linode IPv6 range.|
 [linode.cloud.lke_cluster_info](./docs/modules/lke_cluster_info.md)|Get info about a Linode LKE cluster.|
 [linode.cloud.nodebalancer_info](./docs/modules/nodebalancer_info.md)|Get info about a Linode NodeBalancer.|
-[linode.cloud.object_cluster_info](./docs/modules/object_cluster_info.md)|Get info about a Linode Object Storage Cluster.|
+[linode.cloud.object_cluster_info](./docs/modules/object_cluster_info.md)|**NOTE: This module has been deprecated because it relies on deprecated API endpoints. Going forward, `region` will be the preferred way to designate where Object Storage resources should be created.**|
 [linode.cloud.placement_group_info](./docs/modules/placement_group_info.md)|Get info about a Linode Placement Group.|
 [linode.cloud.profile_info](./docs/modules/profile_info.md)|Get info about a Linode Profile.|
 [linode.cloud.ssh_key_info](./docs/modules/ssh_key_info.md)|Get info about the Linode SSH public key.|
@@ -102,7 +102,7 @@ Name | Description |
 [linode.cloud.instance_type_list](./docs/modules/instance_type_list.md)|List and filter on Linode Instance Types.|
 [linode.cloud.lke_version_list](./docs/modules/lke_version_list.md)|List Kubernetes versions available for deployment to a Kubernetes cluster.|
 [linode.cloud.nodebalancer_list](./docs/modules/nodebalancer_list.md)|List and filter on Nodebalancers.|
-[linode.cloud.object_cluster_list](./docs/modules/object_cluster_list.md)|List and filter on Object Storage Clusters.|
+[linode.cloud.object_cluster_list](./docs/modules/object_cluster_list.md)|**NOTE: This module has been deprecated because it relies on deprecated API endpoints. Going forward, `region` will be the preferred way to designate where Object Storage resources should be created.**|
 [linode.cloud.placement_group_list](./docs/modules/placement_group_list.md)|List and filter on Placement Groups.|
 [linode.cloud.region_list](./docs/modules/region_list.md)|List and filter on Linode Regions.|
 [linode.cloud.ssh_key_list](./docs/modules/ssh_key_list.md)|List and filter on SSH keys in the Linode profile.|

docs/modules/object_cluster_info.md

@@ -1,5 +1,7 @@
 # object_cluster_info
 
+**NOTE: This module has been deprecated because it relies on deprecated API endpoints. Going forward, `region` will be the preferred way to designate where Object Storage resources should be created.**
+
 Get info about a Linode Object Storage Cluster.
 
 - [Minimum Required Fields](#minimum-required-fields)

docs/modules/object_cluster_list.md

@@ -1,5 +1,7 @@
 # object_cluster_list
 
+**NOTE: This module has been deprecated because it relies on deprecated API endpoints. Going forward, `region` will be the preferred way to designate where Object Storage resources should be created.**
+
 List and filter on Object Storage Clusters.
 
 - [Minimum Required Fields](#minimum-required-fields)

docs/modules/object_keys.md

@@ -52,7 +52,7 @@ Manage Linode Object Storage Keys.
 
 | Field     | Type | Required | Description                                                                  |
 |-----------|------|----------|------------------------------------------------------------------------------|
-| `cluster` | <center>`str`</center> | <center>**Required**</center> | The id of the cluster that the provided bucket exists under.   |
+| `cluster` | <center>`str`</center> | <center>**Required**</center> | The id of the cluster that the provided bucket exists under. **NOTE: This field has been deprecated because it relies on deprecated API endpoints. Going forward, `region` will be the preferred way to designate where Object Storage resources should be created.**   |
 | `bucket_name` | <center>`str`</center> | <center>**Required**</center> | The name of the bucket to set the key's permissions for.   |
 | `permissions` | <center>`str`</center> | <center>**Required**</center> | The permissions to give the key.  **(Choices: `read_only`, `write_only`, `read_write`)** |
 

plugins/modules/object_cluster_info.py

@@ -52,7 +52,13 @@
 }
 
 SPECDOC_META = SpecDocMeta(
-    description=["Get info about a Linode Object Storage Cluster."],
+    description=[
+        "**NOTE: This module has been deprecated because it "
+        + "relies on deprecated API endpoints. Going forward, `region` will "
+        + "be the preferred way to designate where Object Storage resources "
+        + "should be created.**",
+        "Get info about a Linode Object Storage Cluster.",
+    ],
     requirements=global_requirements,
     author=global_authors,
     options=linode_object_cluster_info_spec,
@@ -121,6 +127,13 @@ def _get_matching_clusters(self) -> Optional[List[ObjectStorageCluster]]:
     def exec_module(self, **kwargs: Any) -> Optional[dict]:
         """Constructs and calls the Linode Object Storage Clusters module"""
 
+        self.warn(
+            "The linode.cloud.object_cluster_info module has been deprecated because it "
+            "relies on deprecated API endpoints.\n"
+            "Going forward, region will be the preferred way to designate where Object "
+            "Storage resources should be created."
+        )
+
         clusters = self._get_matching_clusters()
 
         if clusters is None:

plugins/modules/object_cluster_list.py

@@ -81,7 +81,13 @@
 }
 
 SPECDOC_META = SpecDocMeta(
-    description=["List and filter on Object Storage Clusters."],
+    description=[
+        "**NOTE: This module has been deprecated because it "
+        + "relies on deprecated API endpoints. Going forward, `region` will "
+        + "be the preferred way to designate where Object Storage resources "
+        + "should be created.**",
+        "List and filter on Object Storage Clusters.",
+    ],
     requirements=global_requirements,
     author=global_authors,
     options=spec,
@@ -111,6 +117,13 @@ def __init__(self) -> None:
     def exec_module(self, **kwargs: Any) -> Optional[dict]:
         """Entrypoint for object storage cluster list module"""
 
+        self.warn(
+            "The linode.cloud.object_cluster_list has been deprecated because it relies "
+            "on deprecated API endpoints.\n"
+            "Going forward, region will be the preferred way to designate where Object "
+            "Storage resources should be created."
+        )
+
         filter_dict = construct_api_filter(self.module.params)
 
         self.results["clusters"] = get_all_paginated(

plugins/modules/object_keys.py

@@ -28,7 +28,11 @@
         type=FieldType.string,
         required=True,
         description=[
-            "The id of the cluster that the provided bucket exists under."
+            "The id of the cluster that the provided bucket exists under.",
+            "**NOTE: This field has been deprecated because it "
+            + "relies on deprecated API endpoints. Going forward, `region` will "
+            + "be the preferred way to designate where Object Storage resources "
+            + "should be created.**",
         ],
     ),
     "bucket_name": SpecField(
@@ -164,9 +168,31 @@ def _handle_key_absent(self) -> None:
             self._key.delete()
             self.register_action("Deleted key {0}".format(label))
 
+    def _attempt_warnings(self, **kwargs: Any) -> None:
+        """
+        Raises warnings depending on the user-defined module arguments.
+        """
+
+        # Logic to warn if the `cluster` field has been specified
+        access: Optional[List] = kwargs.get("access", None)
+
+        # If cluster has been defined for any of the `access` objects,
+        # raise a deprecation warning
+        if access is not None and any(
+            v is not None for v in access if v.get("cluster", None)
+        ):
+            self.warn(
+                "The access.cluster field has been deprecated because it relies "
+                "on deprecated API endpoints.\n"
+                "Going forward, region will be the preferred way to designate where Object "
+                "Storage resources should be created."
+            )
+
     def exec_module(self, **kwargs: Any) -> Optional[dict]:
         """Constructs and calls the Linode Object Storage Key module"""
 
+        self._attempt_warnings(**kwargs)
+
         state = kwargs.pop("state")
 
         if state == "absent":