feat: [KmsInventory] Add support for project level key usage tracking (#8927)

* feat: Add support for project level key usage tracking
docs: Add support for project level key usage tracking

PiperOrigin-RevId: 871667322

Source-Link: googleapis/googleapis@1133adb

Source-Link: googleapis/googleapis-gen@d0121e3
Copy-Tag: eyJwIjoiS21zSW52ZW50b3J5Ly5Pd2xCb3QueWFtbCIsImgiOiJkMDEyMWUzN2JhNWZhOTlmMTJhYjE5Njc1OTI2MzVjMjg5NzIwZDFjIn0=

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: gcf-owl-bot[bot]

KmsInventory/metadata/V1/KeyDashboardService.php

@@ -30,10 +30,16 @@
 
 /**
  * Returns aggregate information about the resources protected by the given
- * Cloud KMS [CryptoKey][google.cloud.kms.v1.CryptoKey]. Only resources within
- * the same Cloud organization as the key will be returned. The project that
- * holds the key must be part of an organization in order for this call to
- * succeed.
+ * Cloud KMS [CryptoKey][google.cloud.kms.v1.CryptoKey]. By default,
+ * summary of resources within the same Cloud organization as the key will be
+ * returned, which requires the KMS organization service account to be
+ * configured(refer
+ * https://docs.cloud.google.com/kms/docs/view-key-usage#required-roles).
+ * If the KMS organization service account is not configured or key's project
+ * is not part of an organization, set
+ * [fallback_scope][google.cloud.kms.inventory.v1.GetProtectedResourcesSummaryRequest.fallback_scope]
+ * to `FALLBACK_SCOPE_PROJECT` to retrieve a summary of protected resources
+ * within the key's project.
  *
  * @param string $formattedName The resource name of the
  *                              [CryptoKey][google.cloud.kms.v1.CryptoKey]. Please see

KmsInventory/metadata/V1/KeyTrackingService.php

@@ -31,11 +31,18 @@
 
 /**
  * Returns metadata about the resources protected by the given Cloud KMS
- * [CryptoKey][google.cloud.kms.v1.CryptoKey] in the given Cloud organization.
+ * [CryptoKey][google.cloud.kms.v1.CryptoKey] in the given Cloud
+ * organization/project.
  *
- * @param string $formattedScope Resource name of the organization.
- *                               Example: organizations/123
- *                               Please see {@see KeyTrackingServiceClient::organizationName()} for help formatting this field.
+ * @param string $formattedScope A scope can be an organization or a project. Resources protected
+ *                               by the crypto key in provided scope will be returned.
+ *
+ *                               The following values are allowed:
+ *
+ *                               * organizations/{ORGANIZATION_NUMBER} (e.g., "organizations/12345678")
+ *                               * projects/{PROJECT_ID} (e.g., "projects/foo-bar")
+ *                               * projects/{PROJECT_NUMBER} (e.g., "projects/12345678")
+ *                               Please see {@see KeyTrackingServiceClient::projectName()} for help formatting this field.
  * @param string $cryptoKey      The resource name of the
  *                               [CryptoKey][google.cloud.kms.v1.CryptoKey].
  */
@@ -74,7 +81,7 @@ function search_protected_resources_sample(string $formattedScope, string $crypt
  */
 function callSample(): void
 {
-    $formattedScope = KeyTrackingServiceClient::organizationName('[ORGANIZATION]');
+    $formattedScope = KeyTrackingServiceClient::projectName('[PROJECT]');
     $cryptoKey = '[CRYPTO_KEY]';
 
     search_protected_resources_sample($formattedScope, $cryptoKey);

KmsInventory/samples/V1/KeyTrackingServiceClient/get_protected_resources_summary.php

@@ -116,6 +116,21 @@ public static function organizationName(string $organization): string
         ]);
     }
 
+    /**
+     * Formats a string containing the fully-qualified path to represent a project
+     * resource.
+     *
+     * @param string $project
+     *
+     * @return string The formatted project resource.
+     */
+    public static function projectName(string $project): string
+    {
+        return self::getPathTemplate('project')->render([
+            'project' => $project,
+        ]);
+    }
+
     /**
      * Formats a string containing the fully-qualified path to represent a
      * project_location_key_ring_crypto_key_crypto_key_version_protectedResourcesSummary
@@ -202,6 +217,7 @@ public static function protectedResourcesSummaryName(
      * The following name formats are supported:
      * Template: Pattern
      * - organization: organizations/{organization}
+     * - project: projects/{project}
      * - projectLocationKeyRingCryptoKeyCryptoKeyVersionProtectedResourcesSummary: projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}/cryptoKeyVersions/{crypto_key_version}/protectedResourcesSummary
      * - projectLocationKeyRingCryptoKeyProtectedResourcesSummary: projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}/protectedResourcesSummary
      * - protectedResourcesSummary: projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}/protectedResourcesSummary
@@ -311,10 +327,16 @@ public function __call($method, $args)
 
     /**
      * Returns aggregate information about the resources protected by the given
-     * Cloud KMS [CryptoKey][google.cloud.kms.v1.CryptoKey]. Only resources within
-     * the same Cloud organization as the key will be returned. The project that
-     * holds the key must be part of an organization in order for this call to
-     * succeed.
+     * Cloud KMS [CryptoKey][google.cloud.kms.v1.CryptoKey]. By default,
+     * summary of resources within the same Cloud organization as the key will be
+     * returned, which requires the KMS organization service account to be
+     * configured(refer
+     * https://docs.cloud.google.com/kms/docs/view-key-usage#required-roles).
+     * If the KMS organization service account is not configured or key's project
+     * is not part of an organization, set
+     * [fallback_scope][google.cloud.kms.inventory.v1.GetProtectedResourcesSummaryRequest.fallback_scope]
+     * to `FALLBACK_SCOPE_PROJECT` to retrieve a summary of protected resources
+     * within the key's project.
      *
      * The async variant is
      * {@see KeyTrackingServiceClient::getProtectedResourcesSummaryAsync()} .
@@ -344,7 +366,8 @@ public function getProtectedResourcesSummary(
 
     /**
      * Returns metadata about the resources protected by the given Cloud KMS
-     * [CryptoKey][google.cloud.kms.v1.CryptoKey] in the given Cloud organization.
+     * [CryptoKey][google.cloud.kms.v1.CryptoKey] in the given Cloud
+     * organization/project.
      *
      * The async variant is
      * {@see KeyTrackingServiceClient::searchProtectedResourcesAsync()} .