Add TPC (Trusted Partner Cloud) guidance for Compute SSH

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``.

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

providers/google/src/airflow/providers/google/cloud/hooks/compute_ssh.py

@@ -76,17 +76,35 @@ 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
     :param project_id: The project ID of the remote instance
     :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.