EC2UPLOADIMG-3.13(1)

📦 version 10.0.3, in opensuse-leap 16.0

✨ NAME ✨

okay bestie, welcome to the ec2uploadimg.1() manual page 💅. This is all about ec2uploadimg — upload a compressed raw image file to Amazon EC2 and create a snapshot or an AMI. periodt. 🎀

🌸 SYNOPSIS 🌸

ec2uploadimg [option] PATH_TO_FILE

💖 DESCRIPTION 💖

okay so here's the vibe: ec2uploadimg uploads a compressed raw image to Amazon EC2 using an existing EC2 AMI, then creates a snapshot or registers a new AMI from the image. ✨ The apparent size of the raw image is recommended to be 10 GB or less. It is expected that the raw image has 1 partition, i.e. the root partition is /dev/sda1. 🫶

The process of creating the image is literally this:

  • start an instance
  • create a storage volume and attach it to the running instance
  • create volume that will be the new root and attach it to the running instance
  • upload the image
  • unpack the image and dump it to the new root volume
  • detach the new root volume and create a snapshot
  • register a new AMI
  • clean up

🎀 OPTIONS 🎀

  • -a, --account ACCOUNT_NAME — specifies the account to use to connect to EC2. The account is specified in the config file ~/.ec2utils.conf. The account is specified as a section with [account-ACCOUNT_NAME] delimiter. The options of the sections are access_key_id secret_access_key ssh_key_name ssh_private_key — this allows the program to connect to EC2. If the access_key_id and/or secret_access_key are not found in ~/.ec2utils.conf, the search will use the ACCOUNT_NAME to look for a matching section [profile ACCOUNT_NAME] in ~/.aws/config or [ACCOUNT_NAME] in ~/.aws/credentials. 💅
  • --access-id AWS_ACCESS_KEY — specifies the AWS access key and overrides the value given for the account with the access_key_id in the configuration file. 🔑
  • -B, --backing-store EC2_BACKING_STORE — specifies the backing store type for the AMI to be created. The uploaded image is an EBS (Elastic Block Store) backed image and may be registered as using SSD or Magnetic media as the backing store when being launched. Possible values are ssd, mag, or one of the known storage classes. The generic identifier ssd is mapped to the gp2 storage class, and the mag identifier is mapped to the standard storage class. 🌈
  • --billing-codes BILLING_CODES — specifies the billing product codes to apply to the image during registration. This functionality is restricted to specific accounts within EC2. 💸
  • --boot-kernel AWS_AKI_ID — specifies the aki_id of the boot kernel that should be used when registering a Para-virtual image. This option overrides the aki_i386, aki_x86_64, or g2_aki_x86_64 value in the configuration file. 🧚
  • --boot-mode — optionally specify the boot mode for the image. Accepted values are legacy-bios, uefi, or uefi-preferred. If no boot mode is specified the default behavior for the instance type applies, uefi for aarch64 instances and bios for x86_64 based instances. An image with the uefi-preferred setting will boot using uefi if the instance type supports uefi, otherwise it will use bios. 👑
  • -d, --description IMAGE_DESCRIPTION — specifies a description for the image. The description will also be used for the snapshot. 📝
  • -e, --ec2-ami AWS_AMI_ID — specify the AMI ID of the image to launch that will be used to perform the upload operation. This value overrides the value given with the ami option for a given region in the configuration file. 🦋
  • -f, --file CONFIG_FILE — specifies the configuration file to use. The default is ~/.ec2utils.conf. 📁
  • --grub2 — specifies if the image being uploaded and registered as AMI uses the GRUB2 bootloader. In some cases GRUB2 is referred to as GRUB and the first incarnation of GRUB is referred to as GRUB-Legacy. Setting this switch will select the g2_aki_x86_64 value from the configuration file or will use the value given with --boot-kernel as the aki ID when a para virtual image is being registered. 🥾
  • --imds-support — optionally specify the version for accessing the Instance MetaData Service (IMDS). The default is to access the IMDS using the version 1.0 implementation. Accepted values are 2.0 alternatively prefixed with a v. 🛰️
  • -m, --machine ARCH — specifies the architecture for the VM to be created. Supported values are arm64, i386 or x86_64. 🖥️
  • -n, --name IMAGE_NAME — specifies the name of the AMI to be registered. 🏷️
  • -p, --private-key-file PRIVATE_KEY — specifies the path to the private ssh key file to use to connect with the instance that is being used to upload the raw image. This option overrides the value of the ssh_private_key in the configuration file. 🔐
  • -r, --regions EC2_REGIONS — a comma separated list of Amazon EC2 regions, or a single region. 🌍
  • --root-volume-size — specify the size in GB of the new root volume for the AMI being created. It is recommended to keep the root volume size to 10GB or less. 💾
  • --ssh-key-pair AWS_KEY_PAIR_NAME — specifies the key-pair name to use when launching the instance that is used to upload the raw image. The specified private key file must correlate to the key pair name given with this argument. This value overrides the value given for the account with the ssh_key_name in the configuration file. 🗝️
  • -s, --secret-key AWS_SECRET_KEY — specifies the AWS secret access key and overrides the value given for the account with the secret_access_key in the configuration file. 🤫
  • --security-group-ids AWS_SECURITY_GROUP_IDS — specifies a list of security group ids to apply to the helper instance. At least one of the groups must have port 22 open to support ssh connections. 🚪
  • --session-token AWS_SESSION_TOKEN — specifies the AWS session token. Only necessary when using temporary credentials. 🎟️
  • --snaponly — when this argument is set only a snapshot of the uploaded image will be created. The snapshot may then be used in a separate operation to register an AMI. 📸
  • --use-snapshot — when this argument is set the image will be created from an existing snapshot. The snapshotID is specified as the source variable. 🧩
  • --sriov-support — enable SRIOV support for HVM images. This implies that the appropriate driver has to be included in the image. ⚡
  • --ssh-timeout SSH_TIME_OUT — specifies the amount of time to wait in seconds to establish an SSH connection with the helper instance. ⏳
  • --tpm-support — optionally specify the version of the TPM implementation the OS in the image supports. This option can only be used if boot-mode is set to a value other than bios. Accepted values are 2.0 alternatively prefixed with a v. 🔒
  • -t, --type AWS_UPLOAD_INST_TYPE — specifies the instance type to launch for the instance being used to upload the image. This value overrides the value given with the instance_type option for a given region in the configuration file. 🧱
  • -u, --user AWS_INSTANCE_USER — specifies the user to use to connect to the instance being used to upload the image. This value overrides the value given with the user option for a given region in the configuration file. 🙋‍♀️
  • --use-private-ip — use the private IP of the helper instance to upload the new image. This is helpful when an image is to be created and only a private VPC is available. 🛡️
  • --use-root-swap — create the new image using the root swap method. The helper instance used to upload the image will be stopped and the created image volume will be attached to the helper instance. A new image is registered from the helper instance. This method of image creation is useful when meta data associated with the image used to launch the helper instance needs to be transferred to the new image. The new image creation may time out as a copy of the complete image disk needs to be made. The code will then skip the clean up and a storage volume, a target root volume and a stopped instance will remain in the users account. 😭
  • -V, --virt-type AWS_VIRT_TYPE — specifies the virtualization type to use for the image to be registered. Possible values are para (default) or hvm. 🌀
  • --vpc-subnet-id VPC_SUBNET_ID — specify the VPC subnet ID into which the helper instance should be launched. This option is useful if no default VPC is configured or it is desired to launch the helper instance into a private subnet of the VPC. For the use of a private subnet it may also be necessary to use the --use-private-ip command line option. The ID should start with subnet-. Instance type and subnets are to a certain degree linked in that it may not be possible to launch the configured helper instance type outside a VPC subnet. Therefore, if the --vpc-subnet-id is not specified on the command line and neither --ec2-ami or --instance-id are specified on the command line an attempt will be made to retrieve the subnet-id from the configuration. The configuration is subnet_id_REGION where region is one of the known region identifiers such as us-east-1. The region given with the --regions command line argument is used. Specifying multiple regions with the --regions argument and using the --vpc-subnet-id argument is incompatible. When targeting multiple regions the subnet-id must be set in the configuration file. 🕸️
  • --wait-count AWS_WAIT_COUNT — specifies the number of times to wait for the AWS operation timeout. The default value is 1 which is equivalent to 600 seconds. ⌛

🦋 EXAMPLE 🦋

ec2uploadimg --account example -d "My first image" -m x86_64 -n my_linux_image -r us-east-1 PATH_TO_COMPRESSED_FILE

Will upload the raw disk image contained in the PATH_TO_COMPRESSED_FILE and will register a new AMI from the image. 🎉

🌟 AUTHOR 🌟

Robert Schweikert (rjschwei@suse.com) 💖

and that's the whole ec2uploadimg.1() footer vibe, bestie — catch you in the group chat. 🫶✨

📦 where this page comes from