check for mtls config and prompt user helpfully

Author: laurafitzgerald

src/codeflare_sdk/ray/cluster/cluster.py

@@ -114,6 +114,15 @@ def _client_verify_tls(self):
 
     @property
     def job_client(self):
+        """
+        Get the Ray Job Submission Client for this cluster.
+        
+        Note: If connecting to a cluster with mTLS enabled, ensure you have called
+        cluster.wait_ready() first to automatically generate TLS certificates.
+        """
+        # Check for certificates before creating client
+        self._check_tls_certs_exist()
+        
         k8client = get_api_client()
         if self._job_submission_client:
             return self._job_submission_client
@@ -538,10 +547,46 @@ def details(self, print_to_console: bool = True) -> RayCluster:
             pretty_print.print_clusters([cluster])
         return cluster
 
+    def _check_tls_certs_exist(self):
+        """
+        Check if TLS certificates exist and print helpful warning if not.
+        
+        This is called by connection methods (cluster_uri, local_client_url, job_client)
+        to help users debug mTLS connection issues.
+        """
+        from codeflare_sdk.common.utils.generate_cert import _get_tls_base_dir
+        from pathlib import Path
+        
+        cert_dir = _get_tls_base_dir() / f"{self.config.name}-{self.config.namespace}"
+        
+        if not cert_dir.exists() or not (cert_dir / "tls.crt").exists():
+            print("\n" + "="*70)
+            print("⚠️  WARNING: TLS Certificates Not Found!")
+            print("="*70)
+            print(f"Expected location: {cert_dir}")
+            print()
+            print("TLS certificates are required for mTLS connections to Ray clusters.")
+            print("Without certificates, your connection will likely fail with a timeout")
+            print("or TLS handshake error.")
+            print()
+            print("To fix this issue:")
+            print("  1. Call cluster.wait_ready() after cluster.apply()")
+            print("     → This automatically generates certificates when cluster is ready")
+            print()
+            print("  2. Or manually generate certificates:")
+            print("     from codeflare_sdk.common.utils import generate_cert")
+            print(f"     generate_cert.generate_tls_cert('{self.config.name}', '{self.config.namespace}')")
+            print(f"     generate_cert.export_env('{self.config.name}', '{self.config.namespace}')")
+            print("="*70 + "\n")
+    
     def cluster_uri(self) -> str:
         """
         Returns a string containing the cluster's URI.
+        
+        Note: If connecting to a cluster with mTLS enabled, ensure you have called
+        cluster.wait_ready() first to automatically generate TLS certificates.
         """
+        self._check_tls_certs_exist()
         return f"ray://{self.config.name}-head-svc.{self.config.namespace}.svc:10001"
 
     def refresh_certificates(self):
@@ -685,7 +730,13 @@ def local_client_url(self):
         Returns:
             str:
                 The Ray client URL based on the ingress domain.
+        
+        Note: If connecting to a cluster with mTLS enabled, ensure you have called
+        cluster.wait_ready() first to automatically generate TLS certificates.
         """
+        # Check if TLS certificates exist and provide helpful warning if not
+        self._check_tls_certs_exist()
+        
         ingress_domain = _get_ingress_domain(self)
         return f"ray://{ingress_domain}"
 

src/codeflare_sdk/ray/cluster/test_cluster.py

@@ -325,6 +325,9 @@ def test_cluster_uris(mocker):
         "kubernetes.client.CustomObjectsApi.list_namespaced_custom_object",
         return_value=get_local_queue("kueue.x-k8s.io", "v1beta1", "ns", "localqueues"),
     )
+    # Mock the TLS cert check to avoid warnings in test output
+    mocker.patch("codeflare_sdk.ray.cluster.cluster.Cluster._check_tls_certs_exist")
+    
     cluster = create_cluster(mocker)
     mocker.patch(
         "kubernetes.client.NetworkingV1Api.list_namespaced_ingress",