Launch an instance

Launch an instance to get a running Linux machine you can log in to over SSH. You choose what it boots from, its size, its key pair and where it sits on the network.

Before you begin

Launch the instance

1. Choose an instance type whose available is true:

   origin compute list-instance-types

   For what the fields mean, see Instance types.

2. Choose an image. List the platform-provided images and your own:

   origin compute list-images --project-urn <project-urn>

   To launch the current build of an image family instead, see Using the API. The CLI only launches by image URN.

3. Launch the instance:

   origin compute launch-instance \
     --project-urn <project-urn> \
     --image-urn <image-urn> \
     --instance-type gp1.core.2 \
     --key-pair-urn <key-pair-urn>

   With no --subnet-urn, the instance goes into your project’s default subnet. That subnet is created on first use, in a VPC with an internet gateway, and the instance’s network interface gets a public address automatically. See Default VPC.

4. Add the options you need. Each is optional:

   Option	Use it to
   --subnet-urn <subnet-urn>	Place the instance in a subnet of your own VPC.
   --security-group-urn <security-group-urn>	Attach security groups to the network interface. Repeat it for several groups. Omitted, the VPC’s default security group applies. You can’t change the interface’s groups after launch, only the rules inside them. See Security groups.
   --boot-volume-size-gib <size>	Make the root disk bigger than the image. See Instance storage.
   --boot-volume-storage-class <class>	Pick the root disk’s storage class. See Storage classes.
   --login-user <name>	Override the image’s default user. See Guest environment.

   --volume-backend accepts only pvs, which is the default. Leave it out.

5. Note the instance’s urn and loginUser in the response. The following steps use them.

6. Wait for the instance to reach RUNNING. Run get-instance until status stops changing:

   origin compute get-instance --instance-urn <instance-urn>

   It passes through INITIALIZING and PENDING first. If it ends up FAILED, read its statusReason and see Status reasons. If the host never confirms the start, the instance can stay PENDING for about 30 minutes before it becomes FAILED. To poll every 10 seconds until the status stops changing, with jq:

   while :; do
     status="$(origin compute get-instance --instance-urn <instance-urn> \
       | jq -r '[.. | .status? | strings] | first')"
     echo "$status"
     case "$status" in RUNNING | STOPPED | FAILED | TERMINATED) break ;; esac
     sleep 10
   done

7. Find the instance’s public address. List the project’s floating IPs and their private addresses:

   origin network list-floating-ips --project-urn <project-urn>

   To match a floating IP to the instance, list the network interfaces with origin network list-network-interfaces --project-urn <project-urn>. The interface whose attachedToUrn is your instance’s URN carries its private addresses. See Network interfaces.

   To print the instance’s public address in one go, with jq:

   nic="$(origin compute get-instance --instance-urn <instance-urn> \
     | jq -r '[.. | .networkInterfaceAttachments? // empty | .[].networkInterfaceUrn] | first')"
   origin network list-floating-ips --project-urn <project-urn> \
     | jq -r --arg nic "$nic" '.. | objects | select(.networkInterfaceUrn? == $nic) | .address'

8. Verify that you can log in, as the instance’s loginUser, with the private key of the key pair:

   ssh -i <private-key-file> <login-user>@<public-address>

   The VPC’s default security group allows SSH from anywhere. If you attached other security groups, one of them must allow inbound TCP port 22 from your address.

Using the API

The launchInstance mutation takes the same inputs. It also accepts imageFamily in place of imageUrn, which launches the image currently designated for that family. Set exactly one of the two. See Image families.

mutation {
  compute {
    launchInstance(input: {
      projectUrn: "<project-urn>"
      imageFamily: "<family-slug>"
      instanceType: "gp1.core.2"
      keyPairUrn: "<key-pair-urn>"
      bootVolume: { sizeInGib: 40 }
    }) {
      urn
      status
      loginUser
    }
  }
}

If the launch is refused

A refused launch creates nothing and costs nothing.

• INSUFFICIENT_CAPACITYNo host has room for this type right now. Retry in a few minutes; a larger type may have room. gp1.core.2 is the smallest type, so there is no smaller one to try. The message names the type and what was short. See INSUFFICIENT_CAPACITY.
• PRODUCT_UNAVAILABLE: the instance type or storage class isn’t offered. Pick one whose available is true. See PRODUCT_UNAVAILABLE.
• Quota: the launch would take the organization or project past an instance, vCPU or storage limit. The error names the quota. See Limits.
• Root disk too small: --boot-volume-size-gib is smaller than the image. The error names the smallest size that works.

For other problems, see Troubleshoot Compute.

Next steps

• Attach a volume
• Associate a floating IP, for an instance in a subnet that doesn’t assign public addresses automatically
• Stop and start an instance

Related

• launch-instance reference
• Instance lifecycle