This is an automated email from the ASF dual-hosted git repository.
shahar1 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new e80e8946789 Update Compute SSH docuemntation about TPC (#65662)
e80e8946789 is described below
commit e80e894678986cd261e7866bcebdf76ad4cb68ac
Author: Ulada Zakharava <[email protected]>
AuthorDate: Wed Apr 22 16:58:48 2026 +0000
Update Compute SSH docuemntation about TPC (#65662)
---
providers/google/docs/connections/gcp_ssh.rst | 55 ++++++++++++++++++++++
.../google/docs/operators/cloud/compute_ssh.rst | 48 +++++++++++++++++++
.../providers/google/cloud/hooks/compute_ssh.py | 22 ++++++++-
3 files changed, 123 insertions(+), 2 deletions(-)
diff --git a/providers/google/docs/connections/gcp_ssh.rst
b/providers/google/docs/connections/gcp_ssh.rst
index e598b5dd84d..a99574d46e3 100644
--- a/providers/google/docs/connections/gcp_ssh.rst
+++ b/providers/google/docs/connections/gcp_ssh.rst
@@ -25,6 +25,11 @@ The
:class:`~airflow.providers.google.cloud.hooks.compute_ssh.ComputeEngineSSHHo
commands on a remote server using
:class:`~airflow.providers.ssh.operators.ssh.SSHOperator` or transfer
file from/to the remote server using
:class:`~airflow.providers.sftp.operators.sftp.SFTPOperator`.
+.. note::
+
+ ``TPC`` stands for ``Trusted Partner Cloud``. In practice, this means a
deployment that uses a
+ non-default universe domain such as ``apis-tpczero.goog`` instead of
``googleapis.com``.
+
Configuring the Connection
--------------------------
@@ -72,3 +77,53 @@ For example:
use_iap_tunnel=True&\
use_oslogin=False&\
expire_time=4242"
+
+
+Trusted Partner Cloud (TPC) guidance
+------------------------------------
+
+If you are running Airflow in Trusted Partner Cloud (TPC), use the following
configuration guidance for
+Compute Engine SSH.
+
+Recommended configuration for direct SSH
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use instance metadata for SSH keys and connect directly to the instance:
+
+* ``use_oslogin=False``
+* ``use_iap_tunnel=False``
+
+This is the recommended configuration when the instance is reachable directly
and allows TCP traffic on
+port 22.
+
+Recommended configuration for SSH over IAP
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use instance metadata for SSH keys and open the connection through IAP:
+
+* ``use_oslogin=False``
+* ``use_iap_tunnel=True``
+
+This works only when the caller has the IAM permissions needed to open an IAP
tunnel. In Google Cloud
+deployments this is typically the ``IAP-secured Tunnel User`` role
+(``roles/iap.tunnelResourceAccessor``).
+
+Configuration to avoid in TPC
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Do not use Cloud OS Login for Compute Engine SSH in the tested TPC environment:
+
+* ``use_oslogin=True``
+
+In the tested TPC environment, the OS Login SSH flow was not available for
this hook. For users, the
+practical recommendation is to use metadata-managed SSH keys and set
``use_oslogin=False``.
+
+Instance configuration when using metadata-managed SSH keys
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When you use ``use_oslogin=False``:
+
+* do not enable instance metadata ``enable-oslogin=TRUE`` for that SSH path,
+* make sure the instance allows SSH access on port 22,
+* use ``use_iap_tunnel=True`` only when the required IAP IAM permissions are
present, including
+ ``roles/iap.tunnelResourceAccessor``.
diff --git a/providers/google/docs/operators/cloud/compute_ssh.rst
b/providers/google/docs/operators/cloud/compute_ssh.rst
index 869dd00ad8f..2201830951c 100644
--- a/providers/google/docs/operators/cloud/compute_ssh.rst
+++ b/providers/google/docs/operators/cloud/compute_ssh.rst
@@ -43,6 +43,54 @@ To use instance metadata, make sure to set the Cloud OS
Login argument to False
Please note that the target instance must allow tcp traffic on port 22.
+Trusted Partner Cloud (TPC) guidance
+""""""""""""""""""""""""""""""""""""
+
+``TPC`` stands for ``Trusted Partner Cloud``. In these environments, the
practical question for Compute
+Engine SSH is which hook parameters to set.
+
+Use these settings for direct SSH in TPC:
+
+.. code-block:: python
+
+ ComputeEngineSSHHook(
+ ...,
+ use_oslogin=False,
+ use_iap_tunnel=False,
+ )
+
+Use these settings for SSH over IAP in TPC:
+
+.. code-block:: python
+
+ ComputeEngineSSHHook(
+ ...,
+ use_oslogin=False,
+ use_iap_tunnel=True,
+ )
+
+For the IAP case, the caller must also have the IAM permissions required to
open an IAP tunnel. In Google
+Cloud deployments, this is typically the ``IAP-secured Tunnel User`` role
+(``roles/iap.tunnelResourceAccessor``).
+
+Avoid this setting in the tested TPC environment:
+
+.. code-block:: python
+
+ ComputeEngineSSHHook(
+ ...,
+ use_oslogin=True,
+ )
+
+In the tested TPC environment, the OS Login SSH flow was not available for
this hook. For users, the
+practical guidance is to use metadata-managed SSH keys and set
``use_oslogin=False``.
+
+When you use metadata-managed SSH keys in TPC:
+
+* set ``use_oslogin=False``,
+* do not enable instance metadata ``enable-oslogin=TRUE`` for that SSH path,
+* set ``use_iap_tunnel=True`` only when the required IAP IAM permissions are
present.
+
Below is the code to create the operator:
.. exampleinclude::
/../../google/tests/system/google/cloud/compute/example_compute_ssh.py
diff --git
a/providers/google/src/airflow/providers/google/cloud/hooks/compute_ssh.py
b/providers/google/src/airflow/providers/google/cloud/hooks/compute_ssh.py
index f59866230d9..ad138c158fc 100644
--- a/providers/google/src/airflow/providers/google/cloud/hooks/compute_ssh.py
+++ b/providers/google/src/airflow/providers/google/cloud/hooks/compute_ssh.py
@@ -76,6 +76,20 @@ class ComputeEngineSSHHook(SSHHook):
"""
Hook to connect to a remote instance in compute engine.
+ This hook supports two SSH key-management flows:
+
+ * Cloud OS Login when ``use_oslogin=True``
+ * instance metadata SSH keys when ``use_oslogin=False``
+
+ In Trusted Partner Cloud (TPC) environments, the recommended setup is to
use instance metadata SSH keys:
+
+ * ``use_oslogin=False`` and ``use_iap_tunnel=False`` for direct SSH
+ * ``use_oslogin=False`` and ``use_iap_tunnel=True`` for SSH over IAP
+
+ In a tested TPC environment, the OS Login SSH flow was not available for
this hook. Since this hook uses
+ OS Login SSH-key management when ``use_oslogin=True``, that setting should
be avoided there unless the
+ target environment explicitly supports OS Login SSH.
+
:param instance_name: The name of the Compute Engine instance
:param zone: The zone of the Compute Engine instance
:param user: The name of the user on which the login attempt will be made
@@ -83,10 +97,14 @@ class ComputeEngineSSHHook(SSHHook):
:param gcp_conn_id: The connection id to use when fetching connection info
:param hostname: The hostname of the target instance. If it is not passed,
it will be detected
automatically.
- :param use_iap_tunnel: Whether to connect through IAP tunnel
+ :param use_iap_tunnel: Whether to connect through IAP tunnel. In TPC
environments this can work with
+ metadata-managed SSH keys, but it requires the IAM permissions needed
to open an IAP tunnel. In
+ Google Cloud deployments, this is typically the ``IAP-secured Tunnel
User`` role
+ (``roles/iap.tunnelResourceAccessor``).
:param use_internal_ip: Whether to connect using internal IP
:param use_oslogin: Whether to manage keys using OsLogin API. If false,
- keys are managed using instance metadata
+ keys are managed using instance metadata. In tested TPC environments,
set this to ``False`` and use
+ metadata-managed SSH keys instead.
:param expire_time: The maximum amount of time in seconds before the
private key expires
:param gcp_conn_id: The connection id to use when fetching connection
information
:param max_retries: Maximum number of retries the process will try to
establish connection to instance.
