chore: Moving GCE API samples from python-docs-samples (b/191786905) (#1429)

Co-authored-by: Anthonios Partheniou <[email protected]>

Author: m-strzelczyk

samples/README.md

@@ -195,6 +195,18 @@ Documentation for the Search API For Shopping in
   </tr>
 </table>
 
+## ![](https://www.google.com/images/icons/product/compute_engine-32.png) Cloud Compute Engine API
+
+Lets you manage the Google Compute Engine instances in your projects.
+
+<table>
+  <tr>
+    <td><a href="compute">samples/compute</a></td>
+    <td>Creates a Google Compute Engine instance to modify a samples image and upload the result
+        to a Cloud Storage bucket, then deletes the instance.</td>
+  </tr>
+</table>
+
 ## ![](https://www.google.com/images/icons/product/cloud_storage-32.png) Cloud Storage API
 
 Lets you store and retrieve potentially-large, immutable data objects.
@@ -397,4 +409,3 @@ Documentation for the YouTube Data API in
     Getting Started with Google Tasks API</a></td>
   </tr>
 </table>
-

samples/compute/README.md

@@ -0,0 +1,199 @@
+# Using the Cloud Client Libraries for Python
+
+This document demonstrates how to use the Cloud Client Libraries for Python for Compute Engine. 
+It describes how to authorize requests and how to create, list, and delete instances. 
+This exercise discusses how to use the `google-api-python-client` library to access Compute Engine 
+resources. You can run this sample from your local machine or on a VM instance, provided that 
+you have authorized the sample correctly.
+
+For a full list of available client libraries, including other Google client libraries and 
+third-party open source libraries, see the [client libraries page](https://cloud.google.com/compute/docs/api/libraries).
+
+To view the full code example with all of the necessary imports, see the [create_instance.py file](create_instance.py).
+
+## Objectives
+
+ * Perform OAuth 2.0 authorization using the `oauth2client` library
+ * Create, list and delete instances using the `google-api-python-client` library
+
+## Costs
+
+This tutorial uses billable components of Google Cloud including Compute Engine.
+
+## Before you begin
+
+1. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.
+   [Go to project selector](https://console.cloud.google.com/projectselector2/home/dashboard).
+1. Make sure that billing is enabled for your cloud project. 
+   [Learn how to confirm that billing is enabled for your project.](https://cloud.google.com/billing/docs/how-to/modify-project)
+1. [Install Google Cloud SDK and `gcloud`](https://cloud.google.com/sdk)
+1. After the SDK is installed, run `gcloud auth application-default login`.
+1. Install the [google-api-python-client](http://github.com/googleapis/google-api-python-client) library. Typically, you can run:
+   
+   ```bash
+   pip install --upgrade google-api-python-client
+   ```
+
+1. Enable the Cloud Storage API.
+   ```bash
+   gcloud services enable storage.googleapis.com
+   ```
+1. [Create a Cloud Storage bucket](https://cloud.google.com/storage/docs/creating-buckets) and note the bucket name for later.
+
+## Authorizing requests
+
+This sample uses OAuth 2.0 authorization. There are many ways to authorize requests using OAuth 2.0,
+but for the example use [application default credentials](https://developers.google.com/accounts/docs/application-default-credentials). This lets you reuse the credentials from 
+the `gcloud` tool if you are running the sample on a local workstation or reuse credentials from a 
+service account if you are running the sample from within Compute Engine or App Engine. You should 
+have installed and authorized the `gcloud` tool in the "Before you begin" section.
+
+Application default credentials are provided in Google API Client Libraries automatically. 
+You just have to build and initialize the API:
+
+```python
+import googleapiclient
+compute = googleapiclient.discovery.build('compute', 'v1')
+```
+
+See the `main()` method in the [create_instance.py](create_instance.py) script, to see how an API
+client is built and used.
+
+## Listing instances
+
+Using `google-api-python-client`, you can list instances by using the `compute.instances().list()` method. 
+You need to provide the project ID and the zone for which you want to list instances. For example:
+
+```python
+def list_instances(compute, project, zone):
+    result = compute.instances().list(project=project, zone=zone).execute()
+    return result['items'] if 'items' in result else None
+```
+
+## Adding an instance
+
+To add an instance, use the `compute.instances().insert()` method and specify the properties of the new 
+instance. These properties are specified in the request body; for details about each property see 
+the [API reference for `instances.insert`](https://cloud.google.com/compute/docs/reference/latest/instances/insert).
+
+At a minimum, your request must provide values for the following properties when you create a new 
+instance:
+
+* Instance name
+* Root persistent disk
+* Machine type
+* Zone
+* Network Interfaces
+
+This sample starts an instance with the following properties in a zone of your choice:
+
+* Machine type: e2-standard-2
+* Root persistent disk: a new persistent disk based on the latest Debian 8 image
+* The Compute Engine default service account with the following scopes:
+  * https://www.googleapis.com/auth/devstorage.read_write, so the instance can read and write files in Cloud Storage
+  * https://www.googleapis.com/auth/logging.write, so the instances logs can upload to Cloud Logging
+* Metadata to specify commands that the instance should execute upon startup
+
+You can see an example of instance creation in the `create_instance` method in [create_instance.py](create_instance.py) file.
+
+### Root persistent disks
+
+All instances must boot from a [root persistent disk](https://cloud.google.com/compute/docs/disks/create-root-persistent-disks).
+The root persistent disk contains all of the necessary files required for starting an instance. 
+When you create a root persistent disk you must select a public image or a custom image to apply to 
+the disk. In the example above, a new root persistent disk is created based on Debian 8 at the same 
+time as the instance. However, it is also possible to create a disk beforehand and attach it to the 
+instance.
+
+To create an instance using your own custom OS image, you need to provide a different URL than 
+the one included in the example. For more information about starting an instance with your own 
+images, see [Creating an instance from a custom image](https://cloud.google.com/compute/docs/instances/create-start-instance#creating_an_instance_from_a_custom_image).
+
+
+
+### Instance metadata
+
+When you create your instance, you might want to include instance metadata such as a [startup script](https://cloud.google.com/compute/docs/startupscript), 
+configuration variables, and SSH keys. In the example above, you used the `metadata` field in your 
+request body to specify a startup script for the instance and some configuration variables as 
+key/values pairs. The [startup-script.sh](startup-script.sh) shows how to read these variables and use them 
+to apply text to an image and upload it to [Cloud Storage](https://cloud.google.com/storage).
+
+## Deleting an Instance
+
+To delete an instance, you need to call the `compute.instances().delete()` method and provide the name, 
+zone, and project ID of the instance to delete. When the `autoDelete` parameter is set to `true` for the 
+boot disk it is also deleted with the instance. This setting is off by default but is 
+useful when your use case calls for disks and instances to be deleted together.
+
+```python
+def delete_instance(compute, project, zone, name):
+    return compute.instances().delete(
+        project=project,
+        zone=zone,
+        instance=name).execute()
+```
+
+## Running the sample
+
+You can run the full sample by downloading the code and running it on the command line. Make sure 
+to download the `create_instance.py` file and the `startup-script.sh` file. To run the sample:
+
+```bash
+python create_instance.py --name [INSTANCE_NAME] --zone [ZONE] [PROJECT_ID] [CLOUD_STORAGE_BUCKET]
+```
+
+where:
+
+* `[INSTANCE_NAME]` is the name of the instance to create.
+* `[ZONE]` is the desired zone for this request.
+* `[PROJECT_ID]` is our project ID.
+* `[CLOUD_STORAGE_BUCKET]` is the name of the bucket you initially set up but without the `gs://` prefix.
+
+For example:
+
+```bash
+python python-example.py --name example-instance --zone us-central1-a example-project my-gcs-bucket
+```
+
+## Waiting for operations to complete
+
+Requests to the Compute Engine API that modify resources such as instances immediately return a 
+response acknowledging your request. The acknowledgement lets you check the status of the requested 
+operation. Operations can take a few minutes to complete, so it's often easier to wait for the 
+operation to complete before continuing. This helper method waits until the operation completes 
+before returning:
+
+```python
+def wait_for_operation(compute, project, zone, operation):
+    print('Waiting for operation to finish...')
+    while True:
+        result = compute.zoneOperations().get(
+            project=project,
+            zone=zone,
+            operation=operation).execute()
+
+        if result['status'] == 'DONE':
+            print("done.")
+            if 'error' in result:
+                raise Exception(result['error'])
+            return result
+
+        time.sleep(1)
+```
+
+When you query per-zone operations, use the `compute.zoneOperations.get()` method. When you query global 
+operations, use the `compute.globalOperations.get()` method. For more information, see zone resources.
+
+## Cleaning up
+
+To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, 
+either delete the project that contains the resources, or keep the project and delete the 
+individual resources.
+
+### Delete your Cloud Storage bucket
+
+To delete a Cloud Storage bucket:
+1. In the Cloud Console, go to the Cloud Storage [Browser page](https://console.cloud.google.com/storage/browser).
+1. Click the checkbox for the bucket that you want to delete.
+1. To delete the bucket, click `Delete`, and then follow the instructions.