EMR / Client / list_instance_fleets

list_instance_fleets

EMR.Client.list_instance_fleets(**kwargs)

Lists all available details about the instance fleets in a cluster.

Note

The instance fleet configuration is available only in Amazon EMR versions 4.8.0 and later, excluding 5.0.x versions.

See also: AWS API Documentation

Request Syntax

response = client.list_instance_fleets(
    ClusterId='string',
    Marker='string'
)

Parameters:

• ClusterId (string) –

  [REQUIRED]

  The unique identifier of the cluster.

• Marker (string) – The pagination token that indicates the next set of results to retrieve.

Return type:

dict

Returns:

Response Syntax

{
    'InstanceFleets': [
        {
            'Id': 'string',
            'Name': 'string',
            'Status': {
                'State': 'PROVISIONING'|'BOOTSTRAPPING'|'RUNNING'|'RESIZING'|'SUSPENDED'|'TERMINATING'|'TERMINATED',
                'StateChangeReason': {
                    'Code': 'INTERNAL_ERROR'|'VALIDATION_ERROR'|'INSTANCE_FAILURE'|'CLUSTER_TERMINATED',
                    'Message': 'string'
                },
                'Timeline': {
                    'CreationDateTime': datetime(2015, 1, 1),
                    'ReadyDateTime': datetime(2015, 1, 1),
                    'EndDateTime': datetime(2015, 1, 1)
                }
            },
            'InstanceFleetType': 'MASTER'|'CORE'|'TASK',
            'TargetOnDemandCapacity': 123,
            'TargetSpotCapacity': 123,
            'ProvisionedOnDemandCapacity': 123,
            'ProvisionedSpotCapacity': 123,
            'InstanceTypeSpecifications': [
                {
                    'InstanceType': 'string',
                    'WeightedCapacity': 123,
                    'BidPrice': 'string',
                    'BidPriceAsPercentageOfOnDemandPrice': 123.0,
                    'Configurations': [
                        {
                            'Classification': 'string',
                            'Configurations': {'... recursive ...'},
                            'Properties': {
                                'string': 'string'
                            }
                        },
                    ],
                    'EbsBlockDevices': [
                        {
                            'VolumeSpecification': {
                                'VolumeType': 'string',
                                'Iops': 123,
                                'SizeInGB': 123,
                                'Throughput': 123
                            },
                            'Device': 'string'
                        },
                    ],
                    'EbsOptimized': True|False,
                    'CustomAmiId': 'string'
                },
            ],
            'LaunchSpecifications': {
                'SpotSpecification': {
                    'TimeoutDurationMinutes': 123,
                    'TimeoutAction': 'SWITCH_TO_ON_DEMAND'|'TERMINATE_CLUSTER',
                    'BlockDurationMinutes': 123,
                    'AllocationStrategy': 'capacity-optimized'
                },
                'OnDemandSpecification': {
                    'AllocationStrategy': 'lowest-price',
                    'CapacityReservationOptions': {
                        'UsageStrategy': 'use-capacity-reservations-first',
                        'CapacityReservationPreference': 'open'|'none',
                        'CapacityReservationResourceGroupArn': 'string'
                    }
                }
            },
            'ResizeSpecifications': {
                'SpotResizeSpecification': {
                    'TimeoutDurationMinutes': 123
                },
                'OnDemandResizeSpecification': {
                    'TimeoutDurationMinutes': 123
                }
            }
        },
    ],
    'Marker': 'string'
}

Response Structure

