describe-auto-scaling-groups¶

Description¶

Describes one or more Auto Scaling groups.

Synopsis¶

  describe-auto-scaling-groups
[--auto-scaling-group-names <value>]
[--cli-input-json | --cli-input-yaml]
[--starting-token <value>]
[--page-size <value>]
[--max-items <value>]
[--generate-cli-skeleton <value>]

Options¶

--auto-scaling-group-names (list)

The names of the Auto Scaling groups. By default, you can only specify up to 50 names. You can optionally increase this limit using the MaxRecords parameter.

If you omit this parameter, all Auto Scaling groups are described.

(string)

Syntax:

"string" "string" ...

--cli-input-json | --cli-input-yaml (string) Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with --cli-input-yaml.

--starting-token (string)

A token to specify where to start paginating. This is the NextToken from a previously truncated response.

For usage examples, see Pagination in the AWS Command Line Interface User Guide .

--page-size (integer)

The size of each page to get in the AWS service call. This does not affect the number of items returned in the command’s output. Setting a smaller page size results in more calls to the AWS service, retrieving fewer items in each call. This can help prevent the AWS service calls from timing out.

For usage examples, see Pagination in the AWS Command Line Interface User Guide .

--max-items (integer)

The total number of items to return in the command’s output. If the total number of items available is more than the value specified, a NextToken is provided in the command’s output. To resume pagination, provide the NextToken value in the starting-token argument of a subsequent command. Do not use the NextToken response element directly outside of the AWS CLI.

For usage examples, see Pagination in the AWS Command Line Interface User Guide .

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. Similarly, if provided yaml-input it will print a sample input YAML that can be used with --cli-input-yaml. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

See ‘aws help’ for descriptions of global parameters.

Examples¶

To get a description of an Auto Scaling group

This example describes the specified Auto Scaling group:

aws autoscaling describe-auto-scaling-groups --auto-scaling-group-name my-auto-scaling-group

This example describes the specified Auto Scaling groups. It allows you to specify up to 100 group names:

aws autoscaling describe-auto-scaling-groups --max-items 100 --auto-scaling-group-name "group1" "group2" "group3" "group4"

This example describes the Auto Scaling groups in the specified region, up to a maximum of 75 groups:

aws autoscaling describe-auto-scaling-groups --max-items 75 --region us-east-1

The following is example output:

{
    "AutoScalingGroups": [
        {
            "AutoScalingGroupARN": "arn:aws:autoscaling:us-west-2:123456789012:autoScalingGroup:930d940e-891e-4781-a11a-7b0acd480f03:autoScalingGroupName/my-auto-scaling-group",
            "HealthCheckGracePeriod": 300,
            "SuspendedProcesses": [],
            "DesiredCapacity": 1,
            "Tags": [],
            "EnabledMetrics": [],
            "LoadBalancerNames": [],
            "AutoScalingGroupName": "my-auto-scaling-group",
            "DefaultCooldown": 300,
            "MinSize": 0,
            "Instances": [
                {
                    "InstanceId": "i-4ba0837f",
                    "AvailabilityZone": "us-west-2c",
                    "HealthStatus": "Healthy",
                    "LifecycleState": "InService",
                    "LaunchConfigurationName": "my-launch-config"
                }
            ],
            "MaxSize": 1,
            "VPCZoneIdentifier": null,
            "TerminationPolicies": [
                "Default"
            ],
            "LaunchConfigurationName": "my-launch-config",
            "CreatedTime": "2013-08-19T20:53:25.584Z",
            "AvailabilityZones": [
                "us-west-2c"
            ],
            "HealthCheckType": "EC2",
            "NewInstancesProtectedFromScaleIn": false
        }
    ]
}

To return a specific number of Auto Scaling groups, use the max-items parameter:

aws autoscaling describe-auto-scaling-groups --max-items 1

If the output includes a NextToken field, there are more groups. To get the additional groups, use the value of this field with the starting-token parameter in a subsequent call as follows:

aws autoscaling describe-auto-scaling-groups --starting-token Z3M3LMPEXAMPLE

Output¶

AutoScalingGroups -> (list)

The groups.

(structure)

Describes an Auto Scaling group.

AutoScalingGroupName -> (string)

The name of the Auto Scaling group.

AutoScalingGroupARN -> (string)

The Amazon Resource Name (ARN) of the Auto Scaling group.

LaunchConfigurationName -> (string)

The name of the associated launch configuration.

LaunchTemplate -> (structure)

The launch template for the group.

LaunchTemplateId -> (string)

