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.
• The portal has no routes to rebuild an instance, replace its SSH keys, rename it or set its reverse DNS. Plan your panel without them.

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}'

Manage an instance's password, SSH keys and hostname gives the hostname rules.

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 and graphs, and can power it, reach its console, reset its password, 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.

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