diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_aml_compute_node_info.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_aml_compute_node_info.py index 5515d0dbe879..91f12e8c42a8 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_aml_compute_node_info.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_aml_compute_node_info.py @@ -10,10 +10,9 @@ class AmlComputeNodeInfo: - def __init__(self): - """Compute node information related to a AmlCompute Variables are only populated by the server, and will be - ignored when sending a request.""" + """Compute node information related to AmlCompute.""" + def __init__(self): self.node_id = None self.private_ip_address = None self.port = None @@ -22,10 +21,20 @@ def __init__(self): @property def current_job_name(self) -> str: + """The run ID of the current job. + + :return: The run ID of the current job. + :rtype: str + """ return self.run_id @current_job_name.setter def current_job_name(self, value: str) -> None: + """Set the current job run ID. + + :param value: The job run ID. + :type value: str + """ self.run_id = value @classmethod diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_image_metadata.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_image_metadata.py index f87aa9efc841..95fbf8daaad9 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_image_metadata.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_image_metadata.py @@ -4,36 +4,55 @@ class ImageMetadata: - """Metadata about the operating system image for this compute instance.""" - - def __init__(self, *, is_latest_os_image_version: bool, current_image_version: str, latest_image_version: str): + """Metadata about the operating system image for the compute instance. + + :param is_latest_os_image_version: Specifies if the compute instance is running on the latest OS image version. + :type is_latest_os_image_version: bool + :param current_image_version: Version of the current image. + :type current_image_version: str + :param latest_image_version: The latest image version. + :type latest_image_version: str + + .. admonition:: Example: + + .. literalinclude:: ../../../../../samples/ml_samples_compute.py + :start-after: [START image_metadata] + :end-before: [END image_metadata] + :language: python + :dedent: 8 + :caption: Creating a ImageMetadata object. + """ + + def __init__( + self, *, is_latest_os_image_version: bool, current_image_version: str, latest_image_version: str + ) -> None: self._is_latest_os_image_version = is_latest_os_image_version self._current_image_version = current_image_version self._latest_image_version = latest_image_version @property def is_latest_os_image_version(self) -> bool: - """Indicates whether a compute instance is running on the latest OS image version. + """Whether or not a compute instance is running on the latest OS image version. - :return: State of whether the compute instance is running the latest OS image version. + :return: Boolean indicating if the compute instance is running the latest OS image version. :rtype: bool """ return self._is_latest_os_image_version @property def current_image_version(self) -> str: - """Indicates the current OS image version number. + """The current OS image version number. - :return: Current OS Image version number. + :return: The current OS image version number. :rtype: str """ return self._current_image_version @property def latest_image_version(self) -> str: - """Indicates the latest OS image version number. + """The latest OS image version number. - :return: Latest OS Image version number. + :return: The latest OS image version number. :rtype: str """ return self._latest_image_version diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_schedule.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_schedule.py index 819fe6fb3595..77e332752656 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_schedule.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_schedule.py @@ -18,13 +18,22 @@ class ComputeStartStopSchedule(RestTranslatableMixin): """Schedules for compute start or stop scenario. :param trigger: The trigger of the schedule. - :type trigger: Trigger + :type trigger: Union[~azure.ai.ml.entities.CronTrigger, ~azure.ai.ml.entities.RecurrenceTrigger] :param action: The compute power action. - :type action: ComputePowerAction + :type action: ~azure.ai.ml.entities.ComputePowerAction :param state: The state of the schedule. - :type state: ScheduleState + :type state: ~azure.ai.ml.entities.ScheduleState :param kwargs: A dictionary of additional configuration parameters. :type kwargs: dict + + .. admonition:: Example: + + .. literalinclude:: ../../../../../samples/ml_samples_compute.py + :start-after: [START compute_start_stop_schedule] + :end-before: [END compute_start_stop_schedule] + :language: python + :dedent: 8 + :caption: Creating a ComputeStartStopSchedule object. """ def __init__( @@ -34,7 +43,7 @@ def __init__( action: Optional[ComputePowerAction] = None, state: ScheduleState = ScheduleState.ENABLED, **kwargs - ): + ) -> None: self.trigger = trigger self.action = action self.state = state @@ -43,18 +52,18 @@ def __init__( @property def schedule_id(self) -> Optional[str]: - """Schedule id, readonly. + """The schedule ID. - :return: Schedule id. + :return: The schedule ID. :rtype: Optional[str] """ return self._schedule_id @property def provisioning_state(self) -> Optional[str]: - """Schedule provisioning state, readonly. + """The schedule provisioning state. - :return: Schedule provisioning state. + :return: The schedule provisioning state. :rtype: Optional[str] """ return self._provisioning_state @@ -105,12 +114,21 @@ class ComputeSchedules(RestTranslatableMixin): """Compute schedules. :param compute_start_stop: Compute start or stop schedules. - :type compute_start_stop: List[ComputeStartStopSchedule] + :type compute_start_stop: List[~azure.ai.ml.entities.ComputeStartStopSchedule] :param kwargs: A dictionary of additional configuration parameters. :type kwargs: dict + + .. admonition:: Example: + + .. literalinclude:: ../../../../../samples/ml_samples_compute.py + :start-after: [START compute_start_stop_schedule] + :end-before: [END compute_start_stop_schedule] + :language: python + :dedent: 8 + :caption: Creating a ComputeSchedules object. """ - def __init__(self, *, compute_start_stop: Optional[List[ComputeStartStopSchedule]] = None): + def __init__(self, *, compute_start_stop: Optional[List[ComputeStartStopSchedule]] = None) -> None: self.compute_start_stop = compute_start_stop def _to_rest_object(self) -> RestComputeSchedules: diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_vm_size.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_vm_size.py index 393c02d5babe..cb66924c30ce 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_vm_size.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_vm_size.py @@ -13,7 +13,33 @@ class VmSize(RestTranslatableMixin): - """virtual Machine Size.""" + """Virtual Machine Size. + + :param name: The virtual machine size name. + :type name: Optional[str] + :param family: The virtual machine size family name. + :type family: Optional[str] + :param v_cp_us: The number of vCPUs supported by the virtual machine size. + :type v_cp_us: Optional[int] + :param gpus: The number of GPUs supported by the virtual machine size. + :type gpus: Optional[int] + :param os_vhd_size_mb: The OS VHD disk size, in MB, allowed by the virtual machine size. + :type os_vhd_size_mb: Optional[int] + :param max_resource_volume_mb: The resource volume size, in MB, allowed by the virtual machine + size. + :type max_resource_volume_mb: Optional[int] + :param memory_gb: The amount of memory, in GB, supported by the virtual machine size. + :type memory_gb: Optional[float] + :param low_priority_capable: Specifies if the virtual machine size supports low priority VMs. + :type low_priority_capable: Optional[bool] + :param premium_io: Specifies if the virtual machine size supports premium IO. + :type premium_io: Optional[bool] + :param estimated_vm_prices: The estimated price information for using a VM. + :type estimated_vm_prices: ~azure.mgmt.machinelearningservices.models.EstimatedVMPrices + :param supported_compute_types: Specifies the compute types supported by the virtual machine + size. + :type supported_compute_types: Optional[list[str]] + """ def __init__( self, @@ -27,35 +53,7 @@ def __init__( low_priority_capable: Optional[bool] = None, premium_io: Optional[bool] = None, supported_compute_types: Optional[List[str]] = None, - ): - """Virtual machine size. - - :param name: The name of the virtual machine size. - :type name: str - :param family: The family name of the virtual machine size. - :type family: str - :param v_cp_us: The number of vCPUs supported by the virtual machine size. - :type v_cp_us: int - :param gpus: The number of gPUs supported by the virtual machine size. - :type gpus: int - :param os_vhd_size_mb: The OS VHD disk size, in MB, allowed by the virtual machine size. - :type os_vhd_size_mb: int - :param max_resource_volume_mb: The resource volume size, in MB, allowed by the virtual machine - size. - :type max_resource_volume_mb: int - :param memory_gb: The amount of memory, in GB, supported by the virtual machine size. - :type memory_gb: float - :param low_priority_capable: Specifies if the virtual machine size supports low priority VMs. - :type low_priority_capable: bool - :param premium_io: Specifies if the virtual machine size supports premium IO. - :type premium_io: bool - :param estimated_vm_prices: The estimated price information for using a VM. - :type estimated_vm_prices: ~azure.mgmt.machinelearningservices.models.EstimatedVMPrices - :param supported_compute_types: Specifies the compute types supported by the virtual machine - size. - :type supported_compute_types: list[str] - """ - + ) -> None: self.name = name self.family = family self.v_cp_us = v_cp_us diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/aml_compute.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/aml_compute.py index 6e94a55df6bf..4d7548a077dc 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/aml_compute.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/aml_compute.py @@ -6,9 +6,7 @@ from typing import Dict, Optional -from azure.ai.ml._restclient.v2022_10_01_preview.models import ( - AmlCompute as AmlComputeRest, -) +from azure.ai.ml._restclient.v2022_10_01_preview.models import AmlCompute as AmlComputeRest from azure.ai.ml._restclient.v2022_10_01_preview.models import ( AmlComputeProperties, ComputeResource, @@ -18,11 +16,7 @@ ) from azure.ai.ml._schema._utils.utils import get_subnet_str from azure.ai.ml._schema.compute.aml_compute import AmlComputeSchema -from azure.ai.ml._utils.utils import ( - camel_to_snake, - snake_to_pascal, - to_iso_duration_format, -) +from azure.ai.ml._utils.utils import camel_to_snake, snake_to_pascal, to_iso_duration_format from azure.ai.ml.constants._common import BASE_PATH_CONTEXT_KEY, TYPE from azure.ai.ml.constants._compute import ComputeDefaults, ComputeType from azure.ai.ml.entities._credentials import IdentityConfiguration @@ -32,7 +26,25 @@ class AmlComputeSshSettings: - """SSH settings to access a AML compute target.""" + """SSH settings to access a AML compute target. + + :param admin_username: SSH user name. + :type admin_username: str + :param admin_password: SSH user password. Defaults to None. + :type admin_password: str + :param ssh_key_value: The SSH RSA private key. Use "ssh-keygen -t + rsa -b 2048" to generate your SSH key pairs. Defaults to None. + :type ssh_key_value: Optional[str] + + .. admonition:: Example: + + .. literalinclude:: ../../../../../samples/ml_samples_compute.py + :start-after: [START aml_compute_ssh_settings] + :end-before: [END aml_compute_ssh_settings] + :language: python + :dedent: 8 + :caption: Configuring an AmlComputeSshSettings object. + """ def __init__( self, @@ -40,17 +52,7 @@ def __init__( admin_username: str, admin_password: Optional[str] = None, ssh_key_value: Optional[str] = None, - ): - """[summary] - - :param admin_username: SSH user name - :type admin_username: str - :param admin_password: SSH user password, defaults to None - :type admin_password: str - :param ssh_key_value: Specifies the SSH rsa private key as a string. Use "ssh-keygen -t - rsa -b 2048" to generate your SSH key pairs. Defaults to None - :type ssh_key_value: Optional[str] - """ + ) -> None: self.admin_username = admin_username self.admin_password = admin_password self.ssh_key_value = ssh_key_value @@ -72,42 +74,52 @@ def _from_user_account_credentials(cls, credentials: UserAccountCredentials) -> class AmlCompute(Compute): - """Aml Compute resource. + """AzureML Compute resource. - :param name: Name of the compute + :param name: Name of the compute resource. :type name: str - :param description: Description of the resource. - :type description: str - :param size: Compute Size, defaults to None. - :type size: str + :param description: Description of the compute resource. + :type description: Optional[str] + :param size: Size of the compute. Defaults to None. + :type size: Optional[str] :param tags: A set of tags. Contains resource tags defined as key/value pairs. :type tags: Optional[dict[str, str]] :param ssh_settings: SSH settings to access the AzureML compute cluster. - :type ssh_settings: AmlComputeSshSettings + :type ssh_settings: Optional[~azure.ai.ml.entities.AmlComputeSshSettings] :param network_settings: Virtual network settings for the AzureML compute cluster. - :type network_settings: NetworkSettings - :param idle_time_before_scale_down: Node Idle Time before scaling down amlCompute. Defaults to None. - :type idle_time_before_scale_down: int - :param identity: The identity configuration, identities that are associated with the compute cluster. - :type identity: IdentityConfiguration - :param tier: Virtual Machine tier. Possible values include: "Dedicated", "LowPriority". Defaults to None. - :type tier: str + :type network_settings: Optional[~azure.ai.ml.entities.NetworkSettings] + :param idle_time_before_scale_down: Node idle time before scaling down. Defaults to None. + :type idle_time_before_scale_down: Optional[int] + :param identity: The identities that are associated with the compute cluster. + :type identity: Optional[~azure.ai.ml.entities.IdentityConfiguration] + :param tier: Virtual Machine tier. Accepted values include: "Dedicated", "LowPriority". Defaults to None. + :type tier: Optional[str] :param min_instances: Minimum number of instances. Defaults to None. - :type min_instances: int + :type min_instances: Optional[int] :param max_instances: Maximum number of instances. Defaults to None. - :type max_instances: int - :param ssh_public_access_enabled: State of the public SSH port. Possible values are: - False - Indicates that the public ssh port is closed on all nodes of the cluster. True - - Indicates that the public ssh port is open on all nodes of the cluster. None - - Indicates that the public ssh port is closed on all nodes of the cluster if VNet is defined, - else is open all public nodes. It can be default only during cluster creation time, after - creation it will be either True or False. Possible values include: True, False, None. Default value: None. - :type ssh_public_access_enabled: bool - :param enable_node_public_ip: Enable or disable node public IP address provisioning. Possible values are: - True - Indicates that the compute nodes will have public IPs provisioned. - False - Indicates that the compute nodes will have a private endpoint and no public IPs. - Default Value: True. - :type enable_node_public_ip: Optional[bool] + :type max_instances: Optional[int] + :param ssh_public_access_enabled: State of the public SSH port. Accepted values are: + * False - Indicates that the public SSH port is closed on all nodes of the cluster. + * True - Indicates that the public SSH port is open on all nodes of the cluster. + * None - Indicates that the public SSH port is closed on all nodes of the cluster if VNet is defined, + else is open all public nodes. + It can be None only during cluster creation time. After creation it will be either True or False. + Defaults to None. + :type ssh_public_access_enabled: Optional[bool] + :param enable_node_public_ip: Enable or disable node public IP address provisioning. Accepted values are: + * True - Indicates that the compute nodes will have public IPs provisioned. + * False - Indicates that the compute nodes will have a private endpoint and no public IPs. + Defaults to True. + :type enable_node_public_ip: bool + + .. admonition:: Example: + + .. literalinclude:: ../../../../../samples/ml_samples_compute.py + :start-after: [START amlcompute] + :end-before: [END amlcompute] + :language: python + :dedent: 8 + :caption: Creating an AmlCompute object. """ def __init__( @@ -127,7 +139,7 @@ def __init__( tier: Optional[str] = None, enable_node_public_ip: bool = True, **kwargs, - ): + ) -> None: kwargs[TYPE] = ComputeType.AMLCOMPUTE super().__init__( name=name, diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/compute.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/compute.py index 33e29f3c525d..dc65e51ed3d6 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/compute.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/compute.py @@ -21,19 +21,21 @@ class Compute(Resource, RestTranslatableMixin): - """Compute resource. + """Base class for compute resources. - :param type: The type of the compute, possible values are - ["amlcompute", "computeinstance", "virtualmachine", "kubernetes", "synapsespark"] + This class should not be instantiated directly. Instead, use one of its subclasses. + + :param type: The compute type. Accepted values are "amlcompute", "computeinstance", + "virtualmachine", "kubernetes", and "synapsespark". :type type: str - :param name: Name of the compute + :param name: Name of the compute resource. :type name: str - :param location: The resource location, defaults to workspace location. + :param location: The resource location. Defaults to workspace location. :type location: Optional[str] - :param description: Description of the resource. + :param description: Description of the resource. Defaults to None. :type description: Optional[str] - :param resource_id: ARM resource id of the underlying compute. - :type resource_id: str + :param resource_id: ARM resource id of the underlying compute. Defaults to None. + :type resource_id: Optional[str] :param tags: A set of tags. Contains resource tags defined as key/value pairs. :type tags: Optional[dict[str, str]] """ @@ -46,7 +48,7 @@ def __init__( resource_id: Optional[str] = None, tags: Optional[dict] = None, **kwargs, - ): + ) -> None: self._type = kwargs.pop("type", None) if self._type: self._type = self._type.lower() @@ -62,37 +64,36 @@ def __init__( @property def type(self) -> Optional[str]: - """The type of the compute, possible values are ["amlcompute", "computeinstance", "virtualmachine", - "kubernetes", "synapsespark"] + """The compute type. - :return: The type of the compute + :return: The compute type. :rtype: Optional[str] """ return self._type @property def created_on(self) -> Optional[str]: - """Creation timestamp. + """The compute resource creation timestamp. - :return: [description] + :return: The compute resource creation timestamp. :rtype: Optional[str] """ return self._created_on @property def provisioning_state(self) -> Optional[str]: - """Provisioning state. + """The compute resource's provisioning state. - :return: [description] + :return: The compute resource's provisioning state. :rtype: Optional[str] """ return self._provisioning_state @property def provisioning_errors(self) -> Optional[str]: - """Provisioning errors. + """The compute resource provisioning errors. - :return: [description] + :return: The compute resource provisioning errors. :rtype: Optional[str] """ return self._provisioning_errors @@ -202,20 +203,30 @@ def _load_from_dict(cls, data: Dict, context: Dict, **kwargs) -> "Compute": class NetworkSettings: + """Network settings for a compute resource. + + :param vnet_name: The virtual network name. + :type vnet_name: str + :param subnet: The subnet name. + :type subnet: str + + .. admonition:: Example: + + .. literalinclude:: ../../../../../samples/ml_samples_compute.py + :start-after: [START network_settings] + :end-before: [END network_settings] + :language: python + :dedent: 8 + :caption: Configuring NetworkSettings for an AmlCompute object. + """ + def __init__( self, *, vnet_name: Optional[str] = None, subnet: Optional[str] = None, **kwargs, - ): - """Network settings for a compute. - - :param vnet_name: The virtual network name, defaults to None - :type vnet_name: str - :param subnet: The subnet name, defaults to None - :type subnet: str - """ + ) -> None: self.vnet_name = vnet_name self.subnet = subnet self._public_ip_address = kwargs.pop("public_ip_address", None) diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/compute_instance.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/compute_instance.py index 9708af6fcf0b..ddac2e071c47 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/compute_instance.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/compute_instance.py @@ -12,9 +12,7 @@ from azure.ai.ml._restclient.v2022_10_01_preview.models import AssignedUser from azure.ai.ml._restclient.v2022_10_01_preview.models import ComputeInstance as CIRest from azure.ai.ml._restclient.v2022_10_01_preview.models import ComputeInstanceProperties -from azure.ai.ml._restclient.v2022_10_01_preview.models import ( - ComputeInstanceSshSettings as CiSShSettings, -) +from azure.ai.ml._restclient.v2022_10_01_preview.models import ComputeInstanceSshSettings as CiSShSettings from azure.ai.ml._restclient.v2022_10_01_preview.models import ( ComputeResource, PersonalComputeInstanceSettings, @@ -29,10 +27,10 @@ from azure.ai.ml.entities._mixins import DictMixin from azure.ai.ml.entities._util import load_from_dict +from ._custom_applications import CustomApplications, validate_custom_applications from ._image_metadata import ImageMetadata from ._schedule import ComputeSchedules from ._setup_scripts import SetupScripts -from ._custom_applications import CustomApplications, validate_custom_applications module_logger = logging.getLogger(__name__) @@ -40,7 +38,20 @@ class ComputeInstanceSshSettings: """Credentials for an administrator user account to SSH into the compute node. - Can only be configured if ssh_public_access_enabled is set to true. + Can only be configured if `ssh_public_access_enabled` is set to true on compute + resource. + + :param ssh_key_value: The SSH public key of the administrator user account. + :type ssh_key_value: Optional[str] + + .. admonition:: Example: + + .. literalinclude:: ../../../../../samples/ml_samples_compute.py + :start-after: [START compute_instance_ssh_settings] + :end-before: [END compute_instance_ssh_settings] + :language: python + :dedent: 8 + :caption: Configuring ComputeInstanceSshSettings object. """ def __init__( @@ -48,12 +59,7 @@ def __init__( *, ssh_key_value: Optional[str] = None, **kwargs, - ): - """[summary] - - :param ssh_key_value: The SSH public key of the administrator user account. - :type ssh_key_value: str - """ + ) -> None: self.ssh_key_value = ssh_key_value self._ssh_port = kwargs.pop("ssh_port", None) self._admin_username = kwargs.pop("admin_username", None) @@ -78,16 +84,24 @@ def ssh_port(self) -> str: class AssignedUserConfiguration(DictMixin): - """Settings to create a compute on behalf of another user.""" + """Settings to create a compute resource on behalf of another user. - def __init__(self, *, user_tenant_id: str, user_object_id: str): - """[summary] + :param user_tenant_id: Tenant ID of the user to assign the compute target to. + :type user_tenant_id: str + :param user_object_id: Object ID of the user to assign the compute target to. + :type user_object_id: str - :param user_tenant_id: Tenant ID of the user to assign the compute target to. - :type user_tenant_id: str - :param user_object_id: Object ID of the user to assign the compute target to. - :type user_object_id: str - """ + .. admonition:: Example: + + .. literalinclude:: ../../../../../samples/ml_samples_compute.py + :start-after: [START assigned_user_configuration] + :end-before: [END assigned_user_configuration] + :language: python + :dedent: 8 + :caption: Creating an AssignedUserConfiguration. + """ + + def __init__(self, *, user_tenant_id: str, user_object_id: str) -> None: self.user_tenant_id = user_tenant_id self.user_object_id = user_object_id @@ -95,41 +109,39 @@ def __init__(self, *, user_tenant_id: str, user_object_id: str): class ComputeInstance(Compute): """Compute Instance resource. - :param name: Name of the compute + :param name: Name of the compute. :type name: str - :param location: The resource location, defaults to None + :param location: The resource location. :type location: Optional[str] :param description: Description of the resource. :type description: Optional[str] - :param size: Compute Size, defaults to None + :param size: Compute size. :type size: Optional[str] :param tags: A set of tags. Contains resource tags defined as key/value pairs. :type tags: Optional[dict[str, str]] - :param create_on_behalf_of: defaults to None - :type create_on_behalf_of: Optional[AssignedUserConfiguration] - :ivar state: defaults to None + :param create_on_behalf_of: Configuration to create resource on behalf of another user. Defaults to None. + :type create_on_behalf_of: Optional[~azure.ai.ml.entities.AssignedUserConfiguration] + :ivar state: State of the resource. :type state: Optional[str] - :ivar last_operation: defaults to None + :ivar last_operation: The last operation. :type last_operation: Optional[Dict[str, str]] - :ivar applications: defaults to None + :ivar applications: Applications associated with the compute instance. :type applications: Optional[List[Dict[str, str]]] - :param network_settings: defaults to None - :type network_settings: Optional[NetworkSettings] - :param ssh_settings: defaults to None - :type ssh_settings: Optional[ComputeInstanceSshSettings] - :param ssh_public_access_enabled: State of the public SSH port. Possible values are: ["False", "True", "None"] - False - Indicates that the public ssh port is closed on all nodes of the cluster. - True - Indicates that the public ssh port is open on all nodes of the cluster. - None -Indicates that the public ssh port is closed on all nodes of the cluster if VNet is defined, - else is open all public nodes. It can be default only during cluster creation time, after - creation it will be either True or False. Possible values include: True, False, None. - Default value: None. - + :param network_settings: Network settings for the compute instance. + :type network_settings: Optional[~azure.ai.ml.entities.NetworkSettings] + :param ssh_settings: SSH settings for the compute instance. + :type ssh_settings: Optional[~azure.ai.ml.entities.ComputeInstanceSshSettings] + :param ssh_public_access_enabled: State of the public SSH port. Defaults to None. Possible values are: + * False - Indicates that the public ssh port is closed on all nodes of the cluster. + * True - Indicates that the public ssh port is open on all nodes of the cluster. + * None -Indicates that the public ssh port is closed on all nodes of the cluster if VNet is defined, + else is open all public nodes. It can be default only during cluster creation time, after + creation it will be either True or False. :type ssh_public_access_enabled: Optional[bool] - :param schedules: Compute instance schedules, defaults to None - :type schedules: Optional[ComputeSchedules] - :param identity: The identity configuration, identities that are associated with the compute cluster. - :type identity: IdentityConfiguration + :param schedules: Compute instance schedules. Defaults to None. + :type schedules: Optional[~azure.ai.ml.entities.ComputeSchedules] + :param identity: The identities that are associated with the compute cluster. + :type identity: ~azure.ai.ml.entities.IdentityConfiguration :param idle_time_before_shutdown: Deprecated. Use the `idle_time_before_shutdown_minutes` parameter instead. Stops compute instance after user defined period of inactivity. Time is defined in ISO8601 format. Minimum is 15 minutes, maximum is 3 days. @@ -137,16 +149,25 @@ class ComputeInstance(Compute): :param idle_time_before_shutdown_minutes: Stops compute instance after a user defined period of inactivity in minutes. Minimum is 15 minutes, maximum is 3 days. :type idle_time_before_shutdown_minutes: Optional[int] - :param enable_node_public_ip: Enable or disable node public IP address provisioning. Possible values are: - True - Indicates that the compute nodes will have public IPs provisioned. - False - Indicates that the compute nodes will have a private endpoint and no public IPs. - Default Value: True. + :param enable_node_public_ip: Enable or disable node public IP address provisioning. Defaults to True. + Possible values are: + * True - Indicates that the compute nodes will have public IPs provisioned. + * False - Indicates that the compute nodes will have a private endpoint and no public IPs. :type enable_node_public_ip: Optional[bool] :param setup_scripts: Details of customized scripts to execute for setting up the cluster. - :type setup_scripts: Optional[SetupScripts] + :type setup_scripts: Optional[~azure.ai.ml.entities.SetupScripts] :param custom_applications: List of custom applications and their endpoints for the compute instance. - :type custom_applications: Optional[List[CustomApplications]] + :type custom_applications: Optional[List[~azure.ai.ml.entities.CustomApplications]] + + .. admonition:: Example: + + .. literalinclude:: ../../../../../samples/ml_samples_compute.py + :start-after: [START compute_instance] + :end-before: [END compute_instance] + :language: python + :dedent: 8 + :caption: Creating a ComputeInstance object. """ def __init__( @@ -168,7 +189,7 @@ def __init__( enable_node_public_ip: bool = True, custom_applications: Optional[List[CustomApplications]] = None, **kwargs, - ): + ) -> None: kwargs[TYPE] = ComputeType.COMPUTEINSTANCE self._state = kwargs.pop("state", None) self._last_operation = kwargs.pop("last_operation", None) @@ -198,9 +219,9 @@ def __init__( @property def services(self) -> List[Dict[str, str]]: - """ + """The compute instance's services. - :return: The services for the compute instance. + :return: The compute instance's services. :rtype: List[Dict[str, str]] """ return self._services @@ -228,7 +249,7 @@ def os_image_metadata(self) -> ImageMetadata: """Metadata about the operating system image for this compute instance. :return: Operating system image metadata. - :rtype: ImageMetadata + :rtype: ~azure.ai.ml.entities.ImageMetadata """ return self._os_image_metadata diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/kubernetes_compute.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/kubernetes_compute.py index 50758bcc90e0..83f2b36d1daa 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/kubernetes_compute.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/kubernetes_compute.py @@ -18,26 +18,21 @@ class KubernetesCompute(Compute): """Kubernetes Compute resource. - :param name: Name of the compute - :type name: str - :param location: The resource location, defaults to None - :type location: Optional[str] - :param description: Description of the resource. - :type description: Optional[str] - :param tags: A set of tags. Contains resource tags defined as key/value pairs. - :type tags: Optional[dict[str, str]] - :param resource_id: ARM resource id of the underlying compute, defaults to None - :type resource_id: Optional[str] - :param created_on: defaults to None - :type created_on: Optional[~datetime.datetime] - :param provisioning_state: defaults to None - :type provisioning_state: Optional[str] - :param namespace: Namespace of the KubernetesCompute + :param namespace: The namespace of the KubernetesCompute. Defaults to "default". :type namespace: Optional[str] - :param properties: KubernetesProperties, defaults to None + :param properties: The properties of the Kubernetes compute resource. :type properties: Optional[Dict] - :param identity: The identity configuration, identities that are associated with the compute cluster. - :type identity: IdentityConfiguration + :param identity: The identities that are associated with the compute cluster. + :type identity: ~azure.ai.ml.entities.IdentityConfiguration + + .. admonition:: Example: + + .. literalinclude:: ../../../../../samples/ml_samples_compute.py + :start-after: [START kubernetes_compute] + :end-before: [END kubernetes_compute] + :language: python + :dedent: 8 + :caption: Creating a KubernetesCompute object. """ def __init__( @@ -47,7 +42,7 @@ def __init__( properties: Optional[Dict[str, Any]] = None, identity: Optional[IdentityConfiguration] = None, **kwargs, - ): + ) -> None: kwargs[TYPE] = ComputeType.KUBERNETES super().__init__(**kwargs) self.namespace = namespace diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/unsupported_compute.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/unsupported_compute.py index b05d52f4447b..d47d1fed3fd1 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/unsupported_compute.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/unsupported_compute.py @@ -12,13 +12,13 @@ class UnsupportedCompute(Compute): """Unsupported compute resource. - Only for use displaying compute properties for resources not fully supported in the SDK. + Only used for displaying compute properties for resources not fully supported in the SDK. """ def __init__( self, **kwargs, - ): + ) -> None: kwargs[TYPE] = "*** Unsupported Compute Type ***" super().__init__(**kwargs) diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/virtual_machine_compute.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/virtual_machine_compute.py index cc0b759f5fe1..a7a92e638f5a 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/virtual_machine_compute.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/virtual_machine_compute.py @@ -11,13 +11,37 @@ VirtualMachineSshCredentials, ) from azure.ai.ml._schema.compute.virtual_machine_compute import VirtualMachineComputeSchema -from azure.ai.ml.constants._common import BASE_PATH_CONTEXT_KEY, DefaultOpenEncoding, TYPE +from azure.ai.ml.constants._common import BASE_PATH_CONTEXT_KEY, TYPE, DefaultOpenEncoding from azure.ai.ml.constants._compute import ComputeType from azure.ai.ml.entities._compute.compute import Compute from azure.ai.ml.entities._util import load_from_dict class VirtualMachineSshSettings: + """SSH settings for a virtual machine. + + :param admin_username: The admin user name. Defaults to None. + :type admin_username: str + :param admin_password: The admin user password. Defaults to None. + Required if `ssh_private_key_file` is not specified. + :type admin_password: Optional[str] + :param ssh_port: The ssh port number. Default is 22. + :type ssh_port: int + :param ssh_private_key_file: Path to the file containing the SSH rsa private key. + Use "ssh-keygen -t rsa -b 2048" to generate your SSH key pairs. + Required if admin_password is not specified. + :type ssh_private_key_file: Optional[str] + + .. admonition:: Example: + + .. literalinclude:: ../../../../../samples/ml_samples_compute.py + :start-after: [START vm_ssh_settings] + :end-before: [END vm_ssh_settings] + :language: python + :dedent: 8 + :caption: Configuring a VirtualMachineSshSettings object. + """ + def __init__( self, *, @@ -25,21 +49,7 @@ def __init__( admin_password: Optional[str] = None, ssh_port: int = 22, ssh_private_key_file: Optional[str] = None, - ): - """SSH settings for a virtual machine. - - :param admin_username: Describes the admin user name., defaults to None. - :type admin_username: str, required - :param admin_password: Describes the admin user password. - Defaults to None. Required if ssh_private_key_file is not specified. - :type admin_password: str - :param ssh_port: The ssh port number. Default is 22. - :type ssh_port: str - :param ssh_private_key_file: Specifies the file containing SSH rsa private key. - Use "ssh-keygen -t rsa -b 2048" to generate your SSH key pairs. - Required if admin_password is not specified. - :type ssh_private_key_file: str - """ + ) -> None: self.admin_username = admin_username self.admin_password = admin_password self.ssh_port = ssh_port @@ -49,16 +59,25 @@ def __init__( class VirtualMachineCompute(Compute): """Virtual Machine Compute resource. - :param name: Name of the compute + :param name: Name of the compute resource. :type name: str - :param description: Description of the resource. + :param description: Description of the resource. Defaults to None. :type description: Optional[str] - :param resource_id: ARM resource id of the underlying compute + :param resource_id: ARM resource ID of the underlying compute resource. :type resource_id: str :param tags: A set of tags. Contains resource tags defined as key/value pairs. - :type tags: Optional[dict[str, str]] - :param ssh_settings: SSH settings. - :type ssh_settings: VirtualMachineSshSettings + :type tags: Optional[dict] + :param ssh_settings: SSH settings. Defaults to None. + :type ssh_settings: Optional[~azure.ai.ml.entities.VirtualMachineSshSettings] + + .. admonition:: Example: + + .. literalinclude:: ../../../../../samples/ml_samples_compute.py + :start-after: [START vm_compute] + :end-before: [END vm_compute] + :language: python + :dedent: 8 + :caption: Configuring a VirtualMachineCompute object. """ def __init__( @@ -70,7 +89,7 @@ def __init__( tags: Optional[dict] = None, ssh_settings: Optional[VirtualMachineSshSettings] = None, **kwargs, - ): + ) -> None: kwargs[TYPE] = ComputeType.VIRTUALMACHINE self._public_key_data = kwargs.pop("public_key_data", None) super().__init__( diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_feature_set/materialization_compute_resource.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_feature_set/materialization_compute_resource.py index df9fada902ec..62d6321cd13a 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_feature_set/materialization_compute_resource.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_feature_set/materialization_compute_resource.py @@ -11,11 +11,22 @@ @experimental class MaterializationComputeResource(RestTranslatableMixin): + """Materialization Compute resource + + :keyword instance_type: The compute instance type. + :paramtype instance_type: str + + .. admonition:: Example: + + .. literalinclude:: ../../../../../samples/ml_samples_compute.py + :start-after: [START materialization_compute_resource] + :end-before: [END materialization_compute_resource] + :language: python + :dedent: 8 + :caption: Creating a MaterializationComputeResource object. + """ + def __init__(self, *, instance_type: str, **kwargs): # pylint: disable=unused-argument - """ - :keyword instance_type: Specifies the instance type. - :paramtype instance_type: str - """ self.instance_type = instance_type def _to_rest_object(self) -> RestMaterializationComputeResource: diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_job/compute_configuration.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_job/compute_configuration.py index 67a9690784e6..b3c37514de29 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_job/compute_configuration.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_job/compute_configuration.py @@ -15,6 +15,22 @@ class ComputeConfiguration(RestTranslatableMixin, DictMixin): + """Compute resource configuration + + :param target: The compute target. + :type target: Optional[str] + :param instance_count: The number of instances. + :type instance_count: Optional[int] + :param is_local: Specifies if the compute will be on the local machine. + :type is_local: Optional[bool] + :param location: The location of the compute resource. + :type location: Optional[str] + :param properties: The resource properties + :type properties: Optional[Dict[str, Any]] + :param deserialize_properties: Specifies if property bag should be deserialized. Defaults to False. + :type deserialize_properties: bool + """ + def __init__( self, *, @@ -25,7 +41,7 @@ def __init__( location: Optional[str] = None, properties: Optional[Dict[str, Any]] = None, deserialize_properties: bool = False, - ): + ) -> None: self.instance_count = instance_count self.target = target or LOCAL_COMPUTE_TARGET self.is_local = is_local or self.target == LOCAL_COMPUTE_TARGET diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_load_functions.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_load_functions.py index 57a934af95f5..0f2a9318a243 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_load_functions.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_load_functions.py @@ -5,7 +5,7 @@ import logging import warnings from os import PathLike -from typing import IO, AnyStr, Optional, Type, Union +from typing import IO, AnyStr, Dict, List, Optional, Type, Union from marshmallow import ValidationError @@ -308,6 +308,7 @@ def load_compute( source: Union[str, PathLike, IO[AnyStr]], *, relative_origin: Optional[str] = None, + params_override: Optional[List[Dict[str, str]]] = None, **kwargs, ) -> Compute: """Construct a compute object from a yaml file. @@ -323,15 +324,23 @@ def load_compute( the relative locations of files referenced in the parsed yaml. Defaults to the inputted source's directory if it is a file or file path input. Defaults to "./" if the source is a stream input with no name value. - :paramtype relative_origin: str + :paramtype relative_origin: Optional[str] :keyword params_override: Fields to overwrite on top of the yaml file. Format is [{"field1": "value1"}, {"field2": "value2"}] - :paramtype params_override: List[Dict] - + :paramtype params_override: Optional[List[Dict]] :return: Loaded compute object. - :rtype: Compute + :rtype: ~azure.ai.ml.entities.Compute + + .. admonition:: Example: + + .. literalinclude:: ../../../../samples/ml_samples_compute.py + :start-after: [START load_compute] + :end-before: [END load_compute] + :language: python + :dedent: 8 + :caption: Loading a Compute object from a YAML file and overriding its description. """ - return load_common(Compute, source, relative_origin, **kwargs) + return load_common(Compute, source, relative_origin, params_override=params_override, **kwargs) def load_component( diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_workspace/compute_runtime.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_workspace/compute_runtime.py index 036a2440d05a..26eb9ddd7fd8 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_workspace/compute_runtime.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_workspace/compute_runtime.py @@ -5,21 +5,32 @@ from typing import Optional from azure.ai.ml._restclient.v2023_06_01_preview.models import ComputeRuntimeDto as RestComputeRuntimeDto -from azure.ai.ml.entities._mixins import RestTranslatableMixin from azure.ai.ml._utils._experimental import experimental +from azure.ai.ml.entities._mixins import RestTranslatableMixin @experimental class ComputeRuntime(RestTranslatableMixin): + """Spark compute runtime configuration. + + :keyword spark_runtime_version: Spark runtime version. + :paramtype spark_runtime_version: Optional[str] + + .. admonition:: Example: + + .. literalinclude:: ../../../../../samples/ml_samples_compute.py + :start-after: [START compute_runtime] + :end-before: [END compute_runtime] + :language: python + :dedent: 8 + :caption: Creating a ComputeRuntime object. + """ + def __init__( self, *, spark_runtime_version: Optional[str] = None, - ): - """ - :keyword spark_runtime_version: - :paramtype spark_runtime_version: str - """ + ) -> None: self.spark_runtime_version = spark_runtime_version def _to_rest_object(self) -> RestComputeRuntimeDto: diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/operations/_compute_operations.py b/sdk/ml/azure-ai-ml/azure/ai/ml/operations/_compute_operations.py index a6d057c5c72d..63cb0413f729 100644 --- a/sdk/ml/azure-ai-ml/azure/ai/ml/operations/_compute_operations.py +++ b/sdk/ml/azure-ai-ml/azure/ai/ml/operations/_compute_operations.py @@ -23,16 +23,15 @@ class ComputeOperations(_ScopeDependentOperations): """ComputeOperations. - You should not instantiate this class directly. Instead, you should create an MLClient instance that instantiates it - for you and attaches it as an attribute. + This class should not be instantiated directly. Instead, use the `compute` attribute of an MLClient object. :param operation_scope: Scope variables for the operations classes of an MLClient object. :type operation_scope: ~azure.ai.ml._scope_dependent_operations.OperationScope :param operation_config: Common configuration for operations classes of an MLClient object. :type operation_config: ~azure.ai.ml._scope_dependent_operations.OperationConfig - :param service_client: Service client to allow end users to operate on Azure Machine Learning Workspace resources. - :type service_client: ~azure.ai.ml._restclient.v2023_02_01_preview._azure_machine_learning_workspaces. - AzureMachineLearningWorkspaces + :param service_client: Service client to allow end users to operate on Azure Machine Learning + Workspace resources. + :type service_client: ~azure.ai.ml._restclient.v2023_02_01_preview.AzureMachineLearningWorkspaces """ def __init__( @@ -41,7 +40,7 @@ def __init__( operation_config: OperationConfig, service_client: ServiceClient022023Preview, **kwargs: Dict, - ): + ) -> None: super(ComputeOperations, self).__init__(operation_scope, operation_config) ops_logger.update_info(kwargs) self._operation = service_client.compute @@ -55,19 +54,19 @@ def __init__( def list(self, *, compute_type: Optional[str] = None) -> Iterable[Compute]: """List computes of the workspace. - :keyword compute_type: the type of the compute to be listed, defaults to amlcompute - :paramtype compute_type: str - :return: An iterator like instance of Compute objects - :rtype: ~azure.core.paging.ItemPaged[Compute] + :keyword compute_type: The type of the compute to be listed, case-insensitive. Defaults to AMLCompute. + :paramtype compute_type: Optional[str] + :return: An iterator like instance of Compute objects. + :rtype: ~azure.core.paging.ItemPaged[~azure.ai.ml.entities.Compute] .. admonition:: Example: - .. literalinclude:: ../../../../samples/ml_samples_misc.py + .. literalinclude:: ../../../../samples/ml_samples_compute.py :start-after: [START compute_operations_list] :end-before: [END compute_operations_list] :language: python :dedent: 8 - :caption: List compute example. + :caption: Retrieving a list of the AzureML Kubernetes compute resources in a workspace. """ return self._operation.list( @@ -85,19 +84,19 @@ def list(self, *, compute_type: Optional[str] = None) -> Iterable[Compute]: def get(self, name: str) -> Compute: """Get a compute resource. - :param name: Name of the compute + :param name: Name of the compute resource. :type name: str - :return: Compute object - :rtype: Compute + :return: A Compute object. + :rtype: ~azure.ai.ml.entities.Compute .. admonition:: Example: - .. literalinclude:: ../../../../samples/ml_samples_misc.py + .. literalinclude:: ../../../../samples/ml_samples_compute.py :start-after: [START compute_operations_get] :end-before: [END compute_operations_get] :language: python :dedent: 8 - :caption: Get compute resource example. + :caption: Retrieving a compute resource from a workspace. """ rest_obj = self._operation.get( @@ -110,21 +109,21 @@ def get(self, name: str) -> Compute: @distributed_trace @monitor_with_activity(logger, "Compute.ListNodes", ActivityType.PUBLICAPI) def list_nodes(self, name: str) -> Iterable[AmlComputeNodeInfo]: - """Get a compute resource nodes. + """Retrieve a list of a compute resource's nodes. - :param name: Name of the compute + :param name: Name of the compute resource. :type name: str - :return: An iterator over aml compute node information objects - :rtype: ~azure.core.paging.ItemPaged[AmlComputeNodeInfo] + :return: An iterator-like instance of AmlComputeNodeInfo objects. + :rtype: ~azure.core.paging.ItemPaged[~azure.ai.ml.entities.AmlComputeNodeInfo] .. admonition:: Example: - .. literalinclude:: ../../../../samples/ml_samples_misc.py + .. literalinclude:: ../../../../samples/ml_samples_compute.py :start-after: [START compute_operations_list_nodes] :end-before: [END compute_operations_list_nodes] :language: python :dedent: 8 - :caption: Get compute resource nodes example. + :caption: Retrieving a list of nodes from a compute resource. """ return self._operation.list_nodes( self._operation_scope.resource_group_name, @@ -136,21 +135,22 @@ def list_nodes(self, name: str) -> Iterable[AmlComputeNodeInfo]: @distributed_trace @monitor_with_activity(logger, "Compute.BeginCreateOrUpdate", ActivityType.PUBLICAPI) def begin_create_or_update(self, compute: Compute) -> LROPoller[Compute]: - """Create a compute. + """Create and register a compute resource. - :param compute: Compute definition. - :type compute: Compute - :return: An instance of LROPoller that returns a Compute. + :param compute: The compute resource definition. + :type compute: ~azure.ai.ml.entities.Compute + :return: An instance of LROPoller that returns a Compute object once the + long-running operation is complete. :rtype: ~azure.core.polling.LROPoller[~azure.ai.ml.entities.Compute] .. admonition:: Example: - .. literalinclude:: ../../../../samples/ml_samples_misc.py - :start-after: [START compute_operations_create_or_update] - :end-before: [END compute_operations_create_or_update] + .. literalinclude:: ../../../../samples/ml_samples_compute.py + :start-after: [START compute_operations_create_update] + :end-before: [END compute_operations_create_update] :language: python :dedent: 8 - :caption: Create compute example. + :caption: Creating and registering a compute resource. """ if compute.type != ComputeType.AMLCOMPUTE: if compute.location: @@ -184,42 +184,44 @@ def begin_create_or_update(self, compute: Compute) -> LROPoller[Compute]: @distributed_trace @monitor_with_activity(logger, "Compute.Attach", ActivityType.PUBLICAPI) def begin_attach(self, compute: Compute, **kwargs: Any) -> LROPoller[Compute]: - """Attaches a compute to the workspace. + """Attach a compute resource to the workspace. - :param compute: Compute definition. - :type compute: Compute - :return: An instance of LROPoller that returns Compute. + :param compute: The compute resource definition. + :type compute: ~azure.ai.ml.entities.Compute + :return: An instance of LROPoller that returns a Compute object once the + long-running operation is complete. :rtype: ~azure.core.polling.LROPoller[~azure.ai.ml.entities.Compute] .. admonition:: Example: - .. literalinclude:: ../../../../samples/ml_samples_misc.py + .. literalinclude:: ../../../../samples/ml_samples_compute.py :start-after: [START compute_operations_attach] :end-before: [END compute_operations_attach] :language: python :dedent: 8 - :caption: Attach compute example. + :caption: Attaching a compute resource to the workspace. """ return self.begin_create_or_update(compute=compute, **kwargs) @distributed_trace @monitor_with_activity(logger, "Compute.BeginUpdate", ActivityType.PUBLICAPI) def begin_update(self, compute: Compute) -> LROPoller[Compute]: - """Update a compute. Currently only valid for AmlCompute. + """Update a compute resource. Currently only valid for AmlCompute resource types. - :param compute: Compute resource. - :type compute: Compute - :return: An instance of LROPoller that returns Compute. + :param compute: The compute resource definition. + :type compute: ~azure.ai.ml.entities.Compute + :return: An instance of LROPoller that returns a Compute object once the + long-running operation is complete. :rtype: ~azure.core.polling.LROPoller[~azure.ai.ml.entities.Compute] .. admonition:: Example: - .. literalinclude:: ../../../../samples/ml_samples_misc.py + .. literalinclude:: ../../../../samples/ml_samples_compute.py :start-after: [START compute_operations_update] :end-before: [END compute_operations_update] :language: python :dedent: 8 - :caption: Update compute example. + :caption: Updating an AmlCompute resource. """ if not compute.type == ComputeType.AMLCOMPUTE: COMPUTE_UPDATE_ERROR.format(compute.name, compute.type) @@ -240,12 +242,12 @@ def begin_update(self, compute: Compute) -> LROPoller[Compute]: @distributed_trace @monitor_with_activity(logger, "Compute.BeginDelete", ActivityType.PUBLICAPI) def begin_delete(self, name: str, *, action: str = "Delete") -> LROPoller[None]: - """Delete a compute. + """Delete or detach a compute resource. - :param name: The name of the compute. + :param name: The name of the compute resource. :type name: str :keyword action: Action to perform. Possible values: ["Delete", "Detach"]. Defaults to "Delete". - :type action: Optional[str] + :type action: str :return: A poller to track the operation status. :rtype: ~azure.core.polling.LROPoller[None] @@ -269,21 +271,21 @@ def begin_delete(self, name: str, *, action: str = "Delete") -> LROPoller[None]: @distributed_trace @monitor_with_activity(logger, "Compute.BeginStart", ActivityType.PUBLICAPI) def begin_start(self, name: str) -> LROPoller[None]: - """Start a compute. + """Start a compute instance. - :param name: The name of the compute. + :param name: The name of the compute instance. :type name: str :return: A poller to track the operation status. :rtype: azure.core.polling.LROPoller[None] .. admonition:: Example: - .. literalinclude:: ../../../../samples/ml_samples_misc.py + .. literalinclude:: ../../../../samples/ml_samples_compute.py :start-after: [START compute_operations_start] :end-before: [END compute_operations_start] :language: python :dedent: 8 - :caption: Start compute example. + :caption: Starting a compute instance. """ return self._operation.begin_start( @@ -295,21 +297,21 @@ def begin_start(self, name: str) -> LROPoller[None]: @distributed_trace @monitor_with_activity(logger, "Compute.BeginStop", ActivityType.PUBLICAPI) def begin_stop(self, name: str) -> LROPoller[None]: - """Stop a compute. + """Stop a compute instance. - :param name: The name of the compute. + :param name: The name of the compute instance. :type name: str :return: A poller to track the operation status. :rtype: azure.core.polling.LROPoller[None] .. admonition:: Example: - .. literalinclude:: ../../../../samples/ml_samples_misc.py + .. literalinclude:: ../../../../samples/ml_samples_compute.py :start-after: [START compute_operations_stop] :end-before: [END compute_operations_stop] :language: python :dedent: 8 - :caption: Stop compute example. + :caption: Stopping a compute instance. """ return self._operation.begin_stop( self._operation_scope.resource_group_name, @@ -320,21 +322,21 @@ def begin_stop(self, name: str) -> LROPoller[None]: @distributed_trace @monitor_with_activity(logger, "Compute.BeginRestart", ActivityType.PUBLICAPI) def begin_restart(self, name: str) -> LROPoller[None]: - """Restart a compute. + """Restart a compute instance. - :param name: The name of the compute. + :param name: The name of the compute instance. :type name: str :return: A poller to track the operation status. :rtype: azure.core.polling.LROPoller[None] .. admonition:: Example: - .. literalinclude:: ../../../../samples/ml_samples_misc.py + .. literalinclude:: ../../../../samples/ml_samples_compute.py :start-after: [START compute_operations_restart] :end-before: [END compute_operations_restart] :language: python :dedent: 8 - :caption: Restart compute example. + :caption: Restarting a stopped compute instance. """ return self._operation.begin_restart( self._operation_scope.resource_group_name, @@ -345,22 +347,23 @@ def begin_restart(self, name: str) -> LROPoller[None]: @distributed_trace @monitor_with_activity(logger, "Compute.ListUsage", ActivityType.PUBLICAPI) def list_usage(self, *, location: Optional[str] = None) -> Iterable[Usage]: - """Gets the current usage information as well as limits for AML resources for given subscription and location. + """List the current usage information as well as AzureML resource limits for the + given subscription and location. :keyword location: The location for which resource usage is queried. - If location not provided , defaults to workspace location - :paramtype location: str - :return: An iterator over current usage info - :rtype: ~azure.core.paging.ItemPaged[Usage] + Defaults to workspace location. + :paramtype location: Optional[str] + :return: An iterator over current usage info objects. + :rtype: ~azure.core.paging.ItemPaged[~azure.ai.ml.entities.Usage] .. admonition:: Example: - .. literalinclude:: ../../../../samples/ml_samples_misc.py + .. literalinclude:: ../../../../samples/ml_samples_compute.py :start-after: [START compute_operations_list_usage] :end-before: [END compute_operations_list_usage] :language: python :dedent: 8 - :caption: List current compute usage example. + :caption: Listing resource usage for the workspace location. """ if not location: location = self._get_workspace_location() @@ -372,23 +375,24 @@ def list_usage(self, *, location: Optional[str] = None) -> Iterable[Usage]: @distributed_trace @monitor_with_activity(logger, "Compute.ListSizes", ActivityType.PUBLICAPI) def list_sizes(self, *, location: Optional[str] = None, compute_type: Optional[str] = None) -> Iterable[VmSize]: - """Returns supported VM Sizes in a location. + """List the supported VM sizes in a location. :keyword location: The location upon which virtual-machine-sizes is queried. - If location not provided, defaults to workspace location. + Defaults to workspace location. :paramtype location: str - - :return: An iterator over virtual machine sizes. - :rtype: Iterable[VmSize] + :keyword compute_type: The type of the compute to be listed, case-insensitive. Defaults to AMLCompute. + :paramtype compute_type: Optional[str] + :return: An iterator over virtual machine size objects. + :rtype: Iterable[~azure.ai.ml.entities.VmSize] .. admonition:: Example: - .. literalinclude:: ../../../../samples/ml_samples_misc.py + .. literalinclude:: ../../../../samples/ml_samples_compute.py :start-after: [START compute_operations_list_sizes] :end-before: [END compute_operations_list_sizes] :language: python :dedent: 8 - :caption: List VM size example. + :caption: Listing the supported VM sizes in the workspace location. """ if not location: location = self._get_workspace_location() diff --git a/sdk/ml/azure-ai-ml/samples/ml_samples_compute.py b/sdk/ml/azure-ai-ml/samples/ml_samples_compute.py new file mode 100644 index 000000000000..3ac063b99735 --- /dev/null +++ b/sdk/ml/azure-ai-ml/samples/ml_samples_compute.py @@ -0,0 +1,267 @@ +# coding: utf-8 + +# ------------------------------------------------------------------------- +# Copyright (c) Microsoft Corporation. All rights reserved. +# Licensed under the MIT License. See License.txt in the project root for +# license information. +# -------------------------------------------------------------------------- + +""" +FILE: ml_samples_compute_configurations.py +DESCRIPTION: + These samples demonstrate different ways to configure Compute. +USAGE: + python ml_samples_compute_configurations.py + +""" + +import os + + +class ComputeConfigurationOptions(object): + def ml_compute_config(self): + from azure.ai.ml import MLClient + from azure.identity import DefaultAzureCredential + + subscription_id = os.environ["AZURE_SUBSCRIPTION_ID"] + resource_group = os.environ["RESOURCE_GROUP_NAME"] + credential = DefaultAzureCredential() + ml_client = MLClient(credential, subscription_id, resource_group, workspace_name="test-ws1") + + # [START compute_operations_get] + cpu_cluster = ml_client.compute.get("cpucluster") + # [END compute_operations_get] + + # [START load_compute] + from azure.ai.ml import load_compute + + compute = load_compute( + "../tests/test_configs/compute/compute-vm.yaml", + params_override=[{"description": "loaded from compute-vm.yaml"}], + ) + # [END load_compute] + + # [START compute_operations_list] + compute_list = ml_client.compute.list(compute_type="AMLK8s") # cspell:disable-line + # [END compute_operations_list] + + # [START compute_operations_list_nodes] + node_list = ml_client.compute.list_nodes(name="cpucluster") + # [END compute_operations_list_nodes] + + # [START compute_operations_create_update] + from azure.ai.ml.entities import AmlCompute + + compute_obj = AmlCompute( + name="example-compute", + tags={"key1": "value1", "key2": "value2"}, + min_instances=0, + max_instances=10, + idle_time_before_scale_down=100, + ) + registered_compute = ml_client.compute.begin_create_or_update(compute_obj) + # [END compute_operations_create_update] + + # [START compute_operations_attach] + compute_obj = AmlCompute( + name="example-compute-2", + tags={"key1": "value1", "key2": "value2"}, + min_instances=0, + max_instances=10, + idle_time_before_scale_down=100, + ) + attached_compute = ml_client.compute.begin_attach(compute_obj) + # [END compute_operations_attach] + + # [START compute_operations_update] + compute_obj = ml_client.compute.get("cpucluster") + compute_obj.idle_time_before_scale_down = 200 + updated_compute = ml_client.compute.begin_update(compute_obj) + # [END compute_operations_update] + + # [START compute_operations_delete] + ml_client.compute.begin_delete("example-compute", action="Detach") + + ml_client.compute.begin_delete("example-compute-2") + # [END compute_operations_delete] + + compute_obj = ComputeInstance( + name="example-compute", + tags={"key1": "value1", "key2": "value2"}, + min_instances=0, + max_instances=10, + idle_time_before_scale_down=100, + ) + registered_compute = ml_client.compute.begin_create_or_update(compute_obj) + + # [START compute_operations_start] + ml_client.compute.begin_start("example-compute") + # [END compute_operations_start] + + # [START compute_operations_stop] + ml_client.compute.begin_stop("example-compute") + # [END compute_operations_stop] + + # [START compute_operations_restart] + ml_client.compute.begin_stop("example-compute") + ml_client.compute.begin_restart("example-compute") + # [END compute_operations_restart] + + # [START compute_operations_list_usage] + print(ml_client.compute.list_usage()) + # [END compute_operations_list_usage] + + # [START compute_operations_list_sizes] + print(ml_client.compute.list_sizes()) + # [END compute_operations_list_sizes] + + # [START amlcompute] + from azure.ai.ml.entities import AmlCompute, IdentityConfiguration, ManagedIdentityConfiguration + + aml_compute = AmlCompute( + name="my-compute", + min_instances=0, + max_instances=10, + idle_time_before_scale_down=100, + identity=IdentityConfiguration( + type="UserAssigned", + user_assigned_identities=[ + ManagedIdentityConfiguration( + resource_id="/subscriptions/1234567-abcd-ef12-1234-12345/resourcegroups/our_rg_eastus/providers/Microsoft.ManagedIdentity/userAssignedIdentities/our-agent-aks" + ) + ], + ), + ) + # [END amlcompute] + + # [START aml_compute_ssh_settings] + from azure.ai.ml.entities import AmlComputeSshSettings + + ssh_settings = AmlComputeSshSettings( + admin_username="azureuser", + ssh_key_value="ssh-rsa ABCDEFGHIJKLMNOPQRSTUVWXYZ administrator@MININT-2023", + admin_password="password123", + ) + # [END aml_compute_ssh_settings] + + # [START compute_instance_ssh_settings] + from azure.ai.ml.entities import ComputeInstanceSshSettings + + ssh_settings = ComputeInstanceSshSettings( + ssh_key_value="ssh-rsa ABCDEFGHIJKLMNOPQRSTUVWXYZ administrator@MININT-2023" + ) + # [END compute_instance_ssh_settings] + + # [START assigned_user_configuration] + from azure.ai.ml.entities import AssignedUserConfiguration + + on_behalf_of_config = AssignedUserConfiguration(user_tenant_id="12345", user_object_id="abcdef") + # [END assigned_user_configuration] + + # [START compute_instance] + from azure.ai.ml.entities import ComputeInstance + + ci = ComputeInstance( + name="my-ci-resource", + location="eastus", + size="Standard_DS2_v2", + ssh_public_access_enabled=False, + ssh_key_value="ssh-rsa ABCDEFGHIJKLMNOPQRSTUVWXYZ administrator@MININT-2023", + ) + # [END compute_instance] + + # [START vm_ssh_settings] + from azure.ai.ml.entities import VirtualMachineSshSettings + + ssh_settings = VirtualMachineSshSettings( + admin_username="azureuser", + admin_password="azureuserpassword", + ssh_port=8888, + ssh_private_key_file="../tests/test_configs/compute/ssh_fake_key.txt", + ) + # [END vm_ssh_settings] + + # [START vm_compute] + from azure.ai.ml.entities import VirtualMachineCompute + + vm_compute = VirtualMachineCompute( + name="vm-compute", + resource_id="/subscriptions/123456-1234-1234-1234-123456789/resourceGroups/my-rg/providers/Microsoft.Compute/virtualMachines/my-vm", + ssh_settings=ssh_settings, + ) + # [END vm_compute] + + # [START network_settings] + from azure.ai.ml.entities import ( + AmlCompute, + IdentityConfiguration, + ManagedIdentityConfiguration, + NetworkSettings, + ) + + aml_compute = AmlCompute( + name="my-compute", + min_instances=0, + max_instances=10, + idle_time_before_scale_down=100, + network_settings=NetworkSettings(vnet_name="my-vnet", subnet="default"), + ) + # [END network_settings] + + # [START compute_runtime] + from azure.ai.ml.entities import ComputeRuntime + + compute_runtime = ComputeRuntime(spark_runtime_version="3.2.0") + # [END compute_runtime] + + # [START compute_start_stop_schedule] + from azure.ai.ml.constants import TimeZone + from azure.ai.ml.entities import ComputeSchedules, ComputeStartStopSchedule, CronTrigger + + start_stop = ComputeStartStopSchedule( + trigger=CronTrigger( + expression="15 10 * * 1", + start_time="2022-03-10 10:15:00", + end_time="2022-06-10 10:15:00", + time_zone=TimeZone.PACIFIC_STANDARD_TIME, + ) + ) + compute_schedules = ComputeSchedules(compute_start_stop=[start_stop]) + + # [END compute_start_stop_schedule] + + # [START image_metadata] + from azure.ai.ml.entities import ImageMetadata + + os_image_metadata = ImageMetadata( + current_image_version="22.08.19", + latest_image_version="22.08.20", + is_latest_os_image_version=False, + ) + # [END image_metadata] + + # [START kubernetes_compute] + from azure.ai.ml.entities import KubernetesCompute + + k8s_compute = KubernetesCompute( + identity=IdentityConfiguration( + type="UserAssigned", + user_assigned_identities=[ + ManagedIdentityConfiguration( + resource_id="/subscriptions/1234567-abcd-ef12-1234-12345/resourcegroups/our_rg_eastus/providers/Microsoft.ManagedIdentity/userAssignedIdentities/our-agent-aks" + ) + ], + ), + ) + # [END kubernetes_compute] + + # [START materialization_compute_resource] + from azure.ai.ml.entities import MaterializationComputeResource + + materialization_compute = MaterializationComputeResource(instance_type="standard_e4s_v3") + # [END materialization_compute_resource] + + +if __name__ == "__main__": + sample = ComputeConfigurationOptions() + sample.ml_compute_config()