docs(samples): Adding samples for image related operations (#277)

Samples for the [Create, delete, and deprecate custom images](https://cloud.google.com/compute/docs/images/create-delete-deprecate-private-images) page.

compute/compute/ingredients/images/create.py

@@ -17,10 +17,11 @@
 # folder for complete code samples that are ready to be used.
 # Disabling flake8 for the ingredients file, as it would fail F821 - undefined name check.
 # flake8: noqa
-import time
 
-from google.cloud import compute_v1
 import warnings
+from typing import Optional
+
+from google.cloud import compute_v1
 
 # <INGREDIENT create_image>
 STOPPED_MACHINE_STATUS = (
@@ -29,8 +30,8 @@
 )
 
 
-def create_image(project_id: str, zone: str, source_disk_name: str, image_name: str,
-                 storage_location: str = None, force_create: bool = False) -> compute_v1.Image:
+def create_image_from_disk(project_id: str, zone: str, source_disk_name: str, image_name: str,
+                           storage_location: Optional[str] = None, force_create: bool = False) -> compute_v1.Image:
     """
     Creates a new disk image.
 
@@ -44,6 +45,9 @@ def create_image(project_id: str, zone: str, source_disk_name: str, image_name:
             source location.
         force_create: create the image even if the source disk is attached to a
             running instance.
+
+    Returns:
+        An Image object.
     """
     image_client = compute_v1.ImagesClient()
     disk_client = compute_v1.DisksClient()
@@ -77,7 +81,7 @@ def create_image(project_id: str, zone: str, source_disk_name: str, image_name:
 
     operation = image_client.insert(project=project_id, image_resource=image)
 
-    wait_for_extended_operation(operation, "image creation")
+    wait_for_extended_operation(operation, "image creation from disk")
 
     return image_client.get(project=project_id, image=image_name)
 # </INGREDIENT>

compute/compute/ingredients/images/create_from_image.py

@@ -0,0 +1,69 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+
+# This is an ingredient file. It is not meant to be run directly. Check the samples/snippets
+# folder for complete code samples that are ready to be used.
+# Disabling flake8 for the ingredients file, as it would fail F821 - undefined name check.
+# flake8: noqa
+from typing import Optional, Iterable
+
+from google.cloud import compute_v1
+
+
+# <INGREDIENT create_image_from_image>
+def create_image_from_image(project_id: str, source_image_name: str, image_name: str,
+                            source_project_id: Optional[str] = None,
+                            guest_os_features: Optional[Iterable[str]] = None,
+                            storage_location: Optional[str] = None) -> compute_v1.Image:
+    """
+    Creates a copy of another image.
+
+    Args:
+        project_id: project ID or project number of the Cloud project you want to place your new image in.
+        source_image_name: name of the image you want to copy.
+        image_name: name of the image you want to create.
+        source_project_id: name of the project that hosts the source image. If left unset, it's assumed to equal
+            the `project_id`.
+        guest_os_features: an iterable collection of guest features you want to enable for the bootable image.
+            Learn more about Guest OS features here:
+            https://cloud.google.com/compute/docs/images/create-delete-deprecate-private-images#guest-os-features
+        storage_location: the storage location of your image. For example, specify "us" to store the image in the
+            `us` multi-region, or "us-central1" to store it in the `us-central1` region. If you do not make a selection,
+             Compute Engine stores the image in the multi-region closest to your image's source location.
+
+    Returns:
+        An Image object.
+    """
+    if source_project_id is None:
+        source_project_id = project_id
+
+    image_client = compute_v1.ImagesClient()
+    src_image = image_client.get(project=source_project_id, image=source_image_name)
+
+    image = compute_v1.Image()
+    image.name = image_name
+    image.source_image = src_image.self_link
+    if storage_location:
+        image.storage_locations = [storage_location]
+
+    if guest_os_features:
+        image.guest_os_features = [compute_v1.GuestOsFeature(type_=feature) for feature in guest_os_features]
+
+    operation = image_client.insert(project=project_id, image_resource=image)
+
+    wait_for_extended_operation(operation, "image creation from image")
+
+    return image_client.get(project=project_id, image=image_name)
+# </INGREDIENT>

compute/compute/ingredients/images/create_from_snapshot.py

@@ -0,0 +1,71 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+
+# This is an ingredient file. It is not meant to be run directly. Check the samples/snippets
+# folder for complete code samples that are ready to be used.
+# Disabling flake8 for the ingredients file, as it would fail F821 - undefined name check.
+# flake8: noqa
+from typing import Optional, Iterable
+
+from google.cloud import compute_v1
+
+
+# <INGREDIENT create_image_from_snapshot>
+def create_image_from_snapshot(project_id: str, source_snapshot_name: str, image_name: str,
+                               source_project_id: Optional[str] = None,
+                               guest_os_features: Optional[Iterable[str]] = None,
+                               storage_location: Optional[str] = None) -> compute_v1.Image:
+    """
+    Creates an image based on a snapshot.
+
+    Args:
+        project_id: project ID or project number of the Cloud project you want to place your new image in.
+        source_snapshot_name: name of the snapshot you want to use as a base of your image.
+        image_name: name of the image you want to create.
+        source_project_id: name of the project that hosts the source snapshot. If left unset, it's assumed to equal
+            the `project_id`.
+        guest_os_features: an iterable collection of guest features you want to enable for the bootable image.
+            Learn more about Guest OS features here:
+            https://cloud.google.com/compute/docs/images/create-delete-deprecate-private-images#guest-os-features
+        storage_location: the storage location of your image. For example, specify "us" to store the image in the
+            `us` multi-region, or "us-central1" to store it in the `us-central1` region. If you do not make a selection,
+             Compute Engine stores the image in the multi-region closest to your image's source location.
+
+    Returns:
+        An Image object.
+    """
+    if source_project_id is None:
+        source_project_id = project_id
+
+    snapshot_client = compute_v1.SnapshotsClient()
+    image_client = compute_v1.ImagesClient()
+    src_snapshot = snapshot_client.get(project=source_project_id, snapshot=source_snapshot_name)
+
+    image = compute_v1.Image()
+    image.name = image_name
+    image.source_snapshot = src_snapshot.self_link
+
+    if storage_location:
+        image.storage_locations = [storage_location]
+
+    if guest_os_features:
+        image.guest_os_features = [compute_v1.GuestOsFeature(type_=feature) for feature in guest_os_features]
+
+    operation = image_client.insert(project=project_id, image_resource=image)
+
+    wait_for_extended_operation(operation, "image creation from snapshot")
+
+    return image_client.get(project=project_id, image=image_name)
+# </INGREDIENT>

compute/compute/ingredients/images/set_depracation_status.py

@@ -0,0 +1,46 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+
+# This is an ingredient file. It is not meant to be run directly. Check the samples/snippets
+# folder for complete code samples that are ready to be used.
+# Disabling flake8 for the ingredients file, as it would fail F821 - undefined name check.
+# flake8: noqa
+from typing import NoReturn
+
+from google.cloud import compute_v1
+
+
+# <INGREDIENT set_deprecation_status>
+def set_deprecation_status(project_id: str, image_name: str, status: compute_v1.DeprecationStatus.State) -> NoReturn:
+    """
+    Modify the deprecation status of an image.
+
+    Note: Image objects by default don't have the `deprecated` attribute at all unless it's set.
+
+    Args:
+        project_id: project ID or project number of the Cloud project that hosts the image.
+        image_name: name of the image you want to modify
+        status: the status you want to set for the image. Available values are available in
+            `compute_v1.DeprecationStatus.State` enum. Learn more about image deprecation statuses:
+            https://cloud.google.com/compute/docs/images/create-delete-deprecate-private-images#deprecation-states
+    """
+    image_client = compute_v1.ImagesClient()
+    deprecation_status = compute_v1.DeprecationStatus()
+    deprecation_status.state = status.name
+    operation = image_client.deprecate(project=project_id, image=image_name,
+                                       deprecation_status_resource=deprecation_status)
+
+    wait_for_extended_operation(operation, "changing deprecation state of an image")
+# </INGREDIENT>

compute/compute/recipes/images/create_from_image.py

@@ -0,0 +1,22 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+# flake8: noqa
+
+# <REGION compute_images_create_from_image>
+# <IMPORTS/>
+
+# <INGREDIENT wait_for_extended_operation />
+
+# <INGREDIENT create_image_from_image />
+# </REGION compute_images_create_from_image>

compute/compute/recipes/images/create_from_snapshot.py

@@ -0,0 +1,22 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+# flake8: noqa
+
+# <REGION compute_images_create_from_snapshot>
+# <IMPORTS/>
+
+# <INGREDIENT wait_for_extended_operation />
+
+# <INGREDIENT create_image_from_snapshot />
+# </REGION compute_images_create_from_snapshot>

compute/compute/recipes/images/set_deprecation_status.py

@@ -0,0 +1,23 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+# flake8: noqa
+
+# <REGION compute_images_set_deprecation_status>
+# <IMPORTS/>
+
+# <INGREDIENT wait_for_extended_operation />
+
+# <INGREDIENT set_deprecation_status />
+# </REGION compute_images_set_deprecation_status>
+

compute/compute/snippets/images/create.py

@@ -22,8 +22,7 @@
 # [START compute_windows_image_create]
 # [START compute_images_create]
 import sys
-import time
-from typing import Any
+from typing import Any, Optional
 import warnings
 
 from google.api_core.extended_operation import ExtendedOperation
@@ -82,12 +81,12 @@ def wait_for_extended_operation(
 )
 
 
-def create_image(
+def create_image_from_disk(
     project_id: str,
     zone: str,
     source_disk_name: str,
     image_name: str,
-    storage_location: str = None,
+    storage_location: Optional[str] = None,
     force_create: bool = False,
 ) -> compute_v1.Image:
     """
@@ -103,6 +102,9 @@ def create_image(
             source location.
         force_create: create the image even if the source disk is attached to a
             running instance.
+
+    Returns:
+        An Image object.
     """
     image_client = compute_v1.ImagesClient()
     disk_client = compute_v1.DisksClient()
@@ -142,7 +144,7 @@ def create_image(
 
     operation = image_client.insert(project=project_id, image_resource=image)
 
-    wait_for_extended_operation(operation, "image creation")
+    wait_for_extended_operation(operation, "image creation from disk")
 
     return image_client.get(project=project_id, image=image_name)