From c49e2176a2cd2fd7ddffb9d1586292975a22c0ca Mon Sep 17 00:00:00 2001 From: Carlos Bravo Date: Mon, 16 Dec 2024 11:48:45 -0300 Subject: [PATCH 1/6] Adds import local VMs documentation --- .wordlist.txt | 1 + aws/aws-how-to/index.rst | 1 + .../instances/import-local-vm-to-aws.rst | 137 ++++++++++++++++++ aws/aws-how-to/instances/index.rst | 2 + 4 files changed, 141 insertions(+) create mode 100644 aws/aws-how-to/instances/import-local-vm-to-aws.rst diff --git a/.wordlist.txt b/.wordlist.txt index 0798deb2..a32bc6f2 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -57,3 +57,4 @@ Jupyter MLflow PuTTy WSL +OVM diff --git a/aws/aws-how-to/index.rst b/aws/aws-how-to/index.rst index dc539133..2252fd31 100644 --- a/aws/aws-how-to/index.rst +++ b/aws/aws-how-to/index.rst @@ -21,6 +21,7 @@ While using Ubuntu on AWS, you'll need to perform tasks such as launching an ins * :doc:`Configure automated updates ` * :doc:`Deploy Charmed Kubernetes ` * :doc:`Deploy Canonical Data Science Stack ` +* :doc:`Importing a local Ubuntu VM to AWS ` EKS - Using Ubuntu Pro and GPUs on EKS diff --git a/aws/aws-how-to/instances/import-local-vm-to-aws.rst b/aws/aws-how-to/instances/import-local-vm-to-aws.rst new file mode 100644 index 00000000..f00338b6 --- /dev/null +++ b/aws/aws-how-to/instances/import-local-vm-to-aws.rst @@ -0,0 +1,137 @@ +Importing a local Ubuntu VM to AWS +================================== + +This document will guide you to import local virtual machines to AWS. +Please refer to the official `AWS Documentation`_ for more details. + +Requirements +------------ + +- An AWS account +- AWS CLI installed and configured +- A virtual machine exported in Open Virtual Appliance (OVA) format. AWS also supports Virtual Machine Disk (``VMDK``), Virtual Hard Disk (``VHD/VHDX``), and raw. + +.. note:: + Users running Ubuntu on KVM, OpenStack, LXD and other virtualization environments will most likely have ``qcow2`` files and not ``OVA``. Although ``qcow2`` is not supported, it is possible to use ``qemu-img`` to convert it to raw as follows: + + ``sudo qemu-img convert -O raw /var/lib/libvirt/images/my-machine.qcow2 my-machine.raw`` + + + +Upload your OVM machine image to S3 +----------------------------------- + + +Go to S3, create or reuse a bucket and upload the image there. Make a note of your bucket name. + +Create a containers JSON file +----------------------------- + +This file (say ``containers.json``) will specify the bucket and full path to the uploaded image for a single disk machine. In case of a multiple disk machine, each disk has to be defined in this file as a separate container (for instance, separate ``VDMK`` files). If you are importing a raw image, make sure to change the format and the image URL accordingly. + +.. code:: + + [ + { + "Description": "My imported Ubuntu august 2024", + "Format": "ova", + "Url": "s3://ubuntu-artifacts/ubuntu22.04.ova" + } + ] + + +Create an IAM role for the VM import process +-------------------------------------------- + + +Go to IAM, create a role called ``vmimport`` and get the access key. + + +In the process of creating the IAM role, you will create two files: ``role-policy.json`` and ``trust-policy.json``, as described in the AWS documentation. While ``trust-policy.json`` is used in the role creation process, ``role-policy.json`` will be used to create a policy allowing this role to read objects from the source S3 bucket and upload to the export S3 bucket. + + + +Import the VM +------------- + + +.. code:: + + aws ec2 import-image --description "My imported ubuntu server VM" --disk-containers "file://containers.json" --profile default --region us-east-1 + + +This command will return a task ID (``ImportTaskId``), which can be used to check its status. The task itself will take some time since it will import, convert, launch, and create an ami. + +You can check the status with: + +.. code:: + + aws ec2 describe-import-image-tasks + + +Once the status says "completed", make a note of the AMI ID. It’ll be used to launch the VM. + + +Launch it and install AWS-specific packages +------------------------------------------- + + +Your machine has been imported and is ready to be launched. We recommend some final steps to include an AWS-optimized kernel for better performance and other tools for enabling services such as SSM management (``amazon-ssm-agent``), EC2 instance connect (``ec2-instance-connect``) and hibernation (``ec2-hibinit-agent``). + +Launch your EC2 server using the AMI ID obtained in the previous step. This can be done using the AWS CLI or the EC2 web console. + +Ensure that you attach a security group that permits SSH access, as this will be the only method available to connect to the instance until tools like the SSM Agent or EC2 Instance Connect are installed. + +To learn more about launching an instance using AWS CLI, refer to our `official documentation`_. + +Once the machine is up and running, open an SSH session to your machine. If you are using Linux (including WSL on Windows) or MacOS, open a terminal window and connect to your machine using: + +.. code:: + + ssh -i <> ubuntu@<> + + + +If you are connecting from Windows, you can use PuTTy. + +Install the aws kernel: + +.. code:: + + sudo apt update && sudo apt install linux-aws + + + +Restart the machine. + + +(Optional) Install ssm agent and other tools +-------------------------------------------- + +.. code:: + + sudo snap install amazon-ssm-agent --classic + + sudo apt-get install ec2-instance-connect ec2-hibinit-agent + + +Get the VM image ready for production +------------------------------------- + +The VM image is almost ready to be used at scale on AWS. The last step is to allow cloud-init to reinitialize the machine ID. This ensures that each instance launched from this image will generate its own machine ID and will re-detect the cloud that it is running on so that certain features specific to AWS can be enabled. This is also needed if you’re planning to upgrade to Ubuntu Pro in the future. + +Run: + +.. code:: + + sudo cloud-init clean + + +Your machine is now ready. You can either continue using this VM as a normal EC2 instance or create another AMI from this instance to have your final golden image, ready for production. + + + +.. _`AWS documentation`: https://docs.aws.amazon.com/vm-import/latest/userguide/import-vm-image.html +.. _`official documentation`: https://documentation.ubuntu.com/aws/en/latest/aws-how-to/instances/launch-ubuntu-ec2-instance/#launch-the-instance + + diff --git a/aws/aws-how-to/instances/index.rst b/aws/aws-how-to/instances/index.rst index 691f29fb..30e31d03 100644 --- a/aws/aws-how-to/instances/index.rst +++ b/aws/aws-how-to/instances/index.rst @@ -14,6 +14,7 @@ Creating AMIs and CloudFormation templates: * :doc:`Build an Ubuntu Pro AMI using Packer ` * :doc:`Create CloudFormation templates ` +* :doc:`Importing a local Ubuntu VM to AWS ` Installing custom drivers and configuring network cards: @@ -51,4 +52,5 @@ Deploying Canonical Products: Configure automated updates Deploy Charmed Kubernetes Deploy Data Science Stack + Importing a local Ubuntu VM to AWS From 08b925c75a78392f9c4187faa108ab30009d57ac Mon Sep 17 00:00:00 2001 From: carlosbravoa Date: Tue, 17 Dec 2024 10:46:03 -0300 Subject: [PATCH 2/6] Apply suggestions from code review Text improvements as suggested by Dimple Co-authored-by: Dimple Kuriakose <123362247+k-dimple@users.noreply.github.com> --- aws/aws-how-to/index.rst | 2 +- aws/aws-how-to/instances/import-local-vm-to-aws.rst | 12 ++++++------ aws/aws-how-to/instances/index.rst | 4 ++-- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/aws/aws-how-to/index.rst b/aws/aws-how-to/index.rst index 2252fd31..8ba21a26 100644 --- a/aws/aws-how-to/index.rst +++ b/aws/aws-how-to/index.rst @@ -21,7 +21,7 @@ While using Ubuntu on AWS, you'll need to perform tasks such as launching an ins * :doc:`Configure automated updates ` * :doc:`Deploy Charmed Kubernetes ` * :doc:`Deploy Canonical Data Science Stack ` -* :doc:`Importing a local Ubuntu VM to AWS ` +* :doc:`Import a local Ubuntu VM into AWS ` EKS - Using Ubuntu Pro and GPUs on EKS diff --git a/aws/aws-how-to/instances/import-local-vm-to-aws.rst b/aws/aws-how-to/instances/import-local-vm-to-aws.rst index f00338b6..cbfd69e2 100644 --- a/aws/aws-how-to/instances/import-local-vm-to-aws.rst +++ b/aws/aws-how-to/instances/import-local-vm-to-aws.rst @@ -1,8 +1,8 @@ -Importing a local Ubuntu VM to AWS +Import a local Ubuntu VM into AWS ================================== -This document will guide you to import local virtual machines to AWS. -Please refer to the official `AWS Documentation`_ for more details. +This document will guide you to import local virtual machines (VMs) to AWS. +Please refer to the official `AWS Documentation: Import your VM as an image`_ for more details. Requirements ------------ @@ -60,7 +60,7 @@ Import the VM aws ec2 import-image --description "My imported ubuntu server VM" --disk-containers "file://containers.json" --profile default --region us-east-1 -This command will return a task ID (``ImportTaskId``), which can be used to check its status. The task itself will take some time since it will import, convert, launch, and create an ami. +This command will return a task ID (``ImportTaskId``), which can be used to check its status. The task itself will take some time since it will import, convert, launch, and create an AMI. You can check the status with: @@ -105,7 +105,7 @@ Install the aws kernel: Restart the machine. -(Optional) Install ssm agent and other tools +(Optional) Install SSM agent and other tools -------------------------------------------- .. code:: @@ -131,7 +131,7 @@ Your machine is now ready. You can either continue using this VM as a normal EC2 -.. _`AWS documentation`: https://docs.aws.amazon.com/vm-import/latest/userguide/import-vm-image.html +.. _`AWS documentation: Import your VM as an image`: https://docs.aws.amazon.com/vm-import/latest/userguide/import-vm-image.html .. _`official documentation`: https://documentation.ubuntu.com/aws/en/latest/aws-how-to/instances/launch-ubuntu-ec2-instance/#launch-the-instance diff --git a/aws/aws-how-to/instances/index.rst b/aws/aws-how-to/instances/index.rst index 30e31d03..4c69ab3c 100644 --- a/aws/aws-how-to/instances/index.rst +++ b/aws/aws-how-to/instances/index.rst @@ -14,7 +14,7 @@ Creating AMIs and CloudFormation templates: * :doc:`Build an Ubuntu Pro AMI using Packer ` * :doc:`Create CloudFormation templates ` -* :doc:`Importing a local Ubuntu VM to AWS ` +* :doc:`Import a local Ubuntu VM into AWS ` Installing custom drivers and configuring network cards: @@ -52,5 +52,5 @@ Deploying Canonical Products: Configure automated updates Deploy Charmed Kubernetes Deploy Data Science Stack - Importing a local Ubuntu VM to AWS + Import a local Ubuntu VM From 88b282cbfa55df703f40987671a8ffa3a387610b Mon Sep 17 00:00:00 2001 From: carlosbravoa Date: Tue, 17 Dec 2024 11:58:27 -0300 Subject: [PATCH 3/6] Update import-local-vm-to-aws.rst --- aws/aws-how-to/instances/import-local-vm-to-aws.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aws/aws-how-to/instances/import-local-vm-to-aws.rst b/aws/aws-how-to/instances/import-local-vm-to-aws.rst index cbfd69e2..df783b94 100644 --- a/aws/aws-how-to/instances/import-local-vm-to-aws.rst +++ b/aws/aws-how-to/instances/import-local-vm-to-aws.rst @@ -18,7 +18,7 @@ Requirements -Upload your OVM machine image to S3 +Upload your OVA machine image to S3 ----------------------------------- From 59210b22ef4deda82e075a85543238b1212988eb Mon Sep 17 00:00:00 2001 From: carlosbravoa Date: Tue, 17 Dec 2024 13:38:21 -0300 Subject: [PATCH 4/6] Update import-local-vm-to-aws.rst adding links to AWS documentation: Required IAM roles --- aws/aws-how-to/instances/import-local-vm-to-aws.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/aws/aws-how-to/instances/import-local-vm-to-aws.rst b/aws/aws-how-to/instances/import-local-vm-to-aws.rst index df783b94..b8e43452 100644 --- a/aws/aws-how-to/instances/import-local-vm-to-aws.rst +++ b/aws/aws-how-to/instances/import-local-vm-to-aws.rst @@ -44,7 +44,7 @@ Create an IAM role for the VM import process -------------------------------------------- -Go to IAM, create a role called ``vmimport`` and get the access key. +Go to IAM, create a role called ``vmimport`` and get the access key, as decribed in the official `AWS documentation: Required IAM roles`_ In the process of creating the IAM role, you will create two files: ``role-policy.json`` and ``trust-policy.json``, as described in the AWS documentation. While ``trust-policy.json`` is used in the role creation process, ``role-policy.json`` will be used to create a policy allowing this role to read objects from the source S3 bucket and upload to the export S3 bucket. @@ -132,6 +132,7 @@ Your machine is now ready. You can either continue using this VM as a normal EC2 .. _`AWS documentation: Import your VM as an image`: https://docs.aws.amazon.com/vm-import/latest/userguide/import-vm-image.html +.. _`AWS documentation: Required IAM roles`: https://docs.aws.amazon.com/vm-import/latest/userguide/required-permissions.html#vmimport-role .. _`official documentation`: https://documentation.ubuntu.com/aws/en/latest/aws-how-to/instances/launch-ubuntu-ec2-instance/#launch-the-instance From c37306c0891aee94af70ee7f7d099a84ca494e1d Mon Sep 17 00:00:00 2001 From: carlosbravoa Date: Tue, 17 Dec 2024 13:38:56 -0300 Subject: [PATCH 5/6] Update .wordlist.txt --- .wordlist.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.wordlist.txt b/.wordlist.txt index a32bc6f2..582a27c2 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -57,4 +57,4 @@ Jupyter MLflow PuTTy WSL -OVM +OVA From b63dc7b8d50fccd94d6c20cbc781b1252c4cb5e0 Mon Sep 17 00:00:00 2001 From: Dimple Kuriakose <123362247+k-dimple@users.noreply.github.com> Date: Tue, 17 Dec 2024 22:41:02 +0530 Subject: [PATCH 6/6] correct typo --- aws/aws-how-to/instances/import-local-vm-to-aws.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aws/aws-how-to/instances/import-local-vm-to-aws.rst b/aws/aws-how-to/instances/import-local-vm-to-aws.rst index b8e43452..8b1ff4b3 100644 --- a/aws/aws-how-to/instances/import-local-vm-to-aws.rst +++ b/aws/aws-how-to/instances/import-local-vm-to-aws.rst @@ -44,10 +44,10 @@ Create an IAM role for the VM import process -------------------------------------------- -Go to IAM, create a role called ``vmimport`` and get the access key, as decribed in the official `AWS documentation: Required IAM roles`_ +Go to IAM, create a role called ``vmimport`` and get the access key, as described in the official `AWS documentation: Required IAM roles`_ -In the process of creating the IAM role, you will create two files: ``role-policy.json`` and ``trust-policy.json``, as described in the AWS documentation. While ``trust-policy.json`` is used in the role creation process, ``role-policy.json`` will be used to create a policy allowing this role to read objects from the source S3 bucket and upload to the export S3 bucket. +In the process of creating the IAM role, you will create two files: ``role-policy.json`` and ``trust-policy.json``. While ``trust-policy.json`` is used in the role creation process, ``role-policy.json`` will be used to create a policy allowing this role to read objects from the source S3 bucket and upload to the export S3 bucket.