GoogleCloudPlatform · dandhlee · Nov 16, 2022 · Jun 6, 2021 · Jun 9, 2021 · Jun 18, 2021
@@ -0,0 +1,53 @@
+# Code samples for the Compute Engine library
+
+In this folder you can find the source code for the code samples used throughout the 
+[public documentation](https://cloud.google.com/compute/docs/) of Google Compute Engine.
+
+The samples can be found in the `snippets` folder, where they are organized to mimic the
+structure of the public documentation. Files that are saved there are generated by the `sgs.py`
+script from pieces found in `ingredients` and `recipes`. This way, one piece of code can be easily
+included in multiple snippets and updating the code requires less work.
+
+## Working with the SGS
+
+SGS (Snippet Generating System) works by scanning the `recipes` folder, finding all files
+and filling them with pieces of code found in `ingredients`. The folder structure of `recipes` is 
+reconstructed in the `snippets` folder.
+
+### Adding new sample
+
+To create a new sample, just prepare a new file in one of the `recipes` subfolders. The SGS will pick it up 
+automatically when you run it, by executing `python3 sgs.py generate` in this (`samples/`) directory.
+
+### Removing/moving a sample
+
+To remove or move a sample, you need to simply modify the `recipes` folder to match your desired structure, then delete
+the generated snippet from the `snippets` directory. The SGS script will create the snippet in the new location next 
+time you run `python3 sgs.py generate`.
+
+### Interacting with GIT
+
+SGS will not interact with Git repository in any way. All changes made by the script need to be committed manually - 
+preferably in the same commit as the update to the source files.
+
+## Preparing an ingredient
+To add a new ingredient, create a new `.py` file with the code you want to later use in the snippets. Mark the beginning
+of the code you want to include with `# <INGREDIENT name>` and the end with `# </INGREDIENT>`. 
+
+Please leave the imports required by this ingredient **OUTSIDE** the area marked with ingredient comments. The SGS 
+script will automatically collect all the required imports and put them in the final snippet in the right place and in
+right order.
+
+## Preparing a recipe
+Each recipe is a file located in the `recipes` folder. It should have the `.py` extension and should be a valid Python 
+script. Each recipe has to have an `# <IMPORTS/>` line and at least one `# <INGREDIENT name/>` line. 
+Apart from those restrictions, the contents of the file can be whatever you want.
+
+The SGS will copy the recipe file to the destination folder in `snippets` and replace the `# <IMPORTS/>` and 
+`# <INGREDIENT name/>` lines with the `import` statements required by the used ingredients and with the ingredient
+body.
+
+### Regions
+You should use `# <REGION region_name>` and `# </REGION region_name>` lines to indicate where start and end
+of a region should be placed in the generated snippet. Those lines will be simply replaced with the proper 
+`START region_name` and `END region_name` lines.
@@ -0,0 +1,13 @@
+#  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.
@@ -0,0 +1,18 @@
+#  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
@@ -0,0 +1,53 @@
+#  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 set_disk_autodelete>
+def set_disk_autodelete(project_id: str, zone: str, instance_name: str, disk_name: str, autodelete: bool) -> NoReturn:
+    """
+    Set the autodelete flag of a disk to given value.
+
+    Args:
+        project_id: project ID or project number of the Cloud project you want to use.
+        zone: name of the zone in which is the disk you want to modify.
+        instance_name: name of the instance the disk is attached to.
+        disk_name: the name of the disk which flag you want to modify.
+        autodelete: the new value of the autodelete flag.
+    """
+    instance_client = compute_v1.InstancesClient()
+    instance = instance_client.get(project=project_id, zone=zone, instance=instance_name)
+
+    for disk in instance.disks:
+        if disk.device_name == disk_name:
+            break
+    else:
+        raise RuntimeError(f"Instance {instance_name} doesn't have a disk named {disk_name} attached.")
+
+    disk.auto_delete = autodelete
+
+    operation = instance_client.update(project=project_id, zone=zone, instance=instance_name, instance_resource=instance)
+
+    wait_for_extended_operation(operation, "disk update")
+    return
+# </INGREDIENT>
@@ -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>
@@ -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>
@@ -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
+import sys
+
+from google.cloud import compute_v1
+
+
+# <INGREDIENT create_empty_disk>
+def create_empty_disk(
+    project_id: str, zone: str, disk_name: str, disk_type: str, disk_size_gb: int
+) -> compute_v1.Disk:
+    """
+    Creates a new empty disk in a project in 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
+
+    Returns:
+        An unattached Disk instance.
+    """
+    disk = compute_v1.Disk()
+    disk.size_gb = disk_size_gb
+    disk.name = disk_name
+    disk.zone = zone
+    disk.type_ = disk_type
+
+    disk_client = compute_v1.DisksClient()
+    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>
@@ -0,0 +1,59 @@
+#  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 google.cloud import compute_v1
+
+
+# <INGREDIENT create_disk_from_image>
+def create_disk_from_image(
+    project_id: str, zone: str, disk_name: str, disk_type: str, disk_size_gb: int, source_image: str
+) -> compute_v1.Disk:
+    """
+    Creates a new disk in a project in given zone using an image as base.
+
+    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
+        source_image: source image to use when creating this disk. You must have read access to this disk. This
+            can be one of the publicly available images or an image from one of your projects.
+            This value uses the following format: "projects/{project_name}/global/images/{image_name}"
+
+    Returns:
+        An unattached Disk instance.
+    """
+    disk = compute_v1.Disk()
+    disk.size_gb = disk_size_gb
+    disk.name = disk_name
+    disk.zone = zone
+    disk.type_ = disk_type
+    disk.source_image = source_image
+
+    disk_client = compute_v1.DisksClient()
+    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>