new: Add support for Metadata-related fields and endpoints (#289)

## 📝 Description

This change adds preemptive support for endpoints and fields introduced
as a part of the Linode Metadata Service.

## ✔️ How to Test

```
tox
```

Author: lgarber-akamai

linode_api4/groups/image.py

@@ -29,7 +29,7 @@ def __call__(self, *filters):
         """
         return self.client._get_and_filter(Image, *filters)
 
-    def create(self, disk, label=None, description=None):
+    def create(self, disk, label=None, description=None, cloud_init=False):
         """
         Creates a new Image from a disk you own.
 
@@ -42,6 +42,8 @@ def create(self, disk, label=None, description=None):
         :type label: str
         :param description: The description for the new Image.
         :type description: str
+        :param cloud_init: Whether this Image supports cloud-init.
+        :type cloud_init: bool
 
         :returns: The new Image.
         :rtype: Image
@@ -56,6 +58,9 @@ def create(self, disk, label=None, description=None):
         if description is not None:
             params["description"] = description
 
+        if cloud_init:
+            params["cloud_init"] = cloud_init
+
         result = self.client.post("/images", data=params)
 
         if not "id" in result:
@@ -68,7 +73,11 @@ def create(self, disk, label=None, description=None):
         return Image(self.client, result["id"], result)
 
     def create_upload(
-        self, label: str, region: str, description: str = None
+        self,
+        label: str,
+        region: str,
+        description: str = None,
+        cloud_init: bool = False,
     ) -> Tuple[Image, str]:
         """
         Creates a new Image and returns the corresponding upload URL.
@@ -81,12 +90,17 @@ def create_upload(
         :type region: str
         :param description: The description for the new Image.
         :type description: str
+        :param cloud_init: Whether this Image supports cloud-init.
+        :type cloud_init: bool
 
         :returns: A tuple containing the new image and the image upload URL.
         :rtype: (Image, str)
         """
         params = {"label": label, "region": region, "description": description}
 
+        if cloud_init:
+            params["cloud_init"] = cloud_init
+
         result = self.client.post("/images/upload", data=drop_null_keys(params))
 
         if "image" not in result:

linode_api4/groups/linode.py

@@ -1,3 +1,4 @@
+import base64
 import os
 
 from linode_api4 import Profile
@@ -245,6 +246,10 @@ def instance_create(
         :param private_ip: Whether the new Instance should have private networking
                            enabled and assigned a private IPv4 address.
         :type private_ip: bool
+        :param metadata: Metadata-related fields to use when creating the new Instance.
+                         The contents of this field can be built using the
+                         :any:`build_instance_metadata` method.
+        :type metadata: dict
 
         :returns: A new Instance object, or a tuple containing the new Instance and
                   the generated password.
@@ -301,6 +306,40 @@ def instance_create(
             return l
         return l, ret_pass
 
+    @staticmethod
+    def build_instance_metadata(user_data=None, encode_user_data=True):
+        """
+        Builds the contents of the ``metadata`` field to be passed into
+        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(
+                "g6-standard-2",
+                "us-east",
+                image="linode/ubuntu22.04",
+                metadata=client.linode.build_instance_metadata(user_data="myuserdata")
+            )
+        :param user_data: User-defined data to provide to the Linode Instance through
+                          the Metadata service.
+        :type user_data: str
+        :param encode_user_data: If true, the provided user_data field will be automatically
+                                 encoded to a valid base64 string. This field should only
+                                 be set to false if the user_data param is already base64-encoded.
+        :type encode_user_data: bool
+        :returns: The built ``metadata`` structure.
+        :rtype: dict
+        """
+        result = {}
+
+        if user_data is not None:
+            result["user_data"] = (
+                base64.b64encode(user_data.encode()).decode()
+                if encode_user_data
+                else user_data
+            )
+
+        return result
+
     def stackscript_create(
         self, label, script, images, desc=None, public=False, **kwargs
     ):

linode_api4/objects/image.py

@@ -25,4 +25,5 @@ class Image(Base):
         "vendor": Property(),
         "size": Property(),
         "deprecated": Property(),
+        "capabilities": Property(),
     }

linode_api4/objects/linode.py

@@ -412,6 +412,7 @@ class Instance(Base):
         "tags": Property(mutable=True),
         "host_uuid": Property(),
         "watchdog_enabled": Property(mutable=True),
+        "has_user_data": Property(),
     }
 
     @property

test/fixtures/images.json

@@ -17,7 +17,8 @@
           "vendor": "Debian",
           "eol": "2026-07-01T04:00:00",
           "expiry": "2026-08-01T04:00:00",
-          "updated": "2020-07-01T04:00:00"
+          "updated": "2020-07-01T04:00:00",
+          "capabilities": []
         },
         {
           "created": "2017-01-01T00:01:01",
@@ -33,7 +34,8 @@
           "vendor": "Ubuntu",
           "eol": "2026-07-01T04:00:00",
           "expiry": "2026-08-01T04:00:00",
-          "updated": "2020-07-01T04:00:00"
+          "updated": "2020-07-01T04:00:00",
+          "capabilities": []
         },
         {
           "created": "2017-01-01T00:01:01",
@@ -49,7 +51,8 @@
           "vendor": "Fedora",
           "eol": "2026-07-01T04:00:00",
           "expiry": "2026-08-01T04:00:00",
-          "updated": "2020-07-01T04:00:00"
+          "updated": "2020-07-01T04:00:00",
+          "capabilities": []
         },
         {
           "created": "2017-08-20T14:01:01",
@@ -65,7 +68,8 @@
           "vendor": null,
           "eol": "2026-07-01T04:00:00",
           "expiry": "2026-08-01T04:00:00",
-          "updated": "2020-07-01T04:00:00"
+          "updated": "2020-07-01T04:00:00",
+          "capabilities": ["cloud-init"]
         }
     ]
