ec2-clone 1.1.0

Relaunch an AWS instance whilst maintaining the same configuration and data

EC2 Clone

Clone EC2 instances maintaining configuration and data.

Installation

pip install ec2-clone

Confirm installation with ec2-clone --help

Usage + Commands

Command	Description
replace-instance	Clone instance and terminate the source instance
clone-instance	Clone instance without terminating the source instance
create-ami	Create AMI from source instance
create-settings-json	Create instance JSON file from source instance
create-launch-template	Create launch template from source instance

Run as ec2-clone <command> --region <region> --instance-id <instance-id>

--instance-id and --region are required for all commands.

Replace Instance

Useful if a perfect copy of an instance is required. This includes private IP addresess and prefixes along with all other instance configuration.

Example

ec2-clone replace-instance --region eu-west-1 --instance-id i-12345678

Usage

Usage: ec2-clone replace-instance [OPTIONS]

  Clone instance and terminate the source instance

Options:
  --settings-input TEXT           Instance settings input file
  -l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]
                                  Log level as string
  --yes                           Assume yes to all prompts
  -r, --region TEXT               Region string in long format, e.g. eu-west-1
                                  [required]
  -i, --instance-id TEXT          Instance ID  [required]
  --ami-name TEXT                 Name used when creating new AMI
  --ami-suffix TEXT               Suffix used when creating new AMI. Full name
                                  will be \{instance-name\}\{suffix\}
  -a, --ami-id TEXT               AMI to use for new instances instead of
                                  creating a new one
  --instance-type TEXT            Override instance type
  --root-volume-size INTEGER      Size of new instances root volume in GB. If
                                  not set, root volume will be increased based
                                  on instance type to accomodate RAM for
                                  hibernation
  --encrypt-root-volume           Encrypt root volume
  --kms-key-id INTEGER            KMS key ID to use for root volume
                                  encryption. AWS EBS default key used if not
                                  specified
  --enable-hibernation            Increase root volume size, encrypt root
                                  volume and enable hibernation
  --help                          Show this message and exit.

Clone Instance

Useful if the private IP address of an instance does not need to be maintained.

Example

ec2-clone clone-instance --region eu-west-1 --instance-id i-12345678

Usage

Usage: ec2-clone clone-instance [OPTIONS]

  Clone instance without terminating the source instance

Options:
  --private-ip TEXT               Override instance private IP
  --ipv4-prefix TEXT              Override instance IPv4 prefix
  --settings-input TEXT           Instance settings input file
  --instance-name TEXT            Name used when creating new instance
  --instance-suffix TEXT          Suffix used when creating new instance. Full
                                  name will be \{instance-name\}\{suffix\}
  -l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]
                                  Log level as string
  --yes                           Assume yes to all prompts
  -r, --region TEXT               Region string in long format, e.g. eu-west-1
                                  [required]
  -i, --instance-id TEXT          Instance ID  [required]
  --ami-name TEXT                 Name used when creating new AMI
  --ami-suffix TEXT               Suffix used when creating new AMI. Full name
                                  will be \{instance-name\}\{suffix\}
  -a, --ami-id TEXT               AMI to use for new instances instead of
                                  creating a new one
  --instance-type TEXT            Override instance type
  --root-volume-size INTEGER      Size of new instances root volume in GB. If
                                  not set, root volume will be increased based
                                  on instance type to accomodate RAM for
                                  hibernation
  --encrypt-root-volume           Encrypt root volume
  --kms-key-id INTEGER            KMS key ID to use for root volume
                                  encryption. AWS EBS default key used if not
                                  specified
  --enable-hibernation            Increase root volume size, encrypt root
                                  volume and enable hibernation
  --help                          Show this message and exit.

Create AMI

Will only stop an instance and create an AMI. This step is performed automatically when running all other commands.

Example

ec2-clone create-ami --region eu-west-1 --instance-id i-12345678

Usage

Usage: ec2-clone create-ami [OPTIONS]

  Create AMI from source instance

Options:
  -l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]
                                  Log level as string
  --yes                           Assume yes to all prompts
  -r, --region TEXT               Region string in long format, e.g. eu-west-1
                                  [required]
  -i, --instance-id TEXT          Instance ID  [required]
  --ami-name TEXT                 Name used when creating new AMI
  --ami-suffix TEXT               Suffix used when creating new AMI. Full name
                                  will be \{instance-name\}\{suffix\}
  --help                          Show this message and exit.

Create Settings JSON

Useful for dumping only the relevant instance settings that are required for run_instances API call. If you need to modify more settings than are provided by the default CLI options you can use this command to generate a file to use as input, see Overrides below.

Example

ec2-clone create-settings-json --region eu-west-1 --instance-id i-12345678 --output settings.json

Usage: ec2-clone create-settings-json [OPTIONS]

  Create instance JSON file from source instance