The ID of the launch template. To get the template ID, use the Amazon EC2 DescribeLaunchTemplates API operation. New launch templates can be created using the Amazon EC2 CreateLaunchTemplate API.

Conditional: You must specify either a LaunchTemplateId or a LaunchTemplateName .

LaunchTemplateName -> (string)

The name of the launch template. To get the template name, use the Amazon EC2 DescribeLaunchTemplates API operation. New launch templates can be created using the Amazon EC2 CreateLaunchTemplate API.

Conditional: You must specify either a LaunchTemplateId or a LaunchTemplateName .

Version -> (string)

The version number, $Latest , or $Default . To get the version number, use the Amazon EC2 DescribeLaunchTemplateVersions API operation. New launch template versions can be created using the Amazon EC2 CreateLaunchTemplateVersion API. If the value is $Latest , Amazon EC2 Auto Scaling selects the latest version of the launch template when launching instances. If the value is $Default , Amazon EC2 Auto Scaling selects the default version of the launch template when launching instances. The default value is $Default .

MixedInstancesPolicy -> (structure)

The mixed instances policy for the group.

LaunchTemplate -> (structure)

Specifies the launch template to use and optionally the instance types (overrides) that are used to provision EC2 instances to fulfill On-Demand and Spot capacities. Required when creating a mixed instances policy.

LaunchTemplateSpecification -> (structure)

The launch template to use.

LaunchTemplateId -> (string)

The ID of the launch template. To get the template ID, use the Amazon EC2 DescribeLaunchTemplates API operation. New launch templates can be created using the Amazon EC2 CreateLaunchTemplate API.

Conditional: You must specify either a LaunchTemplateId or a LaunchTemplateName .

LaunchTemplateName -> (string)

The name of the launch template. To get the template name, use the Amazon EC2 DescribeLaunchTemplates API operation. New launch templates can be created using the Amazon EC2 CreateLaunchTemplate API.

Conditional: You must specify either a LaunchTemplateId or a LaunchTemplateName .

Version -> (string)

The version number, $Latest , or $Default . To get the version number, use the Amazon EC2 DescribeLaunchTemplateVersions API operation. New launch template versions can be created using the Amazon EC2 CreateLaunchTemplateVersion API. If the value is $Latest , Amazon EC2 Auto Scaling selects the latest version of the launch template when launching instances. If the value is $Default , Amazon EC2 Auto Scaling selects the default version of the launch template when launching instances. The default value is $Default .

Overrides -> (list)

Any properties that you specify override the same properties in the launch template. If not provided, Amazon EC2 Auto Scaling uses the instance type specified in the launch template when it launches an instance.

(structure)

Describes an override for a launch template. The maximum number of instance types that can be associated with an Auto Scaling group is 40. The maximum number of distinct launch templates you can define for an Auto Scaling group is 20. For more information about configuring overrides, see Configuring overrides in the Amazon EC2 Auto Scaling User Guide .

InstanceType -> (string)

The instance type, such as m3.xlarge . You must use an instance type that is supported in your requested Region and Availability Zones. For more information, see Instance types in the Amazon Elastic Compute Cloud User Guide .

WeightedCapacity -> (string)

The number of capacity units provided by the specified instance type in terms of virtual CPUs, memory, storage, throughput, or other relative performance characteristic. When a Spot or On-Demand Instance is provisioned, the capacity units count toward the desired capacity. Amazon EC2 Auto Scaling provisions instances until the desired capacity is totally fulfilled, even if this results in an overage. For example, if there are 2 units remaining to fulfill capacity, and Amazon EC2 Auto Scaling can only provision an instance with a WeightedCapacity of 5 units, the instance is provisioned, and the desired capacity is exceeded by 3 units. For more information, see Instance weighting for Amazon EC2 Auto Scaling in the Amazon EC2 Auto Scaling User Guide . Value must be in the range of 1 to 999.

LaunchTemplateSpecification -> (structure)

Provides the launch template to be used when launching the instance type. For example, some instance types might require a launch template with a different AMI. If not provided, Amazon EC2 Auto Scaling uses the launch template that’s defined for your mixed instances policy. For more information, see Specifying a different launch template for an instance type in the Amazon EC2 Auto Scaling User Guide .

LaunchTemplateId -> (string)

The ID of the launch template. To get the template ID, use the Amazon EC2 DescribeLaunchTemplates API operation. New launch templates can be created using the Amazon EC2 CreateLaunchTemplate API.

Conditional: You must specify either a LaunchTemplateId or a LaunchTemplateName .

