How do I migrate my RHEL BYOL EC2 instance license to an RHUI license?

Resolution

Important: Before you stop and start your instance, take the following actions:

• Create a snapshot of your Amazon Elastic Block Store (Amazon EBS) volume.
  Note: If your instance is instance store-backed or has instance store volumes that contain data, then Amazon EC2 deletes the data when you stop the instance.
• Temporarily remove the instance from its Amazon EC2 Auto Scaling group when you complete the resolution steps.
  Note: If you stop an instance that's in an Amazon EC2 Auto Scaling group, then you might terminate the instance based on your scale-in protection settings. Instances that you launch with Amazon EMR, AWS CloudFormation, or AWS Elastic Beanstalk might be in an Auto Scaling group.
• Set the instance shutdown behavior to Stop to make sure that the instances don't terminate when you stop them.

Note: When you stop and start an instance, the instance's public IP address changes. It's a best practice to use an Elastic IP address to route external traffic to your instance instead of a public IP address. If you use Amazon Route 53, then you might need to update the Route 53 DNS records when the public IP address changes.

To migrate your instance to an RHUI license, complete the following steps:

1. If you use a proxy on your instance, then deactivate the proxy for the Instance Metadata Service (IMDS) IP address.

2. To identify whether your instance is uses a BYOL or AWS license, run the following command based on your IMDS version:
   IMDSv1:

   curl http://169.254.169.254/latest/dynamic/instance-identity/document 2>/dev/null | grep billingProducts

   IMDSv2:

   curl --noproxy '*' -w "\n" -s \
    -H "X-aws-ec2-metadata-token: \
    $(curl --noproxy '*' -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 300")" \
    http://169.254.169.254/latest/dynamic/instance-identity/document \
    | grep billingProducts

   Example output:

   $ curl http://169.254.169.254/latest/dynamic/instance-identity/document 2>/dev/null | grep billingProducts
    "billingProducts" : null,

   Note: If billingProducts is null, then the instance uses BYOL.

3. Use an AWS Marketplace Amazon Machine Image (AMI) to launch a new RHEL instance with the same RHEL version as the original instance. Make sure to use the same Availability Zone as the original instance, and then select a similar instance type.

4. Run the following command to check the instance's billing code, and then verify that the new instance uses RHUI:

   curl http://169.254.169.254/latest/dynamic/instance-identity/document 2>/dev/null | grep billingProducts
    "billingProducts" : [ "bp-6fa54006" ],

5. Run the following command to verify that the new instance has the RHUI client package installed:

    sudo rpm -qa | grep rhui

   Example output:

   $ sudo rpm -qa | grep rhui
   rh-amazon-rhui-client-4.0.4-1.el8.noarch

6. Run one of the following commands to download but not install the RHUI client package's RPM file on the new instance:

   sudo yum install --downloadonly --downloaddir=/tmp rh-amazon-rhui-client -y

   -or-

   sudo yumdownloader --downloaddir=/tmp rh-amazon-rhui-client

7. Run the following command to verify that you correctly downloaded the RPM package on the new instance:

   ls -l /tmp | grep rh-amazon-rhui-client
   -rw-r--r--. 1 root root 43680 Mar 4 19:42 rh-amazon-rhui-client-4.0.5-1.el8.noarch.rpm

8. Run one of the following commands to copy the RHUI client RPM file from the new to the original instance:

   scp /tmp/rh-amazon-rhui-client-*.rpm ec2-user@BYOL-instance-ip:/tmp/

   -or-

   rsync -avz /tmp/rh-amazon-rhui-client-*.rpm ec2-user@BYOL-instance-ip:/tmp/

9. Run the following command to remove existing RHUI configuration and packages from the original instance:

   sudo yum remove $(rpm -qa | grep rhui) -y

10. Run the following command to use the copied RPM file to install the RHUI client on the original instance:

    sudo yum install /tmp/rh-amazon-rhui-client-*.rpm -y

11. Run the following command to verify that you correctly installed the package on the original instance:

    sudo rpm -qa | grep rhui

12. Open the Amazon EC2 console, and then note your original instance's network configuration, such as the IP address, Elastic IP address, and security groups. You might need to create these settings in the new instance.

13. Stop the new and original instances.

14. Detach all Amazon EBS volumes from both instances. Note the device names or IDs of each volume on the original instance.

15. Attach the original instance's volumes to the new instance.
    Note: Use the same device names that the volumes had on the original instance:

16. Start the new instance.

17. Connect to the new instance, and then run the following command to verify that you can get the billing code:

    curl http://169.254.169.254/latest/dynamic/instance-identity/document 2>/dev/null | grep billingProducts
    "billingProducts" : [ "bp-6fa54006" ], 

18. Run the following command to verify that the repository configuration is correct:

    sudo yum clean all
    sudo yum repolist

19. Delete the original instance's detached volumes if you no longer need them. You can keep them as a backup as you validate your updates.

Troubleshoot issues

If the instance won't boot after you swap volumes, then verify that you attached the volumes to the correct device names. If you still encounter issues, then create a snapshot of the root volume and repeat the resolution steps.

If you can't access the repository, then run the following command to verify that you installed the RHUI client:

rpm -qa | grep rhui 

Also, check your network connectivity to the metadata server.

Related information

Migrate RHEL BYOL systems to AWS License-Included instances by using AWS Application Migration Service

Red Hat Enterprise Linux on Amazon EC2 FAQs