Skip to content

Register a Machine Image

Intermediate 10 minutes Auto-generated screenshots

Overview

Registering a machine image in RosettaHub allows you to launch any AWS, Azure, or GCP instance directly from the platform and benefit from full lifecycle management -- start, stop, hibernate, snapshot, and delete -- all from the dashboard. RosettaHub stores the connection credentials for each image, so you can securely connect to your instances at any time without managing keys manually.

Multiple MetaCloud image entries can reference the same underlying cloud resource (e.g., the same AMI), each with different labels, key associations, or port configurations. This many-to-one mapping gives teams flexibility to reuse a single cloud image across different contexts.

Prerequisites

  • [ ] RosettaHub account with active subscription
  • [ ] At least one cloud account connected (see Cloud Accounts)
  • [ ] A Cloud Key provisioned for the region where your image resides (see Working with Keys)
  • [ ] The cloud image ID you want to register (e.g., an AWS AMI ID, Azure resource ID, or GCP image name)

Steps

Step 1: Find Your Cloud Image ID

Before creating the image in RosettaHub, locate the image identifier in your cloud provider's console.

Provider Format Example
AWS AMI ID starting with ami- ami-0abcdef1234567890
Azure (Custom Image) Full resource ID /subscriptions/.../images/myImage
Azure (Marketplace) Colon-separated publisher:offer:sku:version Canonical:UbuntuServer:18_04-lts-gen2:latest
GCP Project and image name ubuntu-os-cloud/ubuntu-2204-lts

Tip

For AWS, you can find AMI IDs in the EC2 console under Images > AMIs. For Azure Marketplace images, the publisher, offer, SKU, and version are listed on the marketplace image detail page.

Step 2: Open the Create Image Dialog

From the dashboard, navigate to the Images panel. Click the plus sign (+) to open the Create Image form.

Step 3: Select the Key Set

Choose the Cloud Key to associate with this image. The key determines which cloud account, region, and VPC the image can be launched into.

Warning

The Cloud Key and the image must be in the same cloud region -- otherwise the launch will fail. The one exception is Azure Marketplace images, which are available across regions.

Step 4: Enter a Label

Input a recognizable Label for the image. This is the name that will appear in your Images panel and in any formations that reference it.

Tip

Use descriptive labels that include the OS, version, and purpose -- for example, Ubuntu 22.04 - ML Training Base or Windows Server 2022 - Dev.

Step 5: Enter the Image ID

Input the Image ID you identified in Step 1.

Step 6: Enter the User Name

Input the User Name associated with the image. This is the default login account used when connecting to instances launched from this image.

OS / Provider Default User Name
Windows (all providers) Administrator
Amazon Linux ec2-user
Ubuntu (AWS) ubuntu
CentOS (AWS) centos
Debian (AWS) admin
RHEL (AWS) ec2-user
Azure Linux Varies by image (often azureuser)
GCP Linux Varies by image

Note

If you are unsure of the username, check the cloud provider's documentation for the specific image. Using the wrong username will prevent SSH connections.

Step 7: Select the Operating System

Choose the Operating System that matches your image:

  • Windows
  • Ubuntu
  • CentOS
  • Amazon Linux

Step 8: Enter the OS Version

Input the OS version number (e.g., 22.04 for Ubuntu, 2022 for Windows Server).

Step 9: Configure Default Ports

Input the default inbound ports that should be opened when launching instances from this image.

Note

RosettaHub automatically opens SSH (port 22) for Linux images and RDP (port 3389) for Windows images. You only need to add additional ports here, such as 8888 for Jupyter or 8080 for a web server.

Step 10: Create the Image

Click Create to register the image in RosettaHub.

The new image appears in your Images panel and is ready to launch. You can also use it in formations, share it with other users, or publish it to the RosettaHub Marketplace.

Next Steps

Troubleshooting

Image creation fails with 'invalid image ID'

Verify the image ID format matches your cloud provider:

  • AWS AMIs must start with ami- followed by a hex string
  • Azure custom images require the full resource path
  • Azure Marketplace images must use the publisher:offer:sku:version format

Double-check for typos or extra whitespace.

Cannot find my Cloud Key in the Key Set dropdown

Ensure that:

  • You have a Cloud Key provisioned for the correct cloud provider and region
  • Your cloud account is active and connected
  • You have permission to use the key (check with your organization administrator)

See Working with Keys for key management details.

Image created but launch fails

This may indicate:

  • The image ID does not exist or has been deregistered in the cloud provider
  • The Cloud Key region does not match the image region
  • Your cloud account lacks permissions to launch from this image
  • The image requires a specific instance type that is not available

Check your cloud provider console to confirm the image is still available.

Wrong username -- cannot connect to launched instance

The User Name must match the default login account for the image. Consult your cloud provider's documentation or the image publisher's instructions for the correct username. You can update the image in RosettaHub and relaunch.