LaunchTemplateName -> (string)

The name of the launch template. To get the template name, use the Amazon EC2 DescribeLaunchTemplates API operation. New launch templates can be created using the Amazon EC2 CreateLaunchTemplate API.

Conditional: You must specify either a LaunchTemplateId or a LaunchTemplateName .

Version -> (string)

The version number, $Latest , or $Default . To get the version number, use the Amazon EC2 DescribeLaunchTemplateVersions API operation. New launch template versions can be created using the Amazon EC2 CreateLaunchTemplateVersion API. If the value is $Latest , Amazon EC2 Auto Scaling selects the latest version of the launch template when launching instances. If the value is $Default , Amazon EC2 Auto Scaling selects the default version of the launch template when launching instances. The default value is $Default .

InstancesDistribution -> (structure)

Specifies the instances distribution. If not provided, the value for each property in InstancesDistribution uses a default value.

OnDemandAllocationStrategy -> (string)

Indicates how to allocate instance types to fulfill On-Demand capacity. The only valid value is prioritized , which is also the default value. This strategy uses the order of instance types in the LaunchTemplateOverrides to define the launch priority of each instance type. The first instance type in the array is prioritized higher than the last. If all your On-Demand capacity cannot be fulfilled using your highest priority instance, then the Auto Scaling groups launches the remaining capacity using the second priority instance type, and so on.

OnDemandBaseCapacity -> (integer)

The minimum amount of the Auto Scaling group’s capacity that must be fulfilled by On-Demand Instances. This base portion is provisioned first as your group scales. Defaults to 0 if not specified. If you specify weights for the instance types in the overrides, set the value of OnDemandBaseCapacity in terms of the number of capacity units, and not the number of instances.

OnDemandPercentageAboveBaseCapacity -> (integer)

Controls the percentages of On-Demand Instances and Spot Instances for your additional capacity beyond OnDemandBaseCapacity . Expressed as a number (for example, 20 specifies 20% On-Demand Instances, 80% Spot Instances). Defaults to 100 if not specified. If set to 100, only On-Demand Instances are provisioned.

SpotAllocationStrategy -> (string)

Indicates how to allocate instances across Spot Instance pools.

If the allocation strategy is lowest-price , the Auto Scaling group launches instances using the Spot pools with the lowest price, and evenly allocates your instances across the number of Spot pools that you specify. Defaults to lowest-price if not specified.

If the allocation strategy is capacity-optimized (recommended), the Auto Scaling group launches instances using Spot pools that are optimally chosen based on the available Spot capacity. Alternatively, you can use capacity-optimized-prioritized and set the order of instance types in the list of launch template overrides from highest to lowest priority (from first to last in the list). Amazon EC2 Auto Scaling honors the instance type priorities on a best-effort basis but optimizes for capacity first.

SpotInstancePools -> (integer)

The number of Spot Instance pools across which to allocate your Spot Instances. The Spot pools are determined from the different instance types in the overrides. Valid only when the Spot allocation strategy is lowest-price . Value must be in the range of 1 to 20. Defaults to 2 if not specified.

SpotMaxPrice -> (string)

The maximum price per unit hour that you are willing to pay for a Spot Instance. If you leave the value at its default (empty), Amazon EC2 Auto Scaling uses the On-Demand price as the maximum Spot price. To remove a value that you previously set, include the property but specify an empty string (“”) for the value.

MinSize -> (integer)

The minimum size of the group.

MaxSize -> (integer)

The maximum size of the group.

DesiredCapacity -> (integer)

The desired size of the group.

DefaultCooldown -> (integer)

The duration of the default cooldown period, in seconds.

AvailabilityZones -> (list)

One or more Availability Zones for the group.

(string)

LoadBalancerNames -> (list)

One or more load balancers associated with the group.

(string)

TargetGroupARNs -> (list)

The Amazon Resource Names (ARN) of the target groups for your load balancer.

(string)

HealthCheckType -> (string)

The service to use for the health checks. The valid values are EC2 and ELB . If you configure an Auto Scaling group to use ELB health checks, it considers the instance unhealthy if it fails either the EC2 status checks or the load balancer health checks.

HealthCheckGracePeriod -> (integer)

The amount of time, in seconds, that Amazon EC2 Auto Scaling waits before checking the health status of an EC2 instance that has come into service.

Instances -> (list)

The EC2 instances associated with the group.

(structure)

Describes an EC2 instance.

InstanceId -> (string)

The ID of the instance.

InstanceType -> (string)

The instance type of the EC2 instance.