Options:
  -o, --output-file TEXT          Output file when dumping settings
  --private-ip TEXT               Override instance private IP
  --ipv4-prefix TEXT              Override instance IPv4 prefix
  -l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]
                                  Log level as string
  --yes                           Assume yes to all prompts
  -r, --region TEXT               Region string in long format, e.g. eu-west-1
                                  [required]
  -i, --instance-id TEXT          Instance ID  [required]
  --ami-name TEXT                 Name used when creating new AMI
  --ami-suffix TEXT               Suffix used when creating new AMI. Full name
                                  will be \{instance-name\}\{suffix\}
  -a, --ami-id TEXT               AMI to use for new instances instead of
                                  creating a new one
  --instance-type TEXT            Override instance type
  --root-volume-size INTEGER      Size of new instances root volume in GB. If
                                  not set, root volume will be increased based
                                  on instance type to accomodate RAM for
                                  hibernation
  --encrypt-root-volume           Encrypt root volume
  --kms-key-id INTEGER            KMS key ID to use for root volume
                                  encryption. AWS EBS default key used if not
                                  specified
  --enable-hibernation            Increase root volume size, encrypt root
                                  volume and enable hibernation
  --help                          Show this message and exit.

Create Launch Template

Useful if you would like to use the AWS GUI to modify the instance settings before confirming the launch. As this method is not fully automated it can't perform the following:

• Move secondary network interfaces
• Tag Volumes
  • TODO - It is possible to tag volumes if there are tags (both key and values) that are shared between all volumes
• Move EIP

Example

ec2-clone create-launch-template --region eu-west-1 --instance-id i-12345678

Usage

Usage: ec2-clone create-launch-template [OPTIONS]

  Create launch template from source instance

Options:
  --private-ip TEXT               Instance settings input file
  --ipv4-prefix TEXT              Override instance IPv4 prefix
  --template-name TEXT            Name used when creating launch template
  --template-suffix TEXT          Suffix used when creating launch template.
                                  Full name will be \{instance-
                                  name\}\{suffix\}
  -l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]
                                  Log level as string
  --yes                           Assume yes to all prompts
  -r, --region TEXT               Region string in long format, e.g. eu-west-1
                                  [required]
  -i, --instance-id TEXT          Instance ID  [required]
  --ami-name TEXT                 Name used when creating new AMI
  --ami-suffix TEXT               Suffix used when creating new AMI. Full name
                                  will be \{instance-name\}\{suffix\}
  -a, --ami-id TEXT               AMI to use for new instances instead of
                                  creating a new one
  --instance-type TEXT            Override instance type
  --root-volume-size INTEGER      Size of new instances root volume in GB. If
                                  not set, root volume will be increased based
                                  on instance type to accomodate RAM for
                                  hibernation
  --encrypt-root-volume           Encrypt root volume
  --kms-key-id INTEGER            KMS key ID to use for root volume
                                  encryption. AWS EBS default key used if not
                                  specified
  --enable-hibernation            Increase root volume size, encrypt root
                                  volume and enable hibernation
  --help                          Show this message and exit.

Standard Usage

In standard operation, all instance settings will be copied across aside from a short number of rarely used parameters. (see Limitations below)

1. Ensure required permissions to relaunch instance are present.
   1. Including permissions for
      1. Volumes
      2. Snapshots
      3. AMIs
      4. EIPs
      5. Network Interfaces
      6. KMS Keys
      7. Instance Profiles
2. Configure AWS_ Environment Variables
   1. AWS_ACCESS_KEY_ID
   2. AWS_SECRET_ACCESS_KEY
   3. etc...
3. Run ec2-clone <command> following usage from above.

Enable Hibernation

1. Verify instance AMI supports hibernation (this can't be reliably confirmed programmatically)
   • Windows AMI Requirements
   • Linux AMI Requirements
2. Follow standard usage, but run with --enable-hibernation

Overrides

Standard operation allows for overriding common instance settings via the CLI. If further overrides are required a settings file can be used. The settings file will be passed directly to the run_instances API call allowing for full control over the new instance configuration.

clone-instance, replace-instance and create-launch-template can all take a file as input using --settings-input. The file is in JSON format, all possible parameters can be found here.

Generating settings

Often only a couple of parameters need overriding. The following workflow will generate a file containing the current instance settings. You can override only the values necessary before providing the modified file as input.

1. Run ec2-clone create-settings-json
   1. A file will be generated holding the configuration that would have been used to launch the new instance.
2. Modify the generated file to your liking
3. Run ec2-clone clone-instance|replace-instance|create-launch-template --settings-input <file> pointing to the modified file.

Limitations

In standard operation the following fields will not be copied between instances.

• Ipv6 Address count
• Ipv6 Addresses
• KernelId
• RamDiskId
• AdditionalInfo
• LaunchTemplate
• UserData

When using clone-instance

• Multiple private IP addresses on the primary nic
• Multiple Ipv4 prefixes on thee primary nic