DetachVolumeCommand

Detaches an EBS volume from an instance. Make sure to unmount any file systems on the device within your operating system before detaching the volume. Failure to do so can result in the volume becoming stuck in the busy state while detaching. If this happens, detachment can be delayed indefinitely until you unmount the volume, force detachment, reboot the instance, or all three. If an EBS volume is the root device of an instance, it can't be detached while the instance is running. To detach the root volume, stop the instance first.

When a volume with an Amazon Web Services Marketplace product code is detached from an instance, the product code is no longer associated with the instance.

You can't detach or force detach volumes that are attached to Amazon ECS or Fargate tasks. Attempting to do this results in the UnsupportedOperationException exception with the Unable to detach volume attached to ECS tasks error message.

For more information, see Detach an Amazon EBS volume  in the Amazon EBS User Guide.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { EC2Client, DetachVolumeCommand } from "@aws-sdk/client-ec2"; // ES Modules import
// const { EC2Client, DetachVolumeCommand } = require("@aws-sdk/client-ec2"); // CommonJS import
const client = new EC2Client(config);
const input = { // DetachVolumeRequest
  Device: "STRING_VALUE",
  Force: true || false,
  InstanceId: "STRING_VALUE",
  VolumeId: "STRING_VALUE", // required
  DryRun: true || false,
};
const command = new DetachVolumeCommand(input);
const response = await client.send(command);
// { // VolumeAttachment
//   DeleteOnTermination: true || false,
//   AssociatedResource: "STRING_VALUE",
//   InstanceOwningService: "STRING_VALUE",
//   VolumeId: "STRING_VALUE",
//   InstanceId: "STRING_VALUE",
//   Device: "STRING_VALUE",
//   State: "attaching" || "attached" || "detaching" || "detached" || "busy",
//   AttachTime: new Date("TIMESTAMP"),
// };

Example Usage

 Loading code editor

DetachVolumeCommand Input

See DetachVolumeCommandInput for more details

Parameter
Type
Description
VolumeId
Required
string | undefined

The ID of the volume.

Device
string | undefined

The device name.

DryRun
boolean | undefined

Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Force
boolean | undefined

Forces detachment if the previous detachment attempt did not occur cleanly (for example, logging into an instance, unmounting the volume, and detaching normally). This option can lead to data loss or a corrupted file system. Use this option only as a last resort to detach a volume from a failed instance. The instance won't have an opportunity to flush file system caches or file system metadata. If you use this option, you must perform file system check and repair procedures.

InstanceId
string | undefined

The ID of the instance. If you are detaching a Multi-Attach enabled volume, you must specify an instance ID.

DetachVolumeCommand Output

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
AssociatedResource
string | undefined

The ARN of the Amazon ECS or Fargate task to which the volume is attached.

AttachTime
Date | undefined

The time stamp when the attachment initiated.

DeleteOnTermination
boolean | undefined

Indicates whether the EBS volume is deleted on instance termination.

Device
string | undefined

The device name.

If the volume is attached to a Fargate task, this parameter returns null.

InstanceId
string | undefined

The ID of the instance.

If the volume is attached to a Fargate task, this parameter returns null.

InstanceOwningService
string | undefined

The service principal of Amazon Web Services service that owns the underlying instance to which the volume is attached.

This parameter is returned only for volumes that are attached to Fargate tasks.

State
VolumeAttachmentState | undefined

The attachment state of the volume.

VolumeId
string | undefined

The ID of the volume.

Throws

Name
Fault
Details
EC2ServiceException
Base exception class for all service exceptions from EC2 service.