AvailabilityZone -> (string)

The Availability Zone in which the instance is running.

LifecycleState -> (string)

A description of the current lifecycle state. The Quarantined state is not used. For information about lifecycle states, see Instance lifecycle in the Amazon EC2 Auto Scaling User Guide .

HealthStatus -> (string)

The last reported health status of the instance. “Healthy” means that the instance is healthy and should remain in service. “Unhealthy” means that the instance is unhealthy and that Amazon EC2 Auto Scaling should terminate and replace it.

LaunchConfigurationName -> (string)

The launch configuration associated with the instance.

LaunchTemplate -> (structure)

The launch template for the instance.

LaunchTemplateId -> (string)

The ID of the launch template. To get the template ID, use the Amazon EC2 DescribeLaunchTemplates API operation. New launch templates can be created using the Amazon EC2 CreateLaunchTemplate API.

Conditional: You must specify either a LaunchTemplateId or a LaunchTemplateName .

LaunchTemplateName -> (string)

The name of the launch template. To get the template name, use the Amazon EC2 DescribeLaunchTemplates API operation. New launch templates can be created using the Amazon EC2 CreateLaunchTemplate API.

Conditional: You must specify either a LaunchTemplateId or a LaunchTemplateName .

Version -> (string)

The version number, $Latest , or $Default . To get the version number, use the Amazon EC2 DescribeLaunchTemplateVersions API operation. New launch template versions can be created using the Amazon EC2 CreateLaunchTemplateVersion API. If the value is $Latest , Amazon EC2 Auto Scaling selects the latest version of the launch template when launching instances. If the value is $Default , Amazon EC2 Auto Scaling selects the default version of the launch template when launching instances. The default value is $Default .

ProtectedFromScaleIn -> (boolean)

Indicates whether the instance is protected from termination by Amazon EC2 Auto Scaling when scaling in.

WeightedCapacity -> (string)

The number of capacity units contributed by the instance based on its instance type.

Valid Range: Minimum value of 1. Maximum value of 999.

CreatedTime -> (timestamp)

The date and time the group was created.

SuspendedProcesses -> (list)

The suspended processes associated with the group.

(structure)

Describes an auto scaling process that has been suspended.

For more information, see Scaling processes in the Amazon EC2 Auto Scaling User Guide .

ProcessName -> (string)

The name of the suspended process.

SuspensionReason -> (string)

The reason that the process was suspended.

PlacementGroup -> (string)

The name of the placement group into which to launch your instances, if any.

VPCZoneIdentifier -> (string)

One or more subnet IDs, if applicable, separated by commas.

EnabledMetrics -> (list)

The metrics enabled for the group.

(structure)

Describes an enabled metric.

Metric -> (string)

One of the following metrics:

GroupMinSize

GroupMaxSize

GroupDesiredCapacity

GroupInServiceInstances

GroupPendingInstances

GroupStandbyInstances

GroupTerminatingInstances

GroupTotalInstances

GroupInServiceCapacity

GroupPendingCapacity

GroupStandbyCapacity

GroupTerminatingCapacity

GroupTotalCapacity

Granularity -> (string)

The granularity of the metric. The only valid value is 1Minute .

Status -> (string)

The current state of the group when the DeleteAutoScalingGroup operation is in progress.

Tags -> (list)

The tags for the group.

(structure)

Describes a tag for an Auto Scaling group.

ResourceId -> (string)

The name of the group.

ResourceType -> (string)

The type of resource. The only supported value is auto-scaling-group .

Key -> (string)

The tag key.

Value -> (string)

The tag value.

PropagateAtLaunch -> (boolean)

Determines whether the tag is added to new instances as they are launched in the group.

TerminationPolicies -> (list)

The termination policies for the group.

(string)

NewInstancesProtectedFromScaleIn -> (boolean)

Indicates whether newly launched instances are protected from termination by Amazon EC2 Auto Scaling when scaling in.

ServiceLinkedRoleARN -> (string)

The Amazon Resource Name (ARN) of the service-linked role that the Auto Scaling group uses to call other AWS services on your behalf.

MaxInstanceLifetime -> (integer)

The maximum amount of time, in seconds, that an instance can be in service.

Valid Range: Minimum value of 0.

CapacityRebalance -> (boolean)

Indicates whether Capacity Rebalancing is enabled.

NextToken -> (string)

A string that indicates that the response contains more items than can be returned in a single response. To receive additional items, specify this string for the NextToken value when requesting the next set of items. This value is null when there are no more items to return.

Table of Contents

Feedback

User Guide