feat: adding samples for default values (#64)

* feat: adding samples for default values

Featuring the usage report API.

samples/snippets/noxfile.py

@@ -48,8 +48,8 @@
     # to 'BUILD_SPECIFIC_GCLOUD_PROJECT' if you want to opt in using a
     # build specific Cloud project. You can also use your own string
     # to use your own Cloud project.
-    'gcloud_project_env': 'GOOGLE_CLOUD_PROJECT',
-    # 'gcloud_project_env': 'BUILD_SPECIFIC_GCLOUD_PROJECT',
+    # 'gcloud_project_env': 'GOOGLE_CLOUD_PROJECT',
+    'gcloud_project_env': 'BUILD_SPECIFIC_GCLOUD_PROJECT',
     # If you need to use a specific version of pip,
     # change pip_version_override to the string representation
     # of the version number, for example, "20.2.4"

samples/snippets/requirements-test.txt

@@ -1 +1,2 @@
-pytest==6.2.4
+pytest==6.2.4
+google-cloud-storage==1.39.0

samples/snippets/sample_default_values.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python
+
+# Copyright 2021 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.
+"""
+A sample script showing how to handle default values when communicating
+with the Compute Engine API.
+"""
+# [START compute_instances_verify_default_value]
+# [START compute_usage_report_set]
+# [START compute_usage_report_get]
+# [START compute_usage_report_disable]
+from google.cloud import compute_v1
+# [END compute_usage_report_disable]
+# [END compute_usage_report_get]
+# [END compute_usage_report_set]
+
+
+# [START compute_usage_report_set]
+def set_usage_export_bucket(project_id: str, bucket_name: str,
+                            report_name_prefix: str = "") -> None:
+    """
+    Set Compute Engine usage export bucket for the Cloud project.
+    This sample presents how to interpret the default value for the
+    report name prefix parameter.
+
+    Args:
+        project_id: project ID or project number of the project to update.
+        bucket_name: Google Cloud Storage bucket used to store Compute Engine
+            usage reports. An existing Google Cloud Storage bucket is required.
+        report_name_prefix: Prefix of the usage report name which defaults to an empty string
+            to showcase default values behaviour.
+    """
+    usage_export_location = compute_v1.UsageExportLocation(
+        bucket_name=bucket_name,
+        report_name_prefix=report_name_prefix
+    )
+
+    if not report_name_prefix:
+        # Sending an empty value for report_name_prefix results in the
+        # next usage report being generated with the default prefix value
+        # "usage_gce". (ref: https://cloud.google.com/compute/docs/reference/rest/v1/projects/setUsageExportBucket)
+        print("Setting report_name_prefix to empty value causes the report "
+              "to have the default prefix of `usage_gce`.")
+
+    projects_client = compute_v1.ProjectsClient()
+    operation = projects_client.set_usage_export_bucket(
+        project=project_id, usage_export_location_resource=usage_export_location)
+
+    op_client = compute_v1.GlobalOperationsClient()
+    op_client.wait(project=project_id, operation=operation.name)
+# [END compute_usage_report_set]
+
+
+# [START compute_usage_report_get]
+def get_usage_export_bucket(project_id: str) -> compute_v1.UsageExportLocation:
+    """
+    Retrieve Compute Engine usage export bucket for the Cloud project.
+    Replaces the empty value returned by the API with the default value used
+    to generate report file names.
+
+    Args:
+        project_id: project ID or project number of the project to update.
+    Returns:
+        UsageExportLocation object describing the current usage export settings
+        for project project_id.
+    """
+    projects_client = compute_v1.ProjectsClient()
+    project_data = projects_client.get(project=project_id)
+
+    uel = project_data.usage_export_location
+
+    if not uel.bucket_name:
+        # The usage reports are disabled.
+        return uel
+
+    if not uel.report_name_prefix:
+        # Although the server sent the empty string value, the next usage report
+        # generated with these settings still has the default prefix value
+        # "usage_gce". (see https://cloud.google.com/compute/docs/reference/rest/v1/projects/get)
+        print('Report name prefix not set, replacing with default value of '
+              '`usage_gce`.')
+        uel.report_name_prefix = 'usage_gce'
+    return uel
+# [END compute_usage_report_get]
+# [END compute_instances_verify_default_value]
+
+
+# [START compute_usage_report_disable]
+def disable_usage_export(project_id: str) -> None:
+    """
+    Disable Compute Engine usage export bucket for the Cloud Project.
+
+    Args:
+        project_id: project ID or project number of the project to update.
+    """
+    projects_client = compute_v1.ProjectsClient()
+
+    # Updating the setting with None will disable the
+    # usage report generation.
+    operation = projects_client.set_usage_export_bucket(
+        project=project_id, usage_export_location_resource=None)
+
+    op_client = compute_v1.GlobalOperationsClient()
+    op_client.wait(project=project_id, operation=operation.name)
+# [END compute_usage_report_disable]

samples/snippets/test_sample_default_values.py

@@ -0,0 +1,65 @@
+# Copyright 2021 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.
+import typing
+import uuid
+
+import google.auth
+import google.cloud.storage as storage
+import pytest
+
+from sample_default_values import \
+    disable_usage_export, get_usage_export_bucket, set_usage_export_bucket
+
+PROJECT = google.auth.default()[1]
+BUCKET_NAME = "test" + uuid.uuid4().hex[:10]
+TEST_PREFIX = 'some-prefix'
+
+
+@pytest.fixture
+def temp_bucket():
+    storage_client = storage.Client()
+    bucket = storage_client.create_bucket(BUCKET_NAME)
+    yield bucket
+    bucket.delete(force=True)
+
+
+def test_set_usage_export_bucket_default(capsys: typing.Any,
+                                         temp_bucket: storage.Bucket) -> None:
+    set_usage_export_bucket(project_id=PROJECT, bucket_name=temp_bucket.name)
+    uel = get_usage_export_bucket(project_id=PROJECT)
+    assert(uel.bucket_name == temp_bucket.name)
+    assert(uel.report_name_prefix == 'usage_gce')
+    out, _ = capsys.readouterr()
+    assert('default prefix of `usage_gce`.' in out)
+
+    disable_usage_export(project_id=PROJECT)
+    uel = get_usage_export_bucket(project_id=PROJECT)
+    assert(uel.bucket_name == '')
+    assert(uel.report_name_prefix == '')
+
+
+def test_set_usage_export_bucket_custom(capsys: typing.Any,
+                                        temp_bucket: storage.Bucket) -> None:
+    set_usage_export_bucket(project_id=PROJECT, bucket_name=temp_bucket.name,
+                            report_name_prefix=TEST_PREFIX)
+    uel = get_usage_export_bucket(project_id=PROJECT)
+    assert(uel.bucket_name == temp_bucket.name)
+    assert(uel.report_name_prefix == TEST_PREFIX)
+    out, _ = capsys.readouterr()
+    assert('usage_gce' not in out)
+
+    disable_usage_export(project_id=PROJECT)
+    uel = get_usage_export_bucket(project_id=PROJECT)
+    assert(uel.bucket_name == '')
+    assert(uel.report_name_prefix == '')