• (dict) –

  • InstanceFleets (list) –

    The list of instance fleets for the cluster and given filters.

    • (dict) –

      Describes an instance fleet, which is a group of EC2 instances that host a particular node type (master, core, or task) in an Amazon EMR cluster. Instance fleets can consist of a mix of instance types and On-Demand and Spot Instances, which are provisioned to meet a defined target capacity.

      Note

      The instance fleet configuration is available only in Amazon EMR versions 4.8.0 and later, excluding 5.0.x versions.

      • Id (string) –

        The unique identifier of the instance fleet.

      • Name (string) –

        A friendly name for the instance fleet.

      • Status (dict) –

        The current status of the instance fleet.

        • State (string) –

          A code representing the instance fleet status.

          • PROVISIONING—The instance fleet is provisioning EC2 resources and is not yet ready to run jobs.

          • BOOTSTRAPPING—EC2 instances and other resources have been provisioned and the bootstrap actions specified for the instances are underway.

          • RUNNING—EC2 instances and other resources are running. They are either executing jobs or waiting to execute jobs.

          • RESIZING—A resize operation is underway. EC2 instances are either being added or removed.

          • SUSPENDED—A resize operation could not complete. Existing EC2 instances are running, but instances can’t be added or removed.

          • TERMINATING—The instance fleet is terminating EC2 instances.

          • TERMINATED—The instance fleet is no longer active, and all EC2 instances have been terminated.

        • StateChangeReason (dict) –

          Provides status change reason details for the instance fleet.

          • Code (string) –

            A code corresponding to the reason the state change occurred.

          • Message (string) –

            An explanatory message.

        • Timeline (dict) –

          Provides historical timestamps for the instance fleet, including the time of creation, the time it became ready to run jobs, and the time of termination.

          • CreationDateTime (datetime) –

            The time and date the instance fleet was created.

          • ReadyDateTime (datetime) –

            The time and date the instance fleet was ready to run jobs.

          • EndDateTime (datetime) –

            The time and date the instance fleet terminated.

      • InstanceFleetType (string) –

        The node type that the instance fleet hosts. Valid values are MASTER, CORE, or TASK.

      • TargetOnDemandCapacity (integer) –

        The target capacity of On-Demand units for the instance fleet, which determines how many On-Demand Instances to provision. When the instance fleet launches, Amazon EMR tries to provision On-Demand Instances as specified by InstanceTypeConfig. Each instance configuration has a specified WeightedCapacity. When an On-Demand Instance is provisioned, the WeightedCapacity units count toward the target capacity. Amazon EMR provisions instances until the target capacity is totally fulfilled, even if this results in an overage. For example, if there are 2 units remaining to fulfill capacity, and Amazon EMR can only provision an instance with a WeightedCapacity of 5 units, the instance is provisioned, and the target capacity is exceeded by 3 units. You can use InstanceFleet$ProvisionedOnDemandCapacity to determine the Spot capacity units that have been provisioned for the instance fleet.

        Note

        If not specified or set to 0, only Spot Instances are provisioned for the instance fleet using TargetSpotCapacity. At least one of TargetSpotCapacity and TargetOnDemandCapacity should be greater than 0. For a master instance fleet, only one of TargetSpotCapacity and TargetOnDemandCapacity can be specified, and its value must be 1.

      • TargetSpotCapacity (integer) –

        The target capacity of Spot units for the instance fleet, which determines how many Spot Instances to provision. When the instance fleet launches, Amazon EMR tries to provision Spot Instances as specified by InstanceTypeConfig. Each instance configuration has a specified WeightedCapacity. When a Spot instance is provisioned, the WeightedCapacity units count toward the target capacity. Amazon EMR provisions instances until the target capacity is totally fulfilled, even if this results in an overage. For example, if there are 2 units remaining to fulfill capacity, and Amazon EMR can only provision an instance with a WeightedCapacity of 5 units, the instance is provisioned, and the target capacity is exceeded by 3 units. You can use InstanceFleet$ProvisionedSpotCapacity to determine the Spot capacity units that have been provisioned for the instance fleet.

        Note

        If not specified or set to 0, only On-Demand Instances are provisioned for the instance fleet. At least one of TargetSpotCapacity and TargetOnDemandCapacity should be greater than 0. For a master instance fleet, only one of TargetSpotCapacity and TargetOnDemandCapacity can be specified, and its value must be 1.

      • ProvisionedOnDemandCapacity (integer) –

        The number of On-Demand units that have been provisioned for the instance fleet to fulfill TargetOnDemandCapacity. This provisioned capacity might be less than or greater than TargetOnDemandCapacity.

      • ProvisionedSpotCapacity (integer) –

        The number of Spot units that have been provisioned for this instance fleet to fulfill TargetSpotCapacity. This provisioned capacity might be less than or greater than TargetSpotCapacity.

      • InstanceTypeSpecifications (list) –

        An array of specifications for the instance types that comprise an instance fleet.

        • (dict) –

          The configuration specification for each instance type in an instance fleet.

          Note

          The instance fleet configuration is available only in Amazon EMR versions 4.8.0 and later, excluding 5.0.x versions.

          • InstanceType (string) –

            The EC2 instance type, for example m3.xlarge.

          • WeightedCapacity (integer) –

            The number of units that a provisioned instance of this type provides toward fulfilling the target capacities defined in InstanceFleetConfig. Capacity values represent performance characteristics such as vCPUs, memory, or I/O. If not specified, the default value is 1.

          • BidPrice (string) –

            The bid price for each EC2 Spot Instance type as defined by InstanceType. Expressed in USD.

          • BidPriceAsPercentageOfOnDemandPrice (float) –

            The bid price, as a percentage of On-Demand price, for each EC2 Spot Instance as defined by InstanceType. Expressed as a number (for example, 20 specifies 20%).

          • Configurations (list) –

            A configuration classification that applies when provisioning cluster instances, which can include configurations for applications and software bundled with Amazon EMR.

            • (dict) –

              Note

              Amazon EMR releases 4.x or later.

              An optional configuration specification to be used when provisioning cluster instances, which can include configurations for applications and software bundled with Amazon EMR. A configuration consists of a classification, properties, and optional nested configurations. A classification refers to an application-specific configuration file. Properties are the settings you want to change in that file. For more information, see Configuring Applications.

              • Classification (string) –

                The classification within a configuration.

              • Configurations (list) –

                A list of additional configurations to apply within a configuration object.

              • Properties (dict) –

                A set of properties specified within a configuration classification.

                • (string) –

                  • (string) –

          • EbsBlockDevices (list) –

            The configuration of Amazon Elastic Block Store (Amazon EBS) attached to each instance as defined by InstanceType.

            • (dict) –

              Configuration of requested EBS block device associated with the instance group.

              • VolumeSpecification (dict) –

                EBS volume specifications such as volume type, IOPS, size (GiB) and throughput (MiB/s) that are requested for the EBS volume attached to an EC2 instance in the cluster.

                • VolumeType (string) –

                  The volume type. Volume types supported are gp3, gp2, io1, st1, sc1, and standard.

                • Iops (integer) –

                  The number of I/O operations per second (IOPS) that the volume supports.

                • SizeInGB (integer) –

                  The volume size, in gibibytes (GiB). This can be a number from 1 - 1024. If the volume type is EBS-optimized, the minimum value is 10.

                • Throughput (integer) –

                  The throughput, in mebibyte per second (MiB/s). This optional parameter can be a number from 125 - 1000 and is valid only for gp3 volumes.

              • Device (string) –

                The device name that is exposed to the instance, such as /dev/sdh.

          • EbsOptimized (boolean) –

            Evaluates to TRUE when the specified InstanceType is EBS-optimized.

          • CustomAmiId (string) –

            The custom AMI ID to use for the instance type.

      • LaunchSpecifications (dict) –

        Describes the launch specification for an instance fleet.

        • SpotSpecification (dict) –

          The launch specification for Spot instances in the fleet, which determines the defined duration, provisioning timeout behavior, and allocation strategy.

          • TimeoutDurationMinutes (integer) –

            The Spot provisioning timeout period in minutes. If Spot Instances are not provisioned within this time period, the TimeOutAction is taken. Minimum value is 5 and maximum value is 1440. The timeout applies only during initial provisioning, when the cluster is first created.

          • TimeoutAction (string) –

            The action to take when TargetSpotCapacity has not been fulfilled when the TimeoutDurationMinutes has expired; that is, when all Spot Instances could not be provisioned within the Spot provisioning timeout. Valid values are TERMINATE_CLUSTER and SWITCH_TO_ON_DEMAND. SWITCH_TO_ON_DEMAND specifies that if no Spot Instances are available, On-Demand Instances should be provisioned to fulfill any remaining Spot capacity.

          • BlockDurationMinutes (integer) –

            The defined duration for Spot Instances (also known as Spot blocks) in minutes. When specified, the Spot Instance does not terminate before the defined duration expires, and defined duration pricing for Spot Instances applies. Valid values are 60, 120, 180, 240, 300, or 360. The duration period starts as soon as a Spot Instance receives its instance ID. At the end of the duration, Amazon EC2 marks the Spot Instance for termination and provides a Spot Instance termination notice, which gives the instance a two-minute warning before it terminates.

            Note

            Spot Instances with a defined duration (also known as Spot blocks) are no longer available to new customers from July 1, 2021. For customers who have previously used the feature, we will continue to support Spot Instances with a defined duration until December 31, 2022.

          • AllocationStrategy (string) –

            Specifies the strategy to use in launching Spot Instance fleets. Currently, the only option is capacity-optimized (the default), which launches instances from Spot Instance pools with optimal capacity for the number of instances that are launching.

        • OnDemandSpecification (dict) –

          The launch specification for On-Demand Instances in the instance fleet, which determines the allocation strategy.

          Note

          The instance fleet configuration is available only in Amazon EMR versions 4.8.0 and later, excluding 5.0.x versions. On-Demand Instances allocation strategy is available in Amazon EMR version 5.12.1 and later.

          • AllocationStrategy (string) –

            Specifies the strategy to use in launching On-Demand instance fleets. Currently, the only option is lowest-price (the default), which launches the lowest price first.

          • CapacityReservationOptions (dict) –

            The launch specification for On-Demand instances in the instance fleet, which determines the allocation strategy.

            • UsageStrategy (string) –

              Indicates whether to use unused Capacity Reservations for fulfilling On-Demand capacity.

              If you specify use-capacity-reservations-first, the fleet uses unused Capacity Reservations to fulfill On-Demand capacity up to the target On-Demand capacity. If multiple instance pools have unused Capacity Reservations, the On-Demand allocation strategy ( lowest-price) is applied. If the number of unused Capacity Reservations is less than the On-Demand target capacity, the remaining On-Demand target capacity is launched according to the On-Demand allocation strategy ( lowest-price).

              If you do not specify a value, the fleet fulfills the On-Demand capacity according to the chosen On-Demand allocation strategy.

            • CapacityReservationPreference (string) –

              Indicates the instance’s Capacity Reservation preferences. Possible preferences include:

              • open - The instance can run in any open Capacity Reservation that has matching attributes (instance type, platform, Availability Zone).

              • none - The instance avoids running in a Capacity Reservation even if one is available. The instance runs as an On-Demand Instance.

            • CapacityReservationResourceGroupArn (string) –

              The ARN of the Capacity Reservation resource group in which to run the instance.

      • ResizeSpecifications (dict) –

        The resize specification for the instance fleet.

        • SpotResizeSpecification (dict) –

          The resize specification for Spot Instances in the instance fleet, which contains the resize timeout period.

          • TimeoutDurationMinutes (integer) –

            Spot resize timeout in minutes. If Spot Instances are not provisioned within this time, the resize workflow will stop provisioning of Spot instances. Minimum value is 5 minutes and maximum value is 10,080 minutes (7 days). The timeout applies to all resize workflows on the Instance Fleet. The resize could be triggered by Amazon EMR Managed Scaling or by the customer (via Amazon EMR Console, Amazon EMR CLI modify-instance-fleet or Amazon EMR SDK ModifyInstanceFleet API) or by Amazon EMR due to Amazon EC2 Spot Reclamation.

        • OnDemandResizeSpecification (dict) –

          The resize specification for On-Demand Instances in the instance fleet, which contains the resize timeout period.

          • TimeoutDurationMinutes (integer) –

            On-Demand resize timeout in minutes. If On-Demand Instances are not provisioned within this time, the resize workflow stops. The minimum value is 5 minutes, and the maximum value is 10,080 minutes (7 days). The timeout applies to all resize workflows on the Instance Fleet. The resize could be triggered by Amazon EMR Managed Scaling or by the customer (via Amazon EMR Console, Amazon EMR CLI modify-instance-fleet or Amazon EMR SDK ModifyInstanceFleet API) or by Amazon EMR due to Amazon EC2 Spot Reclamation.

  • Marker (string) –

    The pagination token that indicates the next set of results to retrieve.

Exceptions

• EMR.Client.exceptions.InternalServerException

• EMR.Client.exceptions.InvalidRequestException