xjg-aws-relaunch-instance-test 0.1.2
Relaunch an AWS instance whilst maintaining the same configuration and data
Requires Python: >=3.6, <4

# AWS Relaunch Instance

Relaunches an EC2 instance maintaining the same configuration and data.

Will either

- Rename the source instance and launch a new instance with the original name
- Terminate the old instance and launch a new instance in its place
  - Necessary if an IP address conflict will block the new instance from being launched

## Usage

```text
Usage: python -m relaunch_instance [OPTIONS]

Options:
  -i, --instance-id TEXT          Instance ID  [required]
  -r, --region TEXT               Region string in long format  [required]
  -a, --ami-id TEXT               AMI to use for new instances instead of
                                  creating a new one
  --instance-type TEXT            Override instance type
  --private-ip 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            Encrypts root volume and increases root
                                  volume size to accomodate RAM.
  --settings-input TEXT           Instance settings input file
  --dump-settings                 Dump settings to file by name instead of
                                  running instance
  --settings-output TEXT          Output file when dumping settings
  -l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]
                                  Log level as string
  --yes                           Assume yes to all prompts
  --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 Limitaions 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`
   1. etc...
3. Run Script using usage above

### Enable Hibernation

1. Verify instance AMI supports hibernation (this can't be reliably confirmed programmatically)
    - [Windows AMI Requirements](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/hibernating-prerequisites.html#hibernation-prereqs-supported-amis)
    - [Linux AMI Requirements](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/hibernating-prerequisites.html#hibernation-prereqs-supported-amis)
2. Follow standard usage, but run with `--enable-hibernation`

### Generating Settings and Overrides

Standard operation allows for overriding common values through CLI options.

`--settings-input` takes a JSON file with parameters to pass to the `run_instances` API call, allowing for arbitrary overrides.
When passing in a settings file, all existing instance configuration is ignored. Only data will be copied between instances via an AMI.
To override only a couple of parameters, try the following:
1. Run the command with `--dump-settings`
   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 the command again with `--settings-input` pointing to the modified file

## Limitations

In standard operation the following fields will not be copied between instances. An important one to note is network interfaces. The script will only copy across the public IP address and the security group. The new instance will be configured with a single network interface as is standard for AWS. Additional network interfaces will need to manually added or migrated from the old instance.

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

## Modes

### Replacing an Instance

Source instances will be replaced if an IPv4 address conflict is detected.

1. Stop instance
2. Detach secondary nics if required
3. Remove Static IP if required
4. Create AMI
5. Attempt dry run launch of old instance to validate configuration and permissions
6. Terminate old instance
7. Launch new instance from AMI
    - Copy tags from old instance (including name)
    - Increasee root EBS volume size to accomodate RAM of new instance when hibernated
8. Reassociate EIP if required
9. Reassociate Nics if required

### Launching a new Instance

1. Verify instance configuration meets requirements for hibernation
2. Stop instance
2. Detach secondary nics if required
3. Remove Static IP if required
4. Create AMI
5. Attempt dry run launch of old instance to validate configuration and permissions
6. Rename old instance
6. Launch new instance from AMI
    - Copy tags from old instance (including name)
    - Increasee root EBS volume size to accomodate RAM of new instance when hibernated
7. Reassociate EIP if required

## Exit Codes

1. Minor error (e.g. connectivity issues to AWS, user abort)
2. Fatal error (e.g. invalid configuration)