credentials_gce: Get a token from the Google metadata server

View source: R/credentials_gce.R

credentials_gceR Documentation

Get a token from the Google metadata server


If your code is running on Google Cloud, we can often obtain a token for an attached service account directly from a metadata server. This is more secure than working with an explicit a service account key, as credentials_service_account() does, and is the preferred method of auth for workloads running on Google Cloud.

The most straightforward scenario is when you are working in a VM on Google Compute Engine and it's OK to use the default service account. This should "just work" automatically.

credentials_gce() supports other use cases (such as GKE Workload Identity), but may require some explicit setup, such as:

  • Create a service account, grant it appropriate scopes(s) and IAM roles, attach it to the target resource. This prep work happens outside of R, e.g., in the Google Cloud Console. On the R side, provide the email address of this appropriately configured service account via service_account.

  • Specify details for constructing the root URL of the metadata service:

    • The logical option "gargle.gce.use_ip". If undefined, this defaults to FALSE.

    • The environment variable GCE_METADATA_URL is consulted when "gargle.gce.use_ip" is FALSE. If undefined, the default is

    • The environment variable GCE_METADATA_IP is consulted when "gargle.gce.use_ip" is TRUE. If undefined, the default is ⁠⁠.

  • Change (presumably increase) the timeout for requests to the metadata server via the "gargle.gce.timeout" global option. This timeout is given in seconds and is set to a value (strategy, really) that often works well in practice. However, in some cases it may be necessary to increase the timeout with code such as:

options(gargle.gce.timeout = 3)

For details on specific use cases, such as Google Kubernetes Engine (GKE), see vignette("non-interactive-auth").


  scopes = "",
  service_account = "default",



A character vector of scopes to request. Pick from those listed at

For certain token flows, the "" scope is unconditionally included. This grants permission to retrieve the email address associated with a token; gargle uses this to index cached OAuth tokens. This grants no permission to view or send email and is generally considered a low-value scope.


Name of the GCE service account to use.


Additional arguments passed to all credential functions.


A GceToken() or NULL.

See Also

A related auth flow that can be used on certain non-Google cloud providers is workload identity federation, which is implemented in credentials_external_account().

How to attach a service account to a resource:

Other credential functions: credentials_app_default(), credentials_byo_oauth2(), credentials_external_account(), credentials_service_account(), credentials_user_oauth2(), token_fetch()


## Not run: 

## End(Not run)

gargle documentation built on July 26, 2023, 5:29 p.m.