From 468e1785a2323c3d91dcdc9420a5882586400bca Mon Sep 17 00:00:00 2001 From: Wang Guan Date: Sun, 2 Jun 2024 03:26:41 +0900 Subject: [PATCH] doc: explain GCS authentication options (#4671) --- core/src/services/gcs/docs.md | 30 +++++++++++++++++++++++++----- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/core/src/services/gcs/docs.md b/core/src/services/gcs/docs.md index 83e227e4d256..d818b6bbafef 100644 --- a/core/src/services/gcs/docs.md +++ b/core/src/services/gcs/docs.md @@ -18,12 +18,32 @@ This service can be used to: - `root`: Set the work directory for backend - `bucket`: Set the container name for backend - `endpoint`: Customizable endpoint setting -- `credential`: Credentials string for GCS service OAuth2 authentication -- `credential_path`: Local path to credentials file for GCS service OAuth2 authentication +- `credential`: Service Account or External Account JSON, in base64 +- `credential_path`: local path to Service Account or External Account JSON file +- `service_account`: name of Service Account - `predefined_acl`: Predefined ACL for GCS - `default_storage_class`: Default storage class for GCS -Refer to public API docs for more information. +Refer to public API docs for more information. For authentication related options, read on. + +## Options to authenticate to GCS + +OpenDAL supports the following authentication options: + +1. Provide a base64-ed JSON key string with `credential` +2. Provide a JSON key file at explicit path with `credential_path` +3. Provide a JSON key file at implicit path + - `GcsBackend` will attempt to load Service Account key from [ADC well-known places](https://cloud.google.com/docs/authentication/application-default-credentials). +4. Fetch access token from [VM metadata](https://cloud.google.com/docs/authentication/rest#metadata-server) + - Only works when running inside Google Cloud. + - If a non-default Service Account name is required, set with `service_account`. Otherwise, nothing need to be set. +5. A custom `TokenLoader` via `GcsBuilder.customed_token_loader()` + +Notes: + +- When a Service Account key is provided, it will be used to create access tokens (VM metadata will not be used). +- Explicit Service Account key, in json or path, always take precedence over ADC-defined key paths. +- Due to [limitation in GCS](https://cloud.google.com/storage/docs/authentication/signatures#signing-process), a private key is required to create Pre-signed URL. Currently, OpenDAL only supports Service Account key. ## Example @@ -44,8 +64,8 @@ async fn main() -> Result<()> { // set the working directory root for GCS // all operations will happen within it builder.root("/path/to/dir"); - // set the credentials string of service account - builder.credential("service account credential"); + // set the credentials with service account + builder.credential("service account JSON in base64"); // set the predefined ACL for GCS builder.predefined_acl("publicRead"); // set the default storage class for GCS