Amazon Elastic Compute Cloud
CLI Reference (API Version 2014-02-01)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

ec2-describe-volume-status

Description

Describes the status of one or more volumes. Volume status provides the result of the checks performed on your volumes to determine events that can impair volume performance. The performance of a volume can be affected if an issue occurs on the volume's underlying host. If the volume's underlying host experiences a power outage or system issue, once the system is restored, there could be data inconsistencies on the volume. Volume events notify you if this occurs. Volume action notifies you if any action needs to be taken in response to the event.

The DescribeVolumeStatus operation provides the following information about the specified volumes:

Status: Reflects the current status of the volume. The possible values are ok, impaired , or insufficient-data. If all checks pass, the overall status of the volume is ok. If the check fails, the overall status is impaired. If the status is insufficient-data, then the checks may still be taking place on your volume at the time. We recommend that you retry the request. For more information on volume status, see Monitoring the Status of Your Volumes.

Events: Reflect the cause of a volume status and may require you to take an action. For example, if your volume returns an impaired status, then the volume event might be potential-data-inconsistency. This means that your volume has been impacted by an issue with the underlying host, has all I/O operations disabled, and may have inconsistent data.

Actions: Reflect the actions you may have to take in response to an event. For example, if the status of the volume is impaired and the volume event shows potential-data-inconsistency, then the action will show enable-volume-io. This means that you may want to enable the I/O operations for the volume by issuing the ec2-enable-volume-io command and then checking the volume for data consistency.

Note

Volume status is based on the volume status checks, and does not reflect the volume state. Therefore, volume status does not indicate volumes in the error state (for example, when a volume is incapable of accepting I/O.)

The short version of this command is ec2dvs.

Syntax

ec2-describe-volume-status [volume_id ...] [[--filter "name=value"] ...]

Options

NameDescription

volume_id

One or more volume IDs.

Type: String

Default: Describes the status of all your volumes.

Required: No

Example: vol-4282672b

-F, --filter name=value

