How can I restore an Amazon S3 object from the S3 Glacier Flexible Retrieval or S3 Glacier Deep Archive storage class using the AWS CLI?

Last updated: 2022-10-03

I archived an Amazon Simple Storage Service (Amazon S3) object to the Amazon S3 Glacier Flexible Retrieval (formerly Glacier) or Amazon S3 Glacier Deep Archive storage class by using a lifecycle configuration. How do I restore the object using the AWS Command Line Interface (AWS CLI)?

Resolution

Use the following steps to restore an S3 object from the S3 Glacier Flexible Retrieval storage or S3 Glacier Deep Archive class using the AWS CLI.

Note: If you receive errors when running AWS CLI commands, make sure that you’re using the most recent AWS CLI version.

Initiate a restore request

Run the following command to initiate a restore request. Be sure to replace all the values in the example command with the values for your bucket, object, and restore request.

Note: Because data retrieval charges are based on the quantity of requests, be sure to confirm that the parameters of your restore request are correct.

$ aws s3api restore-object --bucket awsexamplebucket --key dir1/example.obj --restore-request '{"Days":25,"GlacierJobParameters":{"Tier":"Standard"}}'

After you run this command, a temporary copy of the object is available for the duration specified in the restore request. In this example, the duration specified in the restore request is 25 days while the restore tier is set to S3 Standard.

Note the following modifications that you can make to the command:

  • To restore a specific object version in a versioned bucket, include the --version-id option, and then specify the corresponding version ID.
  • For the S3 Glacier Flexible Retrieval storage class, you can use the Expedited, Standard, or Bulk retrieval options. However, you can use only the Standard or Bulk retrieval options for the S3 Glacier Deep Archive storage class.
  • If the JSON syntax used in the example results in an error on a Windows client, then replace the restore request with the following syntax:
--restore-request Days=25,GlacierJobParameters={"Tier"="Standard"}

Note: If an object is stored in S3 Glacier Instant Retrieval, then data retrieval is instant and the restore operation isn't needed. For more information, see Object Storage Classes.

Monitor the status of your restore request

Run the following command to monitor the status of your restore request:

aws s3api head-object --bucket awsexamplebucket --key dir1/example.obj

If the restore is still in progress after you run the command, you receive a response similar to the following:

{
    "Restore": "ongoing-request=\"true\"",
    ...
    "StorageClass": "GLACIER | DEEP_ARCHIVE",
    "Metadata": {}
}

After the restore is complete, you receive a response similar to the following:

{
    "Restore": "ongoing-request=\"false\", expiry-date=\"Sun, 13 Aug 2017 00:00:00 GMT\"",
    ...
    "StorageClass": "GLACIER | DEEP_ARCHIVE",
    "Metadata": {}
}

Note the expiry-date in the response—you have until this time to access the temporary store object (stored in the S3 Standard storage class). The temporary object is available alongside the archived object that's in the S3 Glacier Flexible Retrieval or S3 Glacier Deep Archive storage class. After the expiry-date elapses, the temporary object is removed. You must change the object's storage class before the temporary object expires. To change the object's storage class after the expiry-date, you must initiate a new restore request.

Change the object's storage class to Amazon S3 Standard

To change the object's storage class to Amazon S3 Standard, use copy. You can overwrite the existing object or copy the object into another location.

Warning: If you're using version 1.x of the AWS CLI, make sure that the multipart threshold is set to 5 GB before copying an object. Otherwise, the object's user metadata is lost when the object size is larger than the multipart thresholds of the AWS CLI. For objects larger than 5 GB, use version 2.x of the AWS CLI to preserve user metadata.

(Optional) To increase the multipart threshold of the AWS CLI, run the following command:

aws configure set default.s3.multipart_threshold 5GB

To overwrite the existing object with the Amazon S3 Standard storage class, run the following command:

aws s3 cp s3://awsexamplebucket/dir1/example.obj s3://awsexamplebucket/dir1/example.obj --storage-class STANDARD

To perform a recursive copy for an entire prefix and overwrite existing objects with the Amazon S3 Standard storage class, run the following command:

aws s3 cp s3://awsexamplebucket/dir1/ s3://awsexamplebucket/dir1/ --storage-class STANDARD --recursive --force-glacier-transfer

Note: Objects that are archived to S3 Glacier Flexible Retrieval have a minimum storage duration of 90 days. Objects that are archived to S3 Glacier Deep Archive have a minimum storage duration of 180 days. If you have overwritten an object in S3 Glacier Flexible Retrieval before the 90-day minimum, you are charged for 90 days. Similarly, objects that are in S3 Glacier Deep Archive and are overwritten before the 180-day minimum, you are charged for 180 days.

To copy the object into another location, run the following command:

aws s3 cp s3://awsexamplebucket/dir1/example.obj s3://awsexamplebucket/dir2/example2.obj

Note: For suspended buckets or buckets with versioning enabled, this step creates additional copies of objects. These additional objects also incur storage costs. To avoid storage costs, remove the non-current versions that are still in the Amazon S3 Glacier storage class or create an S3 Lifecycle expiration rule.