new: Support IP module to allocate a new IP

Makefile

@@ -91,7 +91,7 @@ delete-e2e-firewall: update-test-submodules
 		echo "$$OUTPUT"; \
 		exit 1; \
 	else \
-		echo "E2E Cloud firewall created successfully."; \
+		echo "E2E Cloud firewall deleted successfully."; \
 	fi
 
 update-test-submodules:

README.md

@@ -30,6 +30,7 @@ Name | Description |
 [linode.cloud.firewall_device](./docs/modules/firewall_device.md)|Manage Linode Firewall Devices.|
 [linode.cloud.image](./docs/modules/image.md)|Manage a Linode Image.|
 [linode.cloud.instance](./docs/modules/instance.md)|Manage Linode Instances, Configs, and Disks.|
+[linode.cloud.ip](./docs/modules/ip.md)|Allocates a new IPv4 Address on your Account. The Linode must be configured to support additional addresses - please Open a support ticket requesting additional addresses before attempting allocation.|
 [linode.cloud.ip_assign](./docs/modules/ip_assign.md)|Assign IPs to Linodes in a given Region.|
 [linode.cloud.ip_rdns](./docs/modules/ip_rdns.md)|Manage a Linode IP address's rDNS.|
 [linode.cloud.ip_share](./docs/modules/ip_share.md)|Manage the Linode shared IPs.|

docs/inventory/instance.rst

@@ -58,7 +58,7 @@ Parameters
 
 
   **strict (type=bool):**
-    \• If :literal:`yes` make invalid entries a fatal error, otherwise skip and continue.
+    \• If \ :literal:`yes`\  make invalid entries a fatal error, otherwise skip and continue.
 
     \• Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.
 
@@ -94,13 +94,13 @@ Parameters
       **default_value (type=str):**
         \• The default value when the host variable's value is an empty string.
 
-        \• This option is mutually exclusive with :literal:`keyed\_groups[].trailing\_separator`.
+        \• This option is mutually exclusive with \ :literal:`keyed\_groups[].trailing\_separator`\ .
 
 
       **trailing_separator (type=bool, default=True):**
-        \• Set this option to :literal:`False` to omit the :literal:`keyed\_groups[].separator` after the host variable when the value is an empty string.
+        \• Set this option to \ :literal:`False`\  to omit the \ :literal:`keyed\_groups[].separator`\  after the host variable when the value is an empty string.
 
-        \• This option is mutually exclusive with :literal:`keyed\_groups[].default\_value`.
+        \• This option is mutually exclusive with \ :literal:`keyed\_groups[].default\_value`\ .
 
 
 

docs/modules/ip.md