A filter for limiting the results. For more information, see the Supported Filters section. Use quotation marks if the value string has a space ("name=value example"). On a Windows system, use quotation marks even without a space in the value string ("name=valueexample"). If you are using Windows Powershell, you might need to use a second set of quotation marks, escaped with backticks ("`"name=valueexample`"").

Type: String

Default: Describes all your volumes, or only those you specified.

Required: No

Example: --filter "volume-status.status=Ok"

Supported Filters

You can specify filters so that the response includes information for only certain volumes. For example, you can use a filter to specify that you're interested in volumes that have impaired status. You can specify multiple values for a filter. The response includes information for a volume only if it matches at least one of the filter values that you specified.

You can specify multiple filters; for example, specify volumes that are in a specific Availability Zone and have the status impaired. The response includes information for a volume only if it matches all the filters that you specified. If there's no match, no special message is returned; the response is simply empty.

You can use wildcards in a filter value. An asterisk (*) matches zero or more characters, and a question mark (?) matches exactly one character. You can escape special characters using a backslash (\) before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\.

The following are the available filters.

availability-zone

The Availability Zone of the instance.

Type: String

volume-status.status

The status of the volume.

Type: String

Valid values: ok | impaired | warning | insufficient-data

volume-status.details-name

The cause for the volume-status.status.

Type: String

Valid values: io-enabled | io-performance

volume-status.details-status

The status of the volume-status.details-name.

Type: String

Valid values for io-enabled: passed | failed

Valid values for io-performance: normal | degraded | severely-degraded | stalled

event.description

A description of the event.

Type: String

event.not-after

The latest end time for the event.

Type: DateTime

event.not-before

The earliest start time for the event.

Type: DateTime

event.event-id

The event ID.

Type: String

event.event-type

The event type.

Type: String

Valid values for io-enabled: potential-data-inconsistency

Valid values for io-performance: io-performance:degraded | io-performance:severely-degraded | io-performance:stalled

action.code

The action code for the event, for example, enable-volume-io

Type: String

action.event-id

The event ID associated with the action.

Type: String

action.description

A description of the action.

Type: String

Common Options

OptionDescription

--region region

The region. Overrides the default region, the region specified by the EC2_URL environment variable, and the URL specified by the -U option.

Default: The region specified by the EC2_URL environment variable, or us-east-1 if EC2_URL isn't set.

-U, --url url

The uniform resource locator (URL) of the Amazon EC2 web service entry point.

Default: The endpoint specified by the EC2_URL environment variable, or https://ec2.amazonaws.com if EC2_URL isn't set.

-O, --aws-access-key aws_access_key_id

Your access key ID. For more information, see Tell the Tools Who You Are.

Default: The value of the AWS_ACCESS_KEY environment variable. If AWS_ACCESS_KEY isn't set, you must specify this option.

Example: -O AKIAIOSFODNN7EXAMPLE

-W, --aws-secret-key aws_secret_access_key

Your secret access key.

Default: The value of the AWS_SECRET_KEY environment variable. If AWS_SECRET_KEY isn't set, you must specify this option.

Example: -W wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

-T, --security-token delegation_token

The AWS delegation token.

Default: The value of the environment variable (if set).

--connection-timeout timeout

The connection timeout, in seconds.

Example: --connection-timeout 30

--request-timeout timeout

The request timeout, in seconds.

Example: --request-timeout 45

-H, --headers

Includes column headers in the command output.

--show-empty-fields

Shows empty columns as (nil).

--hide-tags

Omits tags for tagged resources.

--debug

Displays internal debugging information. This can assist us when helping you troubleshooting problems.

-D, --auth-dry-run

Checks whether you have the required permissions for the command, without actually running the command. If you have the required permissions, the command returns DryRunOperation; otherwise, it returns UnauthorizedOperation.

-v, --verbose

Displays verbose output, including the API request and response on the command line. This is useful if you are building tools to talk directly to the Query API.

-

Reads arguments from standard input. This is useful when piping the output from one command to the input of another.

Example: ec2-describe-instances | grep stopped | cut -f 2 | ec2-start-instances -

-?, --help, -h

Displays usage information for the command.

Deprecated Options

For a limited time, you can still use the private key and X.509 certificate instead of your access key ID and secret access key. However, we recommend that you start using your access key ID (-O, --aws-access-key) and secret access key (-W, --aws-secret-key) now, as the private key (-K, --private-key) and X.509 certificate (-C, --cert) won't be supported after the transition period elapses. For more information, see Tell the Tools Who You Are.

OptionDescription

-K, --private-key ec2_private_key

The private key to use when constructing requests to Amazon EC2.

Default: The value of the EC2_PRIVATE_KEY environment variable.

Example: -K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-C, --cert ec2_cert

The X.509 certificate to use when constructing requests to Amazon EC2.

Default: The value of the EC2_CERT environment variable.

Example: -C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

Output

This command returns a table that contains the following information:

  • The VOLUME identifier

  • The ID of the volume

  • The Availability Zone in which the volume launched

  • The volume status name(Ok, impaired, io-enabled, insufficient-data)

  • The EVENT identifier

  • The ID of the event

  • The event type (potential-data-inconsistencies)

  • The description of the event

  • notBefore (the earliest start time of the event)

  • notAfter (the latest end time of the event)

  • The ACTION identifier

  • The action code (enable-volume-io)

  • The ID of the event associated with the action

  • The event type associated with the action (potential-data-inconsistency)

  • The description of the event associated with the action

Amazon EC2 command line tools display errors on stderr.

Examples

Example 1

This example command describes the status of the volumes with the IDs vol-111111 and vol-222222.

PROMPT> ec2-describe-volume-status  vol-111111 vol-222222
Type          VolumeId   AvailabilityZone VolumeStatus
VOLUME        vol-111111 us-east-1a       ok
VOLUME        vol-222222 us-east-1b       impaired
Type          Name       Status
VOLUMESTATUS  io-enabled failed
Type  EventType        NotBefore                NotAfter EventId   EventDescription
EVENT potential-data-inconsistency 2011-12-01T14:00:00.000Z          evol-61a54008  This is an example
Type   ActionCode                   EventId    EventType                        EventDescription
ACTION enable-volume-io             evol-61a54008  potential-data-inconsistency  This is an example				

Example 2

This example command describes the volumes you own that have failing I/O operations.

PROMPT> ec2-describe-volume-status --filter "volume-status.details-name=io-enabled" --filter "volume-status.details-status=failed"