Glacier

Introduction

Glacier is a data storage service provided by Amazon Web Services to suit the long-term storage of archives and backup of infrequently accessed data. It offers various retrieval options, different levels of retrieval speed, and more. Glacier uses a Vault container to store your data, similar to how S3 stores data in Buckets. A Vault further holds the data in an Archive, which can contain text, images, video, and audio files. Glacier uses Jobs to retrieve the data in an Archive or list the inventory of a Vault.

LocalStack allows you to use the Glacier APIs in your local environment to manage Vaults and Archives. You can use the Glacier API to configure and set up vaults where you can store archives and manage them. The supported APIs are available on our API coverage page, which provides information on the extent of Glacier’s integration with LocalStack.

Getting started

This guide is designed for users new to Glacier and assumes basic knowledge of the AWS CLI and our awslocal wrapper script.

Start your LocalStack container using your preferred method. We will demonstrate how to create a vault, upload an archive, initiate a job to get an inventory details or download an archive, and delete the archive and vault with the AWS CLI.

Create a vault

You can create a vault using the CreateVault API. Run the follow command to create a Glacier Vault named sample-vault.

$ awslocal glacier create-vault --vault-name sample-vault --account-id -

You can get the details from your vault using the DescribeVault API. Run the following command to describe your vault.

$ awslocal glacier describe-vault --vault-name sample-vault --account-id -

On successful creation of the Glacier vault, you will see the following output:

{
    "VaultARN": "arn:aws:glacier:us-east-1:000000000000:vaults/sample-vault",
    "VaultName": "sample-vault",
    "CreationDate": "2023-09-11T15:07:28.000Z",
    "LastInventoryDate": "2023-09-11T15:07:28.000Z",
    "NumberOfArchives": 0,
    "SizeInBytes": 0
}

Upload an archive to a vault

You can upload an archive or an individual file to a vault using the UploadArchive API. Download a random image from the internet and save it as image.jpg. Run the following command to upload the file to your Glacier vault:

$ awslocal glacier upload-archive --vault-name sample-vault --account-id - --body image.jpg

On successful upload of the Glacier archive, you will see the following output:

{
    "location": "/000000000000/vaults/sample-vault/archives/d41d8cd98f00b204e9800998ecf8427e",
    "checksum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "archiveId": "d41d8cd98f00b204e9800998ecf8427e"
}

Initiate the retrieval of an archive from a vault

You can initiate the retrieval of an archive from a vault using the InitiateJob API.

To download an archive, you will need to initiate an archive-retrieval job first to make the Archive available for download.

$ awslocal glacier initiate-job --vault-name sample-vault  --account-id - --job-parameters '{"Type":"archive-retrieval","ArchiveId":"d41d8cd98f00b204e9800998ecf8427e"}'

On successful execution of the job, you will see the following output:

{
    "location": "//vaults/sample-vault/jobs/25CEOTJ7ZUR5Q7YY0B1O55AE4C3L1502EOHWMNY10IIYEBWEQB73D23S8BVYO9RTRTPLRK2LJLUCCRM52GDV87C9A4JW",
    "jobId": "25CEOTJ7ZUR5Q7YY0B1O55AE4C3L1502EOHWMNY10IIYEBWEQB73D23S8BVYO9RTRTPLRK2LJLUCCRM52GDV87C9A4JW"
}

List the jobs

You can list the current and previous processes, called Jobs, to monitor the requests sent to the Glacier API using the ListJobs API.

$ awslocal glacier list-jobs --vault-name sample-vault --account-id -

On successful execution of the command, you will see the following output:

{
    "JobList": [
        {
            "JobId": "25CEOTJ7ZUR5Q7YY0B1O55AE4C3L1502EOHWMNY10IIYEBWEQB73D23S8BVYO9RTRTPLRK2LJLUCCRM52GDV87C9A4JW",
            "Action": "ArchiveRetrieval",
            "ArchiveId": "d41d8cd98f00b204e9800998ecf8427e",
            "VaultARN": "arn:aws:glacier:us-east-1:000000000000:vaults/sample-vault",
            "CreationDate": "2023-09-11T15:25:54.000Z",
            "Completed": true,
            "StatusCode": "Succeeded",
            "ArchiveSizeInBytes": 0,
            "InventorySizeInBytes": 10000,
            "CompletionDate": "2023-09-11T15:25:59.000Z",
            "Tier": "Standard"
        }
    ]
}

Download the result of an archive retrieval

You can download the output of an ArchiveRetrieval job with the GetJobOutput API.

The data download process can be verified through the previous ListJobs call to check progress. Once the ArchiveRetrieval Job is complete, the data can be downloaded. You can use the JobId of the Job to download your archive with the following command:

$ awslocal glacier get-job-output --vault-name sample-vault --account-id - --job-id 25CEOTJ7ZUR5Q7YY0B1O55AE4C3L1502EOHWMNY10IIYEBWEQB73D23S8BVYO9RTRTPLRK2LJLUCCRM52GDV87C9A4JW my-archive.jpg

Retrieve the inventory information

You can also initiate the retrieval of the inventory of a vault using the same InitiateJob API.

Initiate a job of the specified type to get the details of the individual inventory items inside a Vault using the initiate-job command:

$ awslocal glacier initiate-job --vault-name sample-vault  --account-id - --job-parameters '{"Type":"inventory-retrieval","ArchiveId":"d41d8cd98f00b204e9800998ecf8427e"}'

On successful execution of the command, you will see the following output:

{
    "location": "//vaults/sample-vault/jobs/P5972CSWFR803BHX48OD1A7JWNBFJUMYVWCMZWY55ZJPIJMG1XWFV9ISZPZH1X3LBF0UV3UG6ORETM0EHE5R86Z47B1F",
    "jobId": "P5972CSWFR803BHX48OD1A7JWNBFJUMYVWCMZWY55ZJPIJMG1XWFV9ISZPZH1X3LBF0UV3UG6ORETM0EHE5R86Z47B1F"
}

In the same fashion as the archive retrieval, you can now download the result of the inventory retrieval job using GetJobOutput using the JobId from the result of the previous command:

$ awslocal glacier get-job-output \
   --vault-name sample-vault --account-id - --job-id P5972CSWFR803BHX48OD1A7JWNBFJUMYVWCMZWY55ZJPIJMG1XWFV9ISZPZH1X3LBF0UV3UG6ORETM0EHE5R86Z47B1F inventory.json

Inspecting the content of the inventory.json file, we can find an inventory of the vault:

{
  "VaultARN": "arn:aws:glacier:us-east-1:000000000000:vaults/sample-vault",
  "InventoryDate": "2023-09-11T17:20:48.000Z",
  "ArchiveList": [
    {
      "ArchiveId": "d41d8cd98f00b204e9800998ecf8427e",
      "ArchiveDescription": "",
      "CreationDate": "2023-09-11T15:13:41.000Z",
      "Size": 0,
      "SHA256TreeHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
  ]
}

Delete an archive

You can delete a Glacier archive using the DeleteArchive API.

Run the following command to delete the previously created archive:

$ awslocal glacier delete-archive \
      --vault-name sample-vault --account-id - --archive-id d41d8cd98f00b204e9800998ecf8427e

Delete a vault

You can delete a Glacier vault with the DeleteVault API.

Run the following command to delete the vault:

$ awslocal glacier delete-vault --vault-name sample-vault --account-id -