-}
+}

test/fixtures/images_private_1337.json

@@ -12,5 +12,6 @@
     "status": "available",
     "type": "manual",
     "updated": "2021-08-14T22:44:02",
-    "vendor": "Debian"
+    "vendor": "Debian",
+    "capabilities": ["cloud-init"]
 }

test/fixtures/images_upload.json

@@ -13,7 +13,8 @@
         "status": "available",
         "type": "manual",
         "updated": "2021-08-14T22:44:02",
-        "vendor": "Debian"
+        "vendor": "Debian",
+        "capabilities": ["cloud-init"]
     },
     "upload_to": "https://linode.com/"
 }

test/unit/linode_client_test.py

@@ -129,6 +129,7 @@ def test_image_create(self):
 
             self.assertIsNotNone(i)
             self.assertEqual(i.id, "private/123")
+            self.assertEqual(i.capabilities[0], "cloud-init")
 
             self.assertEqual(m.call_url, "/images")
 

test/unit/objects/image_test.py

@@ -77,6 +77,7 @@ def test_image_create_upload(self):
         self.assertEqual(image.id, "private/1337")
         self.assertEqual(image.label, "Realest Image Upload")
         self.assertEqual(image.description, "very real image upload.")
+        self.assertEqual(image.capabilities[0], "cloud-init")
 
         self.assertEqual(url, "https://linode.com/")
 
@@ -100,3 +101,33 @@ def put_mock(url: str, data: BinaryIO = None, **kwargs):
         self.assertEqual(image.id, "private/1337")
         self.assertEqual(image.label, "Realest Image Upload")
         self.assertEqual(image.description, "very real image upload.")
+
+    def test_image_create_cloud_init(self):
+        """
+        Test that an image can be created successfully with cloud-init.
+        """
+
+        with self.mock_post("images/private/123") as m:
+            self.client.images.create(
+                "Test Image",
+                "us-southeast",
+                description="very real image upload.",
+                cloud_init=True,
+            )
+
+            self.assertTrue(m.call_data["cloud_init"])
+
+    def test_image_create_upload_cloud_init(self):
+        """
+        Test that an image upload URL can be created successfully with cloud-init.
+        """
+
+        with self.mock_post("images/upload") as m:
+            self.client.images.create_upload(
+                "Test Image",
+                "us-southeast",
+                description="very real image upload.",
+                cloud_init=True,
+            )
+
+            self.assertTrue(m.call_data["cloud_init"])

test/unit/objects/linode_test.py

@@ -387,6 +387,45 @@ def test_create_disk(self):
 
         assert disk.id == 12345
 
+    def test_instance_create_with_user_data(self):
+        """
+        Tests that the metadata field is populated on Linode create.
+        """
+
+        with self.mock_post("linode/instances/123") as m:
+            self.client.linode.instance_create(
+                "g6-nanode-1",
+                "us-southeast",
+                metadata=self.client.linode.build_instance_metadata(
+                    user_data="cool"
+                ),
+            )
+
+            self.assertEqual(
+                m.call_data,
+                {
+                    "region": "us-southeast",
+                    "type": "g6-nanode-1",
+                    "metadata": {"user_data": "Y29vbA=="},
+                },
+            )
+
+    def test_build_instance_metadata(self):
+        """
+        Tests that the metadata field is built correctly.
+        """
+        self.assertEqual(
+            self.client.linode.build_instance_metadata(user_data="cool"),
+            {"user_data": "Y29vbA=="},
+        )
+
+        self.assertEqual(
+            self.client.linode.build_instance_metadata(
+                user_data="cool", encode_user_data=False
+            ),
+            {"user_data": "cool"},
+        )
+
 
 class DiskTest(ClientBaseCase):
     """