docs(samples): Various ways of creating a new disk (#308)

* docs(samples): Samples for various ways to create disks

Co-authored-by: Anthonios Partheniou <partheniou@google.com>
Co-authored-by: Savija Vijayaraghavan <savijatv@google.com>

compute/compute/ingredients/disks/clone_encrypted_disk.py

@@ -0,0 +1,64 @@
+#  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 google.cloud import compute_v1
+
+
+# <INGREDIENT create_disk_from_customer_encrypted_disk>
+def create_disk_from_customer_encrypted_disk(
+        project_id: str, zone: str, disk_name: str, disk_type: str,
+        disk_size_gb: int, disk_link: str,
+        encryption_key: bytes) -> compute_v1.Disk:
+    """
+    Creates a zonal non-boot persistent disk in a project with the copy of data from an existing disk.
+
+    The encryption key must be the same for the source disk and the new disk.
+
+    Args:
+        project_id: project ID or project number of the Cloud project you want to use.
+        zone: name of the zone in which you want to create the disk.
+        disk_name: name of the disk you want to create.
+        disk_type: the type of disk you want to create. This value uses the following format:
+            "zones/{zone}/diskTypes/(pd-standard|pd-ssd|pd-balanced|pd-extreme)".
+            For example: "zones/us-west3-b/diskTypes/pd-ssd"
+        disk_size_gb: size of the new disk in gigabytes
+        disk_link: a link to the disk you want to use as a source for the new disk.
+            This value uses the following format: "projects/{project_name}/zones/{zone}/disks/{disk_name}"
+        encryption_key: customer-supplied encryption key used for encrypting
+            data in the source disk. The data will be encrypted with the same key
+            in the new disk.
+
+    Returns:
+        An attachable copy of an existing disk.
+    """
+    disk_client = compute_v1.DisksClient()
+    disk = compute_v1.Disk()
+    disk.zone = zone
+    disk.size_gb = disk_size_gb
+    disk.source_disk = disk_link
+    disk.type_ = disk_type
+    disk.name = disk_name
+    disk.disk_encryption_key = compute_v1.CustomerEncryptionKey()
+    disk.disk_encryption_key.raw_key = encryption_key
+    operation = disk_client.insert(project=project_id, zone=zone, disk_resource=disk)
+
+    wait_for_extended_operation(operation, "disk creation")
+
+    return disk_client.get(project=project_id, zone=zone, disk=disk_name)
+# </INGREDIENT>

compute/compute/ingredients/disks/clone_encrypted_disk_managed_key.py

@@ -0,0 +1,65 @@
+#  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 google.cloud import compute_v1
+
+
+# <INGREDIENT create_disk_from_kms_encrypted_disk>
+def create_disk_from_kms_encrypted_disk(
+        project_id: str, zone: str, disk_name: str, disk_type: str,
+        disk_size_gb: int, disk_link: str,
+        kms_key_name: str) -> compute_v1.Disk:
+    """
+    Creates a zonal non-boot disk in a project with the copy of data from an existing disk.
+
+    The encryption key must be the same for the source disk and the new disk.
+
+    Args:
+        project_id: project ID or project number of the Cloud project you want to use.
+        zone: name of the zone in which you want to create the disk.
+        disk_name: name of the disk you want to create.
+        disk_type: the type of disk you want to create. This value uses the following format:
+            "zones/{zone}/diskTypes/(pd-standard|pd-ssd|pd-balanced|pd-extreme)".
+            For example: "zones/us-west3-b/diskTypes/pd-ssd"
+        disk_size_gb: size of the new disk in gigabytes
+        disk_link: a link to the disk you want to use as a source for the new disk.
+            This value uses the following format: "projects/{project_name}/zones/{zone}/disks/{disk_name}"
+        kms_key_name: URL of the key from KMS. The key might be from another project, as
+            long as you have access to it. The data will be encrypted with the same key
+            in the new disk. This value uses following format:
+            "projects/{kms_project_id}/locations/{region}/keyRings/{key_ring}/cryptoKeys/{key}"
+
+    Returns:
+        An attachable copy of an existing disk.
+    """
+    disk_client = compute_v1.DisksClient()
+    disk = compute_v1.Disk()
+    disk.zone = zone
+    disk.size_gb = disk_size_gb
+    disk.source_disk = disk_link
+    disk.type_ = disk_type
+    disk.name = disk_name
+    disk.disk_encryption_key = compute_v1.CustomerEncryptionKey()
+    disk.disk_encryption_key.kms_key_name = kms_key_name
+    operation = disk_client.insert(project=project_id, zone=zone, disk_resource=disk)
+
+    wait_for_extended_operation(operation, "disk creation")
+
+    return disk_client.get(project=project_id, zone=zone, disk=disk_name)
+# </INGREDIENT>

compute/compute/ingredients/disks/create_from_snapshot.py

@@ -16,7 +16,6 @@
 # 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 sys
 
 
 from google.cloud import compute_v1

compute/compute/ingredients/disks/create_from_source.py

@@ -0,0 +1,55 @@
+#  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 google.cloud import compute_v1
+
+
+# <INGREDIENT create_disk_from_disk>
+def create_disk_from_disk(project_id: str, zone: str, disk_name: str, disk_type: str,
+                          disk_size_gb: int, disk_link: str) -> compute_v1.Disk:
+    """
+    Creates a disk in a project in a given zone.
+
+    Args:
+        project_id: project ID or project number of the Cloud project you want to use.
+        zone: name of the zone in which you want to create the disk.
+        disk_name: name of the disk you want to create.
+        disk_type: the type of disk you want to create. This value uses the following format:
+            "zones/{zone}/diskTypes/(pd-standard|pd-ssd|pd-balanced|pd-extreme)".
+            For example: "zones/us-west3-b/diskTypes/pd-ssd"
+        disk_size_gb: size of the new disk in gigabytes
+        disk_link: a link to the disk you want to use as a source for the new disk.
+            This value uses the following format: "projects/{project_name}/zones/{zone}/disks/{disk_name}"
+
+    Returns:
+        An attachable disk.
+    """
+    disk_client = compute_v1.DisksClient()
+    disk = compute_v1.Disk()
+    disk.zone = zone
+    disk.size_gb = disk_size_gb
+    disk.source_disk = disk_link
+    disk.type_ = disk_type
+    disk.name = disk_name
+    operation = disk_client.insert(project=project_id, zone=zone, disk_resource=disk)
+
+    wait_for_extended_operation(operation, "disk creation")
+
+    return disk_client.get(project=project_id, zone=zone, disk=disk_name)
+# </INGREDIENT>

compute/compute/ingredients/disks/create_kms_encrypted_disk.py

@@ -0,0 +1,70 @@
+#  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
+
+from google.cloud import compute_v1
+
+
+# <INGREDIENT create_kms_encrypted_disk>
+def create_kms_encrypted_disk(project_id: str, zone: str, disk_name: str, disk_type: str,
+                              disk_size_gb: int, kms_key_name: str,
+                              disk_link: Optional[str] = None, image_link: Optional[str] = None) -> compute_v1.Disk:
+    """
+    Creates a zonal disk in a project. If you do not provide values for disk_link or image_link,
+    an empty disk will be created.
+
+    Args:
+        project_id: project ID or project number of the Cloud project you want to use.
+        zone: name of the zone in which you want to create the disk.
+        disk_name: name of the disk you want to create.
+        disk_type: the type of disk you want to create. This value uses the following format:
+            "zones/{zone}/diskTypes/(pd-standard|pd-ssd|pd-balanced|pd-extreme)".
+            For example: "zones/us-west3-b/diskTypes/pd-ssd"
+        disk_size_gb: size of the new disk in gigabytes
+        kms_key_name: URL of the key from KMS. The key might be from another project, as
+            long as you have access to it. The data will be encrypted with the same key
+            in the new disk. This value uses following format:
+            "projects/{kms_project_id}/locations/{region}/keyRings/{key_ring}/cryptoKeys/{key}"
+        disk_link: a link to the disk you want to use as a source for the new disk.
+            This value uses the following format: "projects/{project_name}/zones/{zone}/disks/{disk_name}"
+        image_link: a link to the image you want to use as a source for the new disk.
+            This value uses the following format: "projects/{project_name}/global/images/{image_name}"
+
+    Returns:
+        An attachable disk.
+    """
+    disk_client = compute_v1.DisksClient()
+    disk = compute_v1.Disk()
+    disk.zone = zone
+    disk.size_gb = disk_size_gb
+    if disk_link:
+        disk.source_disk = disk_link
+    if image_link:
+        disk.source_image = image_link
+    disk.type_ = disk_type
+    disk.name = disk_name
+    disk.disk_encryption_key = compute_v1.CustomerEncryptionKey()
+    disk.disk_encryption_key.kms_key_name = kms_key_name
+    operation = disk_client.insert(project=project_id, zone=zone, disk_resource=disk)
+
+    wait_for_extended_operation(operation, "disk creation")
+
+    return disk_client.get(project=project_id, zone=zone, disk=disk_name)
+
+# </INGREDIENT>

compute/compute/ingredients/disks/regional_create_from_source.py

@@ -0,0 +1,68 @@
+#  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 Iterable, Optional
+
+from google.cloud import compute_v1
+
+
+# <INGREDIENT create_regional_disk_from_disk>
+def create_regional_disk(project_id: str, region: str, replica_zones: Iterable[str],
+                         disk_name: str, disk_type: str,
+                         disk_size_gb: int,
+                         disk_link: Optional[str] = None,
+                         snapshot_link: Optional[str] = None) -> compute_v1.Disk:
+    """
+    Creates a regional disk from an existing zonal disk in a given project.
+
+    Args:
+        project_id: project ID or project number of the Cloud project you want to use.
+        region: name of the region in which you want to create the disk.
+        replica_zones: an iterable collection of zone names in which you want to keep
+            the new disks' replicas. One of the replica zones of the clone must match
+            the zone of the source disk.
+        disk_name: name of the disk you want to create.
+        disk_type: the type of disk you want to create. This value uses the following format:
+            "regions/{region}/diskTypes/(pd-standard|pd-ssd|pd-balanced|pd-extreme)".
+            For example: "regions/us-west3/diskTypes/pd-ssd"
+        disk_size_gb: size of the new disk in gigabytes
+        disk_link: a link to the disk you want to use as a source for the new disk.
+            This value uses the following format: "projects/{project_name}/zones/{zone}/disks/{disk_name}"
+        snapshot_link: a link to the snapshot you want to use as a source for the new disk.
+            This value uses the following format: "projects/{project_name}/global/snapshots/{snapshot_name}"
+
+    Returns:
+        An attachable regional disk.
+    """
+    disk_client = compute_v1.RegionDisksClient()
+    disk = compute_v1.Disk()
+    disk.replica_zones = replica_zones
+    disk.size_gb = disk_size_gb
+    if disk_link:
+        disk.source_disk = disk_link
+    if snapshot_link:
+        disk.source_snapshot = snapshot_link
+    disk.type_ = disk_type
+    disk.region = region
+    disk.name = disk_name
+    operation = disk_client.insert(project=project_id, region=region, disk_resource=disk)
+
+    wait_for_extended_operation(operation, "disk creation")
+
+    return disk_client.get(project=project_id, region=region, disk=disk_name)
+# </INGREDIENT>

compute/compute/ingredients/disks/regional_delete.py

@@ -0,0 +1,39 @@
+#  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
+import sys
+from typing import NoReturn
+
+from google.cloud import compute_v1
+
+
+# <INGREDIENT delete_regional_disk>
+def delete_regional_disk(project_id: str, region: str, disk_name: str) -> NoReturn:
+    """
+    Deletes a disk from a project.
+
+    Args:
+        project_id: project ID or project number of the Cloud project you want to use.
+        region:name of the region where the disk is located.
+        disk_name: name of the disk that you want to delete.
+    """
+    disk_client = compute_v1.RegionDisksClient()
+    operation = disk_client.delete(project=project_id, region=region, disk=disk_name)
+    wait_for_extended_operation(operation, "regional disk deletion")
+    return
+# </INGREDIENT>

compute/compute/recipes/disks/clone_encrypted_disk.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_disk_clone_encrypted_disk>
+# <IMPORTS/>
+
+# <INGREDIENT wait_for_extended_operation />
+
+# <INGREDIENT create_disk_from_customer_encrypted_disk />
+
+# </REGION compute_disk_clone_encrypted_disk>