added describe cluster cmd (#278)

Co-authored-by: Mohamed Zeidan <[email protected]>

Author: mohamedzeidan2021

src/sagemaker/hyperpod/cli/commands/cluster.py

@@ -77,6 +77,8 @@
     _hyperpod_telemetry_emitter,
 )
 from sagemaker.hyperpod.common.telemetry.constants import Feature
+from sagemaker.hyperpod.cli.utils import convert_datetimes
+from sagemaker_core.main.resources import Cluster
 
 RATE_LIMIT = 4
 RATE_LIMIT_PERIOD = 1  # 1 second
@@ -684,6 +686,75 @@ def get_cluster_context(
         sys.exit(1)
 
 
+@click.command("cluster")
+@click.argument("cluster-name", required=True)
+@click.option("--region", help="AWS region")
+@click.option("--debug", is_flag=True, help="Enable debug logging")
+@_hyperpod_telemetry_emitter(Feature.HYPERPOD_CLI, "describe_cluster_cli")
+def describe_cluster(cluster_name: str, debug: bool, region: str) -> None:
+    """Describe the status of a HyperPod cluster.
+    Shows detailed information about a SageMaker HyperPod cluster including its current status,
+    instance groups, orchestrator details, and configuration.
+    Usage Examples
+          # Describe a cluster
+          hyp describe cluster my-cluster-name
+          # Describe with specific region
+          hyp describe cluster my-cluster-name --region us-west-2
+    """
+    if debug:
+        set_logging_level(logger, logging.DEBUG)
+
+    try:
+        botocore_config = botocore.config.Config(
+            user_agent_extra=get_user_agent_extra_suffix()
+        )
+        session = boto3.Session(region_name=region) if region else boto3.Session()
+        sm_client = get_sagemaker_client(session, botocore_config)
+
+        # Get cluster details using SageMaker client
+        cluster_dict = sm_client.describe_cluster(ClusterName=cluster_name)
+
+        # Convert datetimes for display
+        cluster_dict = convert_datetimes(cluster_dict)
+
+        logger.debug(f"Describing cluster name: {cluster_name}\ninfo: {json.dumps(cluster_dict, indent=2, default=str)}")
+
+        click.echo(f"📋 Cluster Details for: {cluster_name}")
+
+        # Highlight cluster status
+        cluster_status = cluster_dict.get('ClusterStatus', 'UNKNOWN')
+        click.echo(f"Status: ", nl=False)
+        click.secho(cluster_status)
+
+        table_data = []
+        for key, value in cluster_dict.items():
+            if isinstance(value, (dict, list)):
+                formatted_value = json.dumps(value, indent=2, default=str)
+            else:
+                formatted_value = str(value)
+            table_data.append([key, formatted_value])
+
+        # Only display table if we have data
+        if table_data:
+            click.echo(tabulate(table_data, tablefmt="presto"))
+        else:
+            click.echo("No cluster data available")
+
+    except Exception as e:
+        logger.error(f"Failed to describe cluster: {e}")
+        if debug:
+            logger.exception("Detailed error information:")
+
+        if "does not exist" in str(e) or "not found" in str(e).lower():
+            click.echo(f"❌ Cluster '{cluster_name}' not found")
+        elif "AccessDenied" in str(e):
+            click.echo("❌ Access denied. Check AWS permissions")
+        else:
+            click.echo(f"❌ Error describing cluster: {e}")
+
+        sys.exit(1)
+        
+
 @click.command()
 @click.option("--grafana", is_flag=True, help="Returns Grafana Dashboard URL")
 @click.option("--prometheus", is_flag=True, help="Returns Prometheus Workspace URL")

src/sagemaker/hyperpod/cli/hyp_cli.py

@@ -8,7 +8,7 @@
 from importlib.metadata import version, PackageNotFoundError
 
 from sagemaker.hyperpod.cli.commands.cluster import list_cluster, set_cluster_context, get_cluster_context, \
-    get_monitoring
+    get_monitoring, describe_cluster
 from sagemaker.hyperpod.cli.commands.cluster_stack import create_cluster_stack, describe_cluster_stack, \
     list_cluster_stacks, update_cluster, delete_cluster_stack
 from sagemaker.hyperpod.cli.commands.training import (
@@ -183,6 +183,7 @@ def exec():
 describe.add_command(js_describe)
 describe.add_command(custom_describe)
 describe.add_command(describe_cluster_stack)
+describe.add_command(describe_cluster)
 
 update.add_command(update_cluster)
 

test/unit_tests/test_describe_cluster.py

@@ -0,0 +1,282 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+import unittest
+from unittest.mock import Mock, patch
+from click.testing import CliRunner
+from botocore.exceptions import ClientError
+from sagemaker.hyperpod.cli.commands.cluster import describe_cluster
+
+
+class DescribeClusterTest(unittest.TestCase):
+    def setUp(self):
+        self.runner = CliRunner()
+
+    @patch('sagemaker.hyperpod.cli.commands.cluster.get_sagemaker_client')
+    @patch('sagemaker.hyperpod.cli.commands.cluster.boto3.Session')
+    @patch('sagemaker.hyperpod.cli.commands.cluster.setup_logger')
+    def test_describe_cluster_happy_case(self, mock_setup_logger, mock_session, mock_get_sagemaker_client):
+        """Test successful cluster description with valid cluster name."""
+        # Arrange
+        mock_logger = Mock()
+        mock_setup_logger.return_value = mock_logger
+
+        mock_session_instance = Mock()
+        mock_session.return_value = mock_session_instance
+
+        mock_sm_client = Mock()
+        mock_get_sagemaker_client.return_value = mock_sm_client
+
+        # Mock successful cluster response
+        cluster_response = {
+            "ClusterArn": "arn:aws:sagemaker:us-east-2:123456789012:cluster/test-cluster",
+            "ClusterName": "test-cluster",
+            "ClusterStatus": "InService",
+            "CreationTime": "2023-09-23T14:35:38.223000+00:00",
+            "InstanceGroups": [
+                {
+                    "InstanceGroupName": "controller-group",
+                    "InstanceType": "ml.t3.medium",
+                    "CurrentCount": 1,
+                    "TargetCount": 1
+                }
+            ],
+            "VpcConfig": {
+                "SecurityGroupIds": ["sg-1234567890abcdef0"],
+                "Subnets": ["subnet-1234567890abcdef0"]
+            },
+            "Orchestrator": {
+                "Eks": {
+                    "ClusterArn": "arn:aws:eks:us-east-2:123456789012:cluster/eks-cluster"
+                }
+            }
+        }
+
+        mock_sm_client.describe_cluster.return_value = cluster_response
+
+        # Act
+        result = self.runner.invoke(describe_cluster, ["test-cluster"])
+
+        # Assert
+        assert result.exit_code == 0
+        mock_sm_client.describe_cluster.assert_called_once_with(ClusterName="test-cluster")
+        assert "📋 Cluster Details for: test-cluster" in result.output
+        assert "test-cluster" in result.output
+        assert "InService" in result.output
+
+    @patch('sagemaker.hyperpod.cli.commands.cluster.get_sagemaker_client')
+    @patch('sagemaker.hyperpod.cli.commands.cluster.boto3.Session')
+    @patch('sagemaker.hyperpod.cli.commands.cluster.setup_logger')
+    def test_describe_cluster_with_region_flag(self, mock_setup_logger, mock_session, mock_get_sagemaker_client):
+        """Test cluster description with region flag specified."""
+        # Arrange
+        mock_logger = Mock()
+        mock_setup_logger.return_value = mock_logger
+
+        mock_session_instance = Mock()
+        mock_session.return_value = mock_session_instance
+
+        mock_sm_client = Mock()
+        mock_get_sagemaker_client.return_value = mock_sm_client
+
+        # Mock successful cluster response
+        cluster_response = {
+            "ClusterArn": "arn:aws:sagemaker:us-west-2:123456789012:cluster/test-cluster",
+            "ClusterName": "test-cluster",
+            "ClusterStatus": "InService",
+            "CreationTime": "2023-09-23T14:35:38.223000+00:00",
+            "InstanceGroups": [
+                {
+                    "InstanceGroupName": "worker-group",
+                    "InstanceType": "ml.p4d.24xlarge",
+                    "CurrentCount": 2,
+                    "TargetCount": 2
+                }
+            ]
+        }
+
+        mock_sm_client.describe_cluster.return_value = cluster_response
+
+        # Act
+        result = self.runner.invoke(describe_cluster, ["test-cluster", "--region", "us-west-2"])
+
+        # Assert
+        assert result.exit_code == 0
+
+        # Verify that boto3.Session was called with the correct region
+        mock_session.assert_called_with(region_name="us-west-2")
+        mock_sm_client.describe_cluster.assert_called_once_with(ClusterName="test-cluster")
+        assert "📋 Cluster Details for: test-cluster" in result.output
+        assert "test-cluster" in result.output
+        assert "InService" in result.output
+
+    @patch('sagemaker.hyperpod.cli.commands.cluster.get_sagemaker_client')
+    @patch('sagemaker.hyperpod.cli.commands.cluster.boto3.Session')
+    @patch('sagemaker.hyperpod.cli.commands.cluster.setup_logger')
+    def test_describe_cluster_unknown_cluster_name(self, mock_setup_logger, mock_session, mock_get_sagemaker_client):
+        """Test cluster description with unknown/non-existent cluster name."""
+        # Arrange
+        mock_logger = Mock()
+        mock_setup_logger.return_value = mock_logger
+
+        mock_session_instance = Mock()
+        mock_session.return_value = mock_session_instance
+
+        mock_sm_client = Mock()
+        mock_get_sagemaker_client.return_value = mock_sm_client
+
+        # Mock cluster not found exception
+        error_response = {
+            'Error': {
+                'Code': 'ResourceNotFound',
+                'Message': 'Cluster does not exist'
+            }
+        }
+        mock_sm_client.describe_cluster.side_effect = ClientError(
+            error_response, 'DescribeCluster'
+        )
+
+        # Act
+        result = self.runner.invoke(describe_cluster, ["unknown-cluster"])
+
+        # Assert
+        assert result.exit_code == 1
+        mock_sm_client.describe_cluster.assert_called_once_with(ClusterName="unknown-cluster")
+        # Should show the error message
+        assert "❌ Cluster 'unknown-cluster' not found" in result.output
+
+    @patch('sagemaker.hyperpod.cli.commands.cluster.get_sagemaker_client')
+    @patch('sagemaker.hyperpod.cli.commands.cluster.boto3.Session')
+    @patch('sagemaker.hyperpod.cli.commands.cluster.setup_logger')
+    def test_describe_cluster_access_denied(self, mock_setup_logger, mock_session, mock_get_sagemaker_client):
+        """Test cluster description with access denied error."""
+        # Arrange
+        mock_logger = Mock()
+        mock_setup_logger.return_value = mock_logger
+
+        mock_session_instance = Mock()
+        mock_session.return_value = mock_session_instance
+
+        mock_sm_client = Mock()
+        mock_get_sagemaker_client.return_value = mock_sm_client
+
+        # Mock access denied exception
+        error_response = {
+            'Error': {
+                'Code': 'AccessDenied',
+                'Message': 'User is not authorized to perform this action'
+            }
+        }
+        mock_sm_client.describe_cluster.side_effect = ClientError(
+            error_response, 'DescribeCluster'
+        )
+
+        # Act
+        result = self.runner.invoke(describe_cluster, ["test-cluster"])
+
+        # Assert
+        assert result.exit_code == 1
+        mock_sm_client.describe_cluster.assert_called_once_with(ClusterName="test-cluster")
+        # Should show the access denied message
+        assert "❌ Access denied. Check AWS permissions" in result.output
+
+    @patch('sagemaker.hyperpod.cli.commands.cluster.get_sagemaker_client')
+    @patch('sagemaker.hyperpod.cli.commands.cluster.boto3.Session')
+    @patch('sagemaker.hyperpod.cli.commands.cluster.setup_logger')
+    def test_describe_cluster_generic_error(self, mock_setup_logger, mock_session, mock_get_sagemaker_client):
+        """Test cluster description with generic error."""
+        # Arrange
+        mock_logger = Mock()
+        mock_setup_logger.return_value = mock_logger
+
+        mock_session_instance = Mock()
+        mock_session.return_value = mock_session_instance
+
+        mock_sm_client = Mock()
+        mock_get_sagemaker_client.return_value = mock_sm_client
+
+        # Mock generic exception
+        mock_sm_client.describe_cluster.side_effect = Exception("Unexpected error occurred")
+
+        # Act
+        result = self.runner.invoke(describe_cluster, ["test-cluster"])
+
+        # Assert
+        assert result.exit_code == 1
+        mock_sm_client.describe_cluster.assert_called_once_with(ClusterName="test-cluster")
+        # Should show the generic error message
+        assert "❌ Error describing cluster: Unexpected error occurred" in result.output
+
+    @patch('sagemaker.hyperpod.cli.commands.cluster.get_sagemaker_client')
+    @patch('sagemaker.hyperpod.cli.commands.cluster.boto3.Session')
+    @patch('sagemaker.hyperpod.cli.commands.cluster.setup_logger')
+    def test_describe_cluster_with_debug_flag(self, mock_setup_logger, mock_session, mock_get_sagemaker_client):
+        """Test cluster description with debug flag enabled."""
+        # Arrange
+        mock_logger = Mock()
+        mock_setup_logger.return_value = mock_logger
+
+        mock_session_instance = Mock()
+        mock_session.return_value = mock_session_instance
+
+        mock_sm_client = Mock()
+        mock_get_sagemaker_client.return_value = mock_sm_client
+
+        # Mock successful cluster response
+        cluster_response = {
+            "ClusterArn": "arn:aws:sagemaker:us-east-2:123456789012:cluster/test-cluster",
+            "ClusterName": "test-cluster",
+            "ClusterStatus": "InService"
+        }
+
+        mock_sm_client.describe_cluster.return_value = cluster_response
+
+        # Act
+        result = self.runner.invoke(describe_cluster, ["test-cluster", "--debug"])
+
+        # Assert
+        assert result.exit_code == 0
+        mock_sm_client.describe_cluster.assert_called_once_with(ClusterName="test-cluster")
+        assert "📋 Cluster Details for: test-cluster" in result.output
+
+    @patch('sagemaker.hyperpod.cli.commands.cluster.get_sagemaker_client')
+    @patch('sagemaker.hyperpod.cli.commands.cluster.boto3.Session')
+    @patch('sagemaker.hyperpod.cli.commands.cluster.setup_logger')
+    def test_describe_cluster_empty_response(self, mock_setup_logger, mock_session, mock_get_sagemaker_client):
+        """Test cluster description with empty response."""
+        # Arrange
+        mock_logger = Mock()
+        mock_setup_logger.return_value = mock_logger
+
+        mock_session_instance = Mock()
+        mock_session.return_value = mock_session_instance
+
+        mock_sm_client = Mock()
+        mock_get_sagemaker_client.return_value = mock_sm_client
+
+        # Mock empty cluster response
+        cluster_response = {}
+
+        mock_sm_client.describe_cluster.return_value = cluster_response
+
+        # Act
+        result = self.runner.invoke(describe_cluster, ["test-cluster"])
+
+        # Assert
+        assert result.exit_code == 0
+        mock_sm_client.describe_cluster.assert_called_once_with(ClusterName="test-cluster")
+        assert "📋 Cluster Details for: test-cluster" in result.output
+        assert "No cluster data available" in result.output
+
+
+if __name__ == "__main__":
+    unittest.main()