From e56daf4d97243289726ebc7c98df04e3492d7aca Mon Sep 17 00:00:00 2001 From: Dazhong Xia Date: Wed, 28 Feb 2024 10:51:57 -0500 Subject: [PATCH] Update docs about credentials --- docs/source/index.rst | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index f490dba6..121419a9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -99,12 +99,24 @@ Several modes of authentication are supported: or container engine) and fetch the credentials automatically from the metadata service. - - if ``token=dict(...)`` or ``token=``, you may supply a token generated by the - gcloud_ utility; this is either a python dictionary, or the name of a file - containing the JSON returned by logging in with the gcloud CLI tool (e.g., - ``~/.config/gcloud/application_default_credentials.json`` or - ``~/.config/gcloud/legacy_credentials//adc.json``) - or any value google ``Credentials`` object. + - if ``token=dict(...)`` or ``token=``, you may supply a token + generated by the gcloud_ utility. This can be + + - a python dictionary + + - the path to a file containing the JSON returned by logging in with the + gcloud CLI tool (e.g., + ``~/.config/gcloud/application_default_credentials.json`` or + ``~/.config/gcloud/legacy_credentials//adc.json``) + + - the path to a service account key + + - a google.auth.credentials.Credentials_ object + + Note that ``~`` will not be automatically expanded to the user home + directory, and must be manually expanded with a utility like + ``os.path.expanduser()``. - you can also generate tokens via Oauth2 in the browser using ``token='browser'``, which gcsfs then caches in a special file, ~/.gcs_tokens, and can subsequently be accessed with ``token='cache'``. @@ -112,6 +124,8 @@ Several modes of authentication are supported: - anonymous only access can be selected using ``token='anon'``, e.g. to access public resources such as 'anaconda-public-data'. +.. _google.auth.credentials.Credentials: https://google-auth.readthedocs.io/en/master/reference/google.auth.credentials.html#google.auth.credentials.Credentials + The acquired session tokens are *not* preserved when serializing the instances, so it is safe to pass them to worker processes on other machines if using in a distributed computation context. If credentials are given by a file path, however,