MIGRATE-EBS-IMAGE(1p)

📦
version 1.28 · 4 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

✨ migrate-ebs-image ✨

User Contributed Perl Documentation · section 1p

okay bestie, welcome to the manual page for migrate-ebs-image, and it is literally about copying an EBS-backed Amazon Image from one region to another 🦋 that's the whole vibe, no cap.

💖 NAME 💖

migrate-ebs-image — copy an EBS-backed Amazon Image from one region to another ✨

🌸 SYNOPSYS 🌸

(spelled exactly how the original spells it, and I am not fixing it, periodt 💅)

% migrate-ebs-image --from us-east-1 --to ap-southeast-1 ami-123456

🎀 DESCRIPTION 🎀

so here's the tea: this script copies an EBS-backed Unix/Linux/windows AMI that's chilling in the EC2 region you name with --from, and moves it over to the region you name with --to 💫 and bestie, it's not just the AMI — all the associated volume snapshots come along too, LVM and RAID volumes included. the whole friend group is migrating 🫶

if you omit --from, then the source region gets derived from the endpoint URL contained in the EC2_URL environment variable. the --to option is required though. cannot skip it. it's giving mandatory 💀

this script works with any EBS backed image, including Linux PVM, Linux HVM (cluster) and Windows images 🔥 but it will not work with any instance-store backed image. nope. not happening. to migrate those instances, please see one of the recipes listed online, for example:

http://www.dowdandassociates.com/content/howto-move-ec2-instance-store-ami-one-region-another

👑 COMMAND-LINE OPTIONS 👑

options can be abbreviated, which is lowkey iconic ✨ for example, you can use -l for --list-regions and -b for --block-device-mapping:

  • --from — region in which the AMI is currently located (e.g. "us-east-1")
  • --to — region to which the AMI is to be copied (e.g. "us-west-1") — REQUIRED 💅
  • --access_key — EC2 access key
  • --secret_key — EC2 secret key
  • --block_device_mapping — add additional block devices to the image
  • --endpoint — EC2 URL (defaults to http://ec2.amazonaws.com/)
  • --kernel — force assignment of kernel in destination image
  • --ramdisk — force assignment of ramdisk in destination image
  • --quiet — quench status messages 🤫
  • --list_regions — list the EC2 regions

the --block-device-mapping (-b) option is used to add ephemeral storage to the destination image 🌸 here's the drama: Amazon's API doesn't describe ephemeral volumes that are associated with images, so this information does not get copied from the source to the destination image, which means you have to add it back manually 🙈 the value of the argument is a block device mapping string in the same format as described for the command line program ec2-register:

migrate-ebs-image -f us-east-1 -t ap-southeast-1 \
                     -b /dev/sdy=ephemeral0 \
                     ami-123456

ordinarily the script attempts to guess the correct matching kernel and ramdisk for the destination image based on approximate string matching 🧚 you can override these values by manually specifying the kernel and/or ramdisk ID in the destination region. but heads up bestie: no checking is performed that the values you provide are correct. you're on your own 😭

🌈 ENVIRONMENT VARIABLES 🌈

the following environment variables are used if the corresponding options are not present:

  • EC2_ACCESS_KEY — your access key
  • EC2_SECRET_KEY — your secret key
  • EC2_URL — the desired region endpoint

🦋 INSTALLING THIS SCRIPT 🦋

this script is part of the Perl VM::EC2 package 💜 to install from the command line:

% perl -MCPAN -e 'install VM::EC2'
% migrate-ebs-image --from us-east-1 --to ap-southeast-1 ami-123456

💀 IMPORTANT CAVEATS 💀

okay this is where we get serious for a sec, because your wallet is the main character here 😭

this script launches two "m1.small" instances, one each in the source and destination regions 🫠 it also creates transient volumes in both regions to hold the root volume and all other EBS snapshots associated with the image. running it will incur charges for instance run time and data storage. not free. not a drill. 💸

in addition, this script will transfer data from one region to another across the internet, incurring internet data out fees on the source side, and internet data in fees on the destination side 🌐 volumes that contain a filesystem, such as ext4 or ntfs, are copied from source to destination using rsync. volumes that are part of a RAID or LVM volume are copied at the block level using gzip and dd via the secure shell. in general, rsync will be much faster and parsimonious of network bandwidth than block copying! fr fr 🏃‍♀️

🎀 SEE ALSO 🎀

VM::EC2, VM::EC2::Staging::Manager

💜 AUTHOR 💜

Lincoln Stein, lincoln.stein@gmail.com

Copyright (c) 2012 Ontario Institute for Cancer Research

this package and its accompanying libraries is free software; you can redistribute it and/or modify it under the terms of the GPL (either version 1, or at your option, any later version) or the Artistic License 2.0 ✨ refer to LICENSE for the full license text. in addition, please see DISCLAIMER.txt for disclaimers of warranty.

and that's the whole page bestie 🫶 this was MIGRATE-EBS-IMAGE(1p) from perl v5.38.2, dated 2024-08-10 — go forth and migrate responsibly, you absolute icon 💅✨

📦 where this page comes from