@@ -0,0 +1,35 @@
+# ip
+
+Allocates a new IPv4 Address on your Account. The Linode must be configured to support additional addresses - please Open a support ticket requesting additional addresses before attempting allocation.
+
+- [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: Allocate IP to Linode
+  linode.cloud.ip:
+    linode_id: 123
+    public: true
+    type: ipv4
+```
+
+
+## Parameters
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `linode_id` | <center>`int`</center> | <center>**Required**</center> | The ID of a Linode you have access to that this address will be allocated to.   |
+| `public` | <center>`bool`</center> | <center>**Required**</center> | Whether to create a public or private IPv4 address.   |
+| `type` | <center>`str`</center> | <center>**Required**</center> | The type of address you are requesting. Only IPv4 addresses may be allocated through this operation.  **(Choices: `ipv4`)** |
+
+## Return Values
+

plugins/module_utils/doc_fragments/ip.py

@@ -0,0 +1,9 @@
+"""Documentation fragments for the ip module"""
+specdoc_examples = ['''
+- name: Allocate IP to Linode
+  linode.cloud.ip:
+    linode_id: 123
+    public: true
+    type: ipv4''']
+
+result_ip_samples = ['''[{}]''']

plugins/modules/ip.py

@@ -0,0 +1,107 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+"""This module allows users to allocate a new IPv4 Address on their accounts."""
+
+from __future__ import absolute_import, division, print_function
+
+from typing import Any, Optional
+
+import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.ip as docs
+from ansible_collections.linode.cloud.plugins.module_utils.linode_common import (
+    LinodeModuleBase,
+)
+from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import (
+    global_authors,
+    global_requirements,
+)
+from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import (
+    filter_null_values,
+)
+from ansible_specdoc.objects import FieldType, SpecDocMeta, SpecField
+
+spec: dict = {
+    "linode_id": SpecField(
+        type=FieldType.integer,
+        required=True,
+        description=[
+            "The ID of a Linode you have access to "
+            "that this address will be allocated to."
+        ],
+    ),
+    "public": SpecField(
+        type=FieldType.bool,
+        required=True,
+        description=["Whether to create a public or private IPv4 address."],
+    ),
+    "type": SpecField(
+        type=FieldType.string,
+        required=True,
+        choices=["ipv4"],
+        description=[
+            "The type of address you are requesting. "
+            "Only IPv4 addresses may be allocated through this operation."
+        ],
+    ),
+}
+
+SPECDOC_META = SpecDocMeta(
+    description=[
+        "Allocates a new IPv4 Address on your Account. "
+        "The Linode must be configured to support "
+        "additional addresses - "
+        "please Open a support ticket "
+        "requesting additional addresses before attempting allocation.",
+    ],
+    requirements=global_requirements,
+    author=global_authors,
+    options=spec,
+    examples=docs.specdoc_examples,
+    return_values={},
+)
+
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
+
+class Module(LinodeModuleBase):
+    """Module for allocating a new IP"""
+
+    def __init__(self) -> None:
+        self.module_arg_spec = SPECDOC_META.ansible_spec
+        self.results = {
+            "changed": False,
+            "actions": [],
+            "ip": None,
+        }
+        super().__init__(module_arg_spec=self.module_arg_spec)
+
+    def exec_module(self, **kwargs: Any) -> Optional[dict]:
+        """Entrypoint for ip module"""
+        params = filter_null_values(self.module.params)
+        linode_id = params.get("linode_id")
+        public = params.get("public")
+
+        try:
+            ip = self.client.networking.ip_allocate(linode_id, public)
+            self.register_action(
+                f"IP allocation to Linode {linode_id} completed."
+            )
+        except Exception as exc:
+            self.fail(msg=f"failed to allocate IP to Linode {linode_id}: {exc}")
+
+        self.results["ip"] = ip._raw_json
+
+        return self.results
+
+
+def main() -> None:
+    """Constructs and calls the module"""
+    Module()
+
+
+if __name__ == "__main__":
+    main()

tests/integration/targets/ip_basic/tasks/main.yaml

@@ -0,0 +1,46 @@
+- name: ip
+  block:
+    - set_fact:
+        r: "{{ 1000000000 | random }}"
+
+    - name: Create a Linode Instance
+      linode.cloud.instance:
+        label: 'ansible-test-{{ r }}'
+        region: us-southeast
+        type: g6-standard-1
+        image: linode/alpine3.19
+        state: present
+        firewall_id: '{{ firewall_id }}'
+      register: create_instance
+
+    - name: Allocate a new IP to the Linode
+      linode.cloud.ip:
+        linode_id: '{{ create_instance.instance.id }}'
+        public: true
+        type: ipv4
+      register: allocate_ip
+
+    - name: Assert changes
+      assert:
+        that:
+          - allocate_ip.ip.linode_id == create_instance.instance.id
+          - allocate_ip.ip.type == 'ipv4'
+          - allocate_ip.ip.region == create_instance.instance.region
+
+  always:
+    - ignore_errors: true
+      block:
+        - name: Delete instance
+          linode.cloud.instance:
+            label: '{{ create_instance.instance.label }}'
+            state: absent
+
+
+  environment:
+    LINODE_UA_PREFIX: '{{ ua_prefix }}'
+    LINODE_API_TOKEN: '{{ api_token }}'
+    LINODE_API_URL: '{{ api_url }}'
+    LINODE_API_VERSION: '{{ api_version }}'
+    LINODE_CA: '{{ ca_file or "" }}'
+
+