Let customers run Cloud Compute instances

Your storefront's instance panel runs on the portal API. Every route on this page is under /portal/vps/{uuid}/ and takes the customer's token as Authorization: Bearer $CUSTOMER_TOKEN. Only the customer who owns an instance can use it: instances cannot be shared, and any other customer gets 404 with Cloud Compute instance not found.

The routes work like the platform's /api/v1/client/vps/{uuid}/ routes that the Cloud Compute guides describe, and those guides explain each feature in more depth.

• Get a customer token as Sign customers in to your storefront describes.
• Find the instance's uuid. It is resource.uuid on the customer's service; see Show the customer's services.
• Reverse DNS goes through the address's own IP service: PATCH …/portal/ips/{service_id}/ptr, with host_address for an address inside the instance's IPv6 /64 (Set reverse DNS).

curl "https://api.coritan.com/api/v1/orgs/acme/portal/vps/$INSTANCE_UUID" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN"

The answer is the instance with its status, its plan's size, and the image it runs as template_name, os_family and os_version. username is the account to sign in with, and migration describes a move to another host while one is under way.

curl -X POST "https://api.coritan.com/api/v1/orgs/acme/portal/vps/$INSTANCE_UUID/power" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "shutdown"}'

action is start, reboot, shutdown (a clean shutdown) or stop (power off at once), as Start, stop and restart an instance describes. The answer is {"status": "ok", "action": "shutdown"}.

GET /console starts a console session on the instance's host. It answers vnc_ws, vnc_session, vnc_password, expires_in and display, as Use an instance's console shows, and the customer's token as token. Within expires_in seconds, connect a VNC client that speaks WebSocket, such as noVNC, and answer its password prompt with vnc_password:

wss://api.coritan.com/ws/vps/vnc/<instance uuid>?token=<customer token>&session=<vnc_session>

Ask for a new session for every connection. The socket closes with the codes that guide lists when it cannot connect.

• GET /credentials returns the username, whether we hold a password (password_stored) and updated_at, without the password.
• POST /reset-password sets a new random password on a running instance and returns it once, as {"password": "…"}. Show it to the customer straight away, because it cannot be read again.
• PATCH /hostname with hostname (up to 63 characters) sets the hostname. reboot set to true restarts the instance so the name takes effect at once.

curl -X PATCH "https://api.coritan.com/api/v1/orgs/acme/portal/vps/$INSTANCE_UUID/hostname" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "web-2", "reboot": true}'

Rename and tag an instance gives the hostname rules. A name that breaks them answers 422.

• GET /ssh-keys returns the public keys on the instance as ssh_keys (one per line) and their count.
• PUT /ssh-keys with ssh_keys replaces them all. Send an empty string to remove every key. The operating system applies the keys as it starts, so they reach it the next time the customer restarts the instance from your panel (POST /power with reboot).

Start an edit from what GET returned, because PUT does not merge.

POST /cloud-init/regenerate writes the instance's settings to it again. Use it when the instance did not pick up a change, such as a primary address the customer attached after it was built.

It writes the user account, the password we hold, the hostname, the DNS resolvers, the primary address and the IPv6 address. It leaves the SSH keys as the customer last saved them. The operating system applies the settings as it starts, so restart the instance afterwards with POST /power and reboot.

POST /rebuild erases the instance's disk and installs an operating system on it from scratch. The instance keeps its plan, hostname, addresses, SSH keys and backups. It loses every file on the disk and its snapshots, and gets a new random password. Rebuild an instance describes this in full. Because it erases the disk, the request must carry the instance's hostname as the customer typed it.

curl -X POST "https://api.coritan.com/api/v1/orgs/acme/portal/vps/$INSTANCE_UUID/rebuild" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template_id": 8, "confirm_hostname": "web-2"}'

• template_id is a template from GET /api/v1/orgs/{org_slug}/storefront/vps-templates.
• confirm_hostname must be the instance's hostname. Letter case and outer spaces do not matter.
• The answer is {"status": "rebuild_queued"}. The rebuild runs as a job, one per instance at a time. Poll GET /status to see it finish. The customer then signs in with an SSH key, or sets a password with POST /reset-password.

Ask the customer to type the hostname in your panel. Do not fill it in for them: the field is what stops a rebuild on a stray click.

• GET /activity lists what was done to the instance, newest first, as {"items": [{"id", "description", "by", "at"}]}. by is you for the customer's own actions, staff for your staff or ours, and system for the rest. limit takes 1 to 100 and defaults to 20.
• GET /guest returns what the running system reports about itself: agent_online, os_info and network_interfaces. agent_online is false while the instance is off or still booting.

A snapshot saves the instance's disk on its host so the customer can roll back to it. Take and roll back instance snapshots explains how many an instance keeps.

A backup is a full copy of the instance's disk, saved as an archive apart from the disk. Back up and restore an instance explains how many an instance keeps.

• GET /backups lists them.
• POST /backups starts one and answers {"backup_id": 812, "status": "creating"}.
• POST /backups/{backup_id}/restore answers {"status": "restore_queued"}, and DELETE /backups/{backup_id} answers {"status": "delete_queued"}. Read GET /backups to follow them.

Rescue mode restarts the instance from a rescue image so the customer can repair its disk, as Repair an instance in rescue mode describes.

1. List the images with GET /rescue/media. Each has a volid.
2. Enter rescue mode with POST /rescue/enter, and the image's volid as iso_volid. With no iso_volid, the first image in the list is used.
3. When the repair is done, POST /rescue/exit restarts the instance from its disk.

Customers see each instance they bought from you, with its state, traffic, graphs and activity, and can power it, reach its console, reset its password, change its SSH keys, reapply its settings, rebuild it, and take snapshots and backups without contacting your staff.

Cloud Compute instance not found

The instance is not this customer's, or its service has ended. Check the uuid against their services.

Instance is migrating

We are moving the instance to another host. Power actions and new backups are refused until the move ends.

Cannot perform power actions on a suspended instance

The instance is suspended. The service's status says so too; see Service statuses.

Invalid action. Must be: start, stop, shutdown, reboot

Send one of those words as action.

Type the server's hostname to confirm. A rebuild deletes every file on it.

confirm_hostname is missing or is not the instance's hostname. Read the hostname from GET /portal/vps/{uuid} and ask the customer to type it.

Cannot rebuild a suspended instance

The instance is suspended. It can be rebuilt once its service is active again.

Instance must be running to reset password

Start the instance, wait for it to boot, then reset the password.

Monthly traffic quota exceeded; backups are blocked until the next period

The instance has used its traffic for this period. Backups work again when the next period starts.

iso_volid required

The host has no rescue image to fall back on. Pick a volid from GET /rescue/media.

• Build the customer account area
• Let customers run their servers
• Cloud Compute