gcloud: Mon Oct 23 11:10:08 UTC 2023

gcloud/alpha/storage/sign-url

@@ -4,10 +4,10 @@ NAME
 
 SYNOPSIS
     gcloud alpha storage sign-url URL [URL ...]
-        --private-key-file=PRIVATE_KEY_FILE
         [--duration=DURATION, -d DURATION; default=3600]
         [--headers=[KEY=VALUE,...]]
         [--http-verb=HTTP_VERB, -m HTTP_VERB; default="GET"]
+        [--private-key-file=PRIVATE_KEY_FILE]
         [--private-key-password=PRIVATE_KEY_PASSWORD, -p PRIVATE_KEY_PASSWORD]
         [--query-params=[KEY=VALUE,...]] [--region=REGION, -r REGION]
         [GCLOUD_WIDE_FLAG ...]
@@ -15,7 +15,10 @@ SYNOPSIS
 DESCRIPTION
     (ALPHA) gcloud alpha storage sign-url will generate a signed URL that
     embeds authentication data so the URL can be used by someone who does not
-    have a Google account. Please see the Signed URLs documentation
+    have a Google account. Use the global --impersonate-service-account flag to
+    specify the service account that will be used to sign the specified URL or
+    authenticate with a service account directly. Otherwise, a service account
+    key is required. Please see the Signed URLs documentation
     (https://cloud.google.com/storage/docs/access-control/signed-urls) for
     background about signed URLs.
 
@@ -26,26 +29,31 @@ DESCRIPTION
     gs://some-bucket/some-directory/.
 
 EXAMPLES
-    To create a signed url for downloading an object valid for 10 minutes:
+    To create a signed url for downloading an object valid for 10 minutes with
+    the credentials of an impersonated service account:
 
         $ gcloud alpha storage sign-url gs://my-bucket/file.txt \
-            --duration=10m --private-key-file=key.json
+            --duration=10m \
+            --impersonate-service-account=sa@my-project.iam.gserviceaccount.\
+        com
 
-    To create a signed url that will bill to my-billing-project:
+    To create a signed url that will bill to my-billing-project when already
+    authenticated as a service account:
 
         $ gcloud alpha storage sign-url gs://my-bucket/file.txt \
-            --query-params=userProject=my-billing-project \
-            --private-key-file=key.json
+            --query-params=userProject=my-billing-project
 
     To create a signed url, valid for one hour, for uploading a plain text file
     via HTTP PUT:
 
         $ gcloud alpha storage sign-url gs://my-bucket/file.txt \
             --http-verb=PUT --duration=1h \
-            --headers=content-type=text/plain --private-key-file=key.json
+            --headers=content-type=text/plain \
+            --impersonate-service-account=sa@my-project.iam.gserviceaccount.\
+        com
 
     To create a signed URL that initiates a resumable upload for a plain text
-    file:
+    file using a private key file:
 
         $ gcloud alpha storage sign-url gs://my-bucket/file.txt \
             --http-verb=POST \
@@ -56,20 +64,19 @@ POSITIONAL ARGUMENTS
      URL [URL ...]
         The URLs to be signed. May contain wildcards.
 
-REQUIRED FLAGS
-     --private-key-file=PRIVATE_KEY_FILE
-        The service account private key used to generate the cryptographic
-        signature for the generated URL. Must be in PKCS12 or JSON format. If
-        encrypted, will prompt for the passphrase used to protect the private
-        key file (default notasecret).
-
-OPTIONAL FLAGS
+FLAGS
      --duration=DURATION, -d DURATION; default=3600
         Specifies the duration that the signed url should be valid for, default
         duration is 1 hour. For example 10s for 10 seconds. See $ gcloud topic
         datetimes for information on duration formats.
 
-        The max duration allowed is 7 days when PRIVATE_KEY_FILE is used.
+        The max duration allowed is 12 hours. This limitation exists because
+        the system-managed key used to sign the URL may not remain valid after
+        12 hours.
+
+        Alternatively, the max duration allowed is 7 days when signing with
+        either the --private-key-file flag or an account that authorized with
+        gcloud auth activate-service-account.
 
      --headers=[KEY=VALUE,...]
         Specifies the headers to be used in the signed request. Possible
@@ -82,8 +89,19 @@ OPTIONAL FLAGS
         session, you will need to specify the x-goog-resumable:start header in
         the request or else signature validation will fail.
 
+     --private-key-file=PRIVATE_KEY_FILE
+        The service account private key used to generate the cryptographic
+        signature for the generated URL. Must be in PKCS12 or JSON format. If
+        encrypted, will prompt for the passphrase used to protect the private
+        key file (default notasecret).
+
+        Note: Service account keys are a security risk if not managed
+        correctly. Review best practices for managing service account keys
+        (https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys)
+        before using this option.
+
      --private-key-password=PRIVATE_KEY_PASSWORD, -p PRIVATE_KEY_PASSWORD
-        Specifies the private key password instead of prompting.
+        Specifies the PRIVATE_KEY_FILE password instead of prompting.
 
      --query-params=[KEY=VALUE,...]
         Specifies the query parameters to be used in the signed request.