new: Add modules for Placement group

README.md

@@ -39,6 +39,7 @@ Name | Description |
 [linode.cloud.nodebalancer_node](./docs/modules/nodebalancer_node.md)|Manage Linode NodeBalancer Nodes.|
 [linode.cloud.nodebalancer_stats](./docs/modules/nodebalancer_stats.md)|View a Linode NodeBalancers Stats.|
 [linode.cloud.object_keys](./docs/modules/object_keys.md)|Manage Linode Object Storage Keys.|
+[linode.cloud.placement_group](./docs/modules/placement_group.md)|Manage a Linode Placement Group.|
 [linode.cloud.ssh_key](./docs/modules/ssh_key.md)|Manage a Linode SSH key.|
 [linode.cloud.stackscript](./docs/modules/stackscript.md)|Manage a Linode StackScript.|
 [linode.cloud.token](./docs/modules/token.md)|Manage a Linode Token.|
@@ -68,6 +69,7 @@ Name | Description |
 [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.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.|
 [linode.cloud.stackscript_info](./docs/modules/stackscript_info.md)|Get info about a Linode StackScript.|
@@ -98,6 +100,7 @@ Name | Description |
 [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.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.|
 [linode.cloud.stackscript_list](./docs/modules/stackscript_list.md)|List and filter on Linode stackscripts.|

docs/modules/instance.md

@@ -93,7 +93,19 @@ Manage Linode Instances, Configs, and Disks.
     image: linode/ubuntu22.04
     root_pass: verysecurepassword!!!
     metadata:
-        user_data: myuserdata
+      user_data: myuserdata
+    state: present
+```
+
+```yaml
+- name: Create a new Linode instance under a placement group.
+  linode.cloud.instance:
+    label: my-linode
+    type: g6-nanode-1
+    region: us-east
+    placement_group: 
+      id: 123
+      compliant_only: false
     state: present
 ```
 
@@ -136,6 +148,7 @@ Manage Linode Instances, Configs, and Disks.
 | `migration_type` | <center>`str`</center> | <center>Optional</center> | The type of migration to use for Region and Type migrations.  **(Choices: `cold`, `warm`; Default: `cold`)** |
 | `auto_disk_resize` | <center>`bool`</center> | <center>Optional</center> | Whether implicitly created disks should be resized during a type change operation.  **(Default: `False`)** |
 | `tags` | <center>`list`</center> | <center>Optional</center> | An array of tags applied to this object. Tags are for organizational purposes only.  **(Updatable)** |
+| [`placement_group` (sub-options)](#placement_group) | <center>`dict`</center> | <center>Optional</center> | A Placement Group to create this Linode under.   |
 
 ### configs
 
@@ -278,6 +291,13 @@ Manage Linode Instances, Configs, and Disks.
 |-----------|------|----------|------------------------------------------------------------------------------|
 | `public` | <center>`bool`</center> | <center>**Required**</center> | Whether the allocated IPv4 address should be public or private.   |
 
+### placement_group
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `id` | <center>`int`</center> | <center>**Required**</center> | The id of the placement group.   |
+| `compliant_only` | <center>`bool`</center> | <center>Optional</center> | Whether the newly added/migrated/resized linode must be compliant for flexible placement groups.  **(Default: `False`)** |
+
 ## Return Values
 
 - `instance` - The instance description in JSON serialized form.
@@ -326,7 +346,13 @@ Manage Linode Instances, Configs, and Disks.
           ],
           "type": "g6-standard-1",
           "updated": "2018-01-01T00:01:01",
-          "watchdog_enabled": true
+          "watchdog_enabled": true,
+          "placement_group": {
+            "id": 123,
+            "label": "test",
+            "affinity_type": "anti_affinity:local",
+            "is_strict": true
+          }
         }
         ```
     - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#linode-view__responses) for a list of returned fields

docs/modules/instance_info.md

@@ -82,7 +82,13 @@ Get info about a Linode Instance.
           ],
           "type": "g6-standard-1",
           "updated": "2018-01-01T00:01:01",
-          "watchdog_enabled": true
+          "watchdog_enabled": true,
+          "placement_group": {
+            "id": 123,
+            "label": "test",
+            "affinity_type": "anti_affinity:local",
+            "is_strict": true
+          }
         }
         ```
     - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#linode-view__responses) for a list of returned fields

docs/modules/placement_group.md

@@ -0,0 +1,87 @@
+# placement_group
+
+Manage a Linode Placement Group.
+
+**:warning: This module makes use of beta endpoints and requires the `api_version` field be explicitly set to `v4beta`.**
+
+- [Minimum Required Fields](#minimum-required-fields)
+- [Examples](#examples)
+- [Parameters](#parameters)
+- [Return Values](#return-values)
+
+## Minimum Required Fields
+| Field       | Type  | Required     | Description                                                                                                                                                                                                              |
+|-------------|-------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `api_token` | `str` | **Required** | The Linode account personal access token. It is necessary to run the module. <br/>It can be exposed by the environment variable `LINODE_API_TOKEN` instead. <br/>See details in [Usage](https://github.com/linode/ansible_linode?tab=readme-ov-file#usage). |
+
+## Examples
+
+```yaml
+- name: Create a placement group
+  linode.cloud.placement_group:
+    label: my-pg
+    region: us-east
+    affinity_type: anti_affinity:local
+    is_strict: True
+    state: present
+```
+
+```yaml
+- name: Update a Linode placement group label
+  linode.cloud.placement_group:
+    # id is required to update the label
+    id: 123
+    label: my-pg-updated
+    state: present
+```
+
+```yaml
+- name: Delete a placement group by label
+  linode.cloud.placement_group:
+    label: my-pg
+    state: absent
+```
+
+```yaml
+- name: Delete a placement group by id
+  linode.cloud.placement_group:
+    id: 123
+    state: absent    
+
+```
+
+
+## Parameters
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `id` | <center>`int`</center> | <center>Optional</center> | The unique ID of the placement group.   |
+| `label` | <center>`str`</center> | <center>Optional</center> | The label of the Placement Group. This field can only contain ASCII letters, digits and dashes.   |
+| `region` | <center>`str`</center> | <center>Optional</center> | The region that the placement group is in.   |
+| `affinity_type` | <center>`str`</center> | <center>Optional</center> | The affinity policy for Linodes in a placement group.   |
+| `is_strict` | <center>`bool`</center> | <center>Optional</center> | Whether Linodes must be able to become compliant during assignment.  **(Default: `False`)** |
+
+## Return Values
+
+- `placement_group` - The Placement Group in JSON serialized form.
+
+    - Sample Response:
+        ```json
+        {
+          "id": 123,
+          "label": "my-pg",
+          "region": "eu-west",
+          "affinity_type": "anti_affinity:local",
+          "is_strict": true,
+          "is_compliant": true,
+          "members": [
+            {
+              "linode_id": 123,
+              "is_compliant": true
+            }
+          ]
+        }
+        ```
+    - See the [Linode API response documentation](TBD) for a list of returned fields
+
+

docs/modules/placement_group_info.md

@@ -0,0 +1,59 @@
+# placement_group_info
+
+Get info about a Linode Placement Group.
+
+**:warning: This module makes use of beta endpoints and requires the `api_version` field be explicitly set to `v4beta`.**
+
+- [Minimum Required Fields](#minimum-required-fields)
+- [Examples](#examples)
+- [Parameters](#parameters)
+- [Return Values](#return-values)
+
+## Minimum Required Fields
+| Field       | Type  | Required     | Description                                                                                                                                                                                                              |
+|-------------|-------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `api_token` | `str` | **Required** | The Linode account personal access token. It is necessary to run the module. <br/>It can be exposed by the environment variable `LINODE_API_TOKEN` instead. <br/>See details in [Usage](https://github.com/linode/ansible_linode?tab=readme-ov-file#usage). |
+
+## Examples
+
+```yaml
+- name: Get info about a Linode placement group
+  linode.cloud.placement_group_info: 
+    api_version: v4beta
+    id: 123
+
+```
+
+
+## Parameters
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `id` | <center>`int`</center> | <center>**Required**</center> | The ID of the Placement Group to resolve.   |
+
+## Return Values
+
+- `placement_group` - The returned Placement Group.
+
+    - Sample Response:
+        ```json
+
+        {
+          "id": 123,
+          "label": "test",
+          "region": "eu-west",
+          "affinity_type": "anti_affinity:local",
+          "is_strict": true,
+          "is_compliant": true,
+          "members": [
+            {
+              "linode_id": 123,
+              "is_compliant": true
+            }
+          ]
+        }
+
+        ```
+    - See the [Linode API response documentation](TBD) for a list of returned fields
+
+

docs/modules/placement_group_list.md

@@ -0,0 +1,67 @@
+# placement_group_list
+
+List and filter on Placement Groups.
+
+**:warning: This module makes use of beta endpoints and requires the `api_version` field be explicitly set to `v4beta`.**
+
+- [Minimum Required Fields](#minimum-required-fields)
+- [Examples](#examples)
+- [Parameters](#parameters)
+- [Return Values](#return-values)
+
+## Minimum Required Fields
+| Field       | Type  | Required     | Description                                                                                                                                                                                                              |
+|-------------|-------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `api_token` | `str` | **Required** | The Linode account personal access token. It is necessary to run the module. <br/>It can be exposed by the environment variable `LINODE_API_TOKEN` instead. <br/>See details in [Usage](https://github.com/linode/ansible_linode?tab=readme-ov-file#usage). |
+
+## Examples
+
+```yaml
+- name: List all of Linode placement group for the current account
+  linode.cloud.placement_group_list:
+    api_version: v4beta
+```
+
+
+## Parameters
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `order` | <center>`str`</center> | <center>Optional</center> | The order to list Placement Groups in.  **(Choices: `desc`, `asc`; Default: `asc`)** |
+| `order_by` | <center>`str`</center> | <center>Optional</center> | The attribute to order Placement Groups by.   |
+| [`filters` (sub-options)](#filters) | <center>`list`</center> | <center>Optional</center> | A list of filters to apply to the resulting Placement Groups.   |
+| `count` | <center>`int`</center> | <center>Optional</center> | The number of Placement Groups to return. If undefined, all results will be returned.   |
+
+### filters
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `name` | <center>`str`</center> | <center>**Required**</center> | The name of the field to filter on. Valid filterable fields can be found [here](TBD).   |
+| `values` | <center>`list`</center> | <center>**Required**</center> | A list of values to allow for this field. Fields will pass this filter if at least one of these values matches.   |
+
+## Return Values
+
+- `placement_groups` - The returned Placement Groups.
+
+    - Sample Response:
+        ```json
+        [
+            {
+              "id": 123,
+              "label": "test",
+              "region": "eu-west",
+              "affinity_type": "anti_affinity:local",
+              "is_strict": true,
+              "is_compliant": true,
+              "members": [
+                {
+                  "linode_id": 123,
+                  "is_compliant": true
+                }
+              ]
+            }
+        ]
+        ```
+    - See the [Linode API response documentation](TBD) for a list of returned fields
+
+

plugins/module_utils/doc_fragments/instance.py

@@ -70,7 +70,16 @@
     image: linode/ubuntu22.04
     root_pass: verysecurepassword!!!
     metadata:
-        user_data: myuserdata
+      user_data: myuserdata
+    state: present''', '''
+- name: Create a new Linode instance under a placement group.
+  linode.cloud.instance:
+    label: my-linode
+    type: g6-nanode-1
+    region: us-east
+    placement_group: 
+      id: 123
+      compliant_only: false
     state: present''', '''
 - name: Delete a Linode instance.
   linode.cloud.instance:
@@ -119,7 +128,13 @@
   ],
   "type": "g6-standard-1",
   "updated": "2018-01-01T00:01:01",
-  "watchdog_enabled": true
+  "watchdog_enabled": true,
+  "placement_group": {
+    "id": 123,
+    "label": "test",
+    "affinity_type": "anti_affinity:local",
+    "is_strict": true
+  }
 }''']
 
 result_configs_samples = ['''[

plugins/module_utils/doc_fragments/placement_group.py

@@ -0,0 +1,40 @@
+"""Documentation fragments for the placement_group module"""
+
+specdoc_examples = ['''
+- name: Create a placement group
+  linode.cloud.placement_group:
+    label: my-pg
+    region: us-east
+    affinity_type: anti_affinity:local
+    is_strict: True
+    state: present''', '''
+- name: Update a Linode placement group label
+  linode.cloud.placement_group:
+    # id is required to update the label
+    id: 123
+    label: my-pg-updated
+    state: present''', '''
+- name: Delete a placement group by label
+  linode.cloud.placement_group:
+    label: my-pg
+    state: absent''', '''
+- name: Delete a placement group by id
+  linode.cloud.placement_group:
+    id: 123
+    state: absent    
+''']
+
+result_placement_group_samples = ['''{
+  "id": 123,
+  "label": "my-pg",
+  "region": "eu-west",
+  "affinity_type": "anti_affinity:local",
+  "is_strict": true,
+  "is_compliant": true,
+  "members": [
+    {
+      "linode_id": 123,
+      "is_compliant": true
+    }
+  ]
+}''']