feat: honor NO_GCE_CHECK environment variable (#1610)

0x2b3bfa0 · parthea · chalmerlowe · web-flow · commit 383c9827536d · 2026-01-09T14:06:11.000-05:00
Currently, `google.auth.default()` always attempts to authenticate using the Google Compute Engine (GCE) metadata service as a fallback. There is no easy way to prevent this behavior, leading to unnecessary delays and unhelpful exceptions, particularly in cases where GCE-based authentication is pointless or undesired. This pull request introduces a `NO_GCE_CHECK` environment variable, allowing users to explicitly skip GCE metadata service authentication. This implementation mirrors `NO_GCE_CHECK` in [googleapis/google-auth-library-java](https://github.com/googleapis/google-auth-library-java/blob/f154edb3d8503d29f0020b6904dfa40e034ded93/README.md?plain=1#L106-L119): > _The following are searched (in order) to find the Application Default Credentials:_ > > [...] > > 5. Google Compute Engine built-in credentials > - Skip this check by setting the environment variable `NO_GCE_CHECK=true` > [!NOTE] > Other clouds also provide similar environment variables, such as `AWS_EC2_METADATA_DISABLED` on AWS. This change is also tangentially related to the following pull requests: - #1488 - #1481 --------- Co-authored-by: Anthonios Partheniou <partheniou@google.com> Co-authored-by: Chalmer Lowe <chalmerlowe@google.com>
diff --git a/google/auth/compute_engine/_metadata.py b/google/auth/compute_engine/_metadata.py
@@ -101,6 +101,10 @@ def _get_metadata_ip_root(use_mtls: bool):
 except ValueError:  # pragma: NO COVER
     _METADATA_DEFAULT_TIMEOUT = 3
 
+# This is used to disable checking for the GCE metadata server and directly
+# assuming it's not available.
+_NO_GCE_CHECK = os.getenv(environment_vars.NO_GCE_CHECK) == "true"
+
 # Detect GCE Residency
 _GOOGLE = "Google"
 _GCE_PRODUCT_NAME_FILE = "/sys/class/dmi/id/product_name"
@@ -116,6 +120,9 @@ def is_on_gce(request):
     Returns:
         bool: True if the code runs on Google Compute Engine, False otherwise.
     """
+    if _NO_GCE_CHECK:
+        return False
+
     if ping(request):
         return True
 
diff --git a/google/auth/environment_vars.py b/google/auth/environment_vars.py
@@ -60,6 +60,12 @@
 """Environment variable providing an alternate ip:port to be used for ip-only
 GCE metadata requests."""
 
+NO_GCE_CHECK = "NO_GCE_CHECK"
+"""Environment variable controlling whether to check if running on GCE or not.
+
+The default value is false. Users have to explicitly set this value to true
+in order to disable the GCE check."""
+
 GCE_METADATA_MTLS_MODE = "GCE_METADATA_MTLS_MODE"
 """Environment variable controlling the mTLS behavior for GCE metadata requests.
 
diff --git a/tests/compute_engine/test__metadata.py b/tests/compute_engine/test__metadata.py
@@ -108,6 +108,20 @@ def test_is_on_gce_ping_success():
     assert _metadata.is_on_gce(request)
 
 
+def test_is_on_gce_no_gce_check():
+    request = make_request("", headers=_metadata._METADATA_HEADERS)
+
+    os.environ[environment_vars.NO_GCE_CHECK] = "true"
+    importlib.reload(_metadata)
+
+    try:
+        assert not _metadata.is_on_gce(request)
+        assert request.call_count == 0
+    finally:
+        del os.environ[environment_vars.NO_GCE_CHECK]
+        importlib.reload(_metadata)
+
+
 @mock.patch("os.name", new="nt")
 def test_is_on_gce_windows_success():
     request = make_request("", headers={_metadata._METADATA_FLAVOR_HEADER: "meep"})
