From dc670af82cfebbed4700008d83a114d2f846555c Mon Sep 17 00:00:00 2001 From: Ulada Zakharava Date: Tue, 21 Apr 2026 12:40:18 +0000 Subject: [PATCH] Update Compute SSH docuemntation about TPC --- providers/google/docs/connections/gcp_ssh.rst | 55 +++++++++++++++++++ .../docs/operators/cloud/compute_ssh.rst | 48 ++++++++++++++++ .../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 e598b5dd84d6a..a99574d46e32b 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 869dd00ad8fd4..2201830951c1a 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 f59866230d9f5..ad138c158fca8 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.