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.

Author: m-strzelczyk

samples/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>

samples/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>

samples/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>

samples/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>

samples/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>

samples/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>

samples/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>
+

samples/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)