Bare metal services

A bare metal service is one physical server assigned to your organization. The service object describes the machine (hardware: CPU, memoryGb, drives and capabilities), where it stands (region: the datacenter's code, city, facility and rack), its network ports (interfaces), its addresses (primaryIpv4, primaryIpv6), the operating system last installed (operatingSystem), its bootMode and the monthly traffic allowance (bandwidth.includedEgressGb). Get bare metal service returns all of it, together with the running operation and the last finished one as lastOperation. List bare metal services returns the organization's services a page at a time, without interfaces, state or the operations; ?datacenter= narrows it to one datacenter, named by a code such as ams1 or by its id. Update bare metal service changes name, which the next deployment also turns into the server's hostname.

States

state answers one question: can the server take a new operation right now?

When more than one applies, DELETING wins, then SUSPENDED, then OPERATION_IN_PROGRESS.

isLocked sits beside the state and does not change it. Lock and unlock set and clear it; both need the organization.baremetal.lock permission and answer 204. A locked server refuses deployments, hardware tests, cancelling either of them, power commands, BMC resets, segment changes, attaching and detaching virtual networks, and its own deletion, each with 422 and SERVICE_LOCKED. Renaming, iPXE and boot mode, console sessions and virtual media still work.

isSuspended turns true when the service is suspended. A suspended server refuses the deployments, tests, cancels, power commands, BMC resets, segment changes and network attachments a locked one refuses, and also renaming, iPXE and boot mode changes, console sessions and virtual media, the hardware readings, and the lists of images and applications to deploy. Each answers 422 SERVICE_SUSPENDED until the service is reinstated. A server that reads DELETING refuses the same set with 422 SERVICE_DELETING.

Operations

Installing, wiping and testing a server run as operations of type DEPLOYMENT, WIPE or TEST. Only one runs on a server at a time: starting a second answers 409 with OPERATION_IN_PROGRESS. Only our staff start wipes, and the operation history leaves them out.

A deployment installs an operating system from List OS images. The deploy request names it as image, by the image's id or slug, and takes sshKeyIds or a password (with an optional username), a raidVariant (NONE, RAID0, RAID1, RAID5, RAID6 or RAID10; pick one the image names in its raidVariants) and an optional cloudInit document. RAID levels for dedicated servers compares RAID 0, 1, 5 and 10 on usable capacity and failure tolerance. A deployment can install an application in place of a plain image: application, an id or slug from List applications, takes the place of image, and a request that sends both, or neither, is refused with a DEPLOY_SELECTION_INVALID detail. applicationMetadata is a JSON object with the settings that application's metadataSchema describes. Deploy your first server lists the other checks a deploy request has to pass.

A hardware test exercises the machine without installing anything, and it runs non-destructively, leaving the data on the disks in place. Run hardware test takes four required switches, isCpuIncluded, isMemoryIncluded, isDiskIncluded and isSmartIncluded. Optional settings tune the stages: cpuDurationSeconds, memoryDurationSeconds and diskDurationSeconds (10 to 1800 each), cpuWorkers (1 to 1024), memoryPercent (1 to 95), diskBlockSize (512 bytes to 16m in steps of 512, written in bytes or with a k or m suffix) and diskIoDepth (1 to 256). A setting left out keeps the test tool's own default, and one out of range answers 400 VALIDATION_ERROR. The finished test's result is details.report on Get operation: isPassed for the whole run and for each stage, with disk throughput in bytes per second.

A deployment reads CREATED, then WAITING_FOR_PXE_BOOT, then CHECKED_IN once the installer on the server has reported in, and ends as COMPLETED, FAILED or CANCELLED. A deployment that installs an application also passes through IN_PROGRESS after its operating system stage. Treat every state other than the three final ones as still running, and follow progress and lastProgressMessage for how far it has got. List operations is the server's history, newest first, and Get operation returns one run with every progress report it sent.

Cancel operation stops a running deployment or test, named by its id, and answers 204. An operation that has already finished, or that finishes while the cancel is being saved, answers 422 ENTITY_STATE_INVALID. An id that names none of this server's deployments or tests answers 404.

Power and hardware readings

Send power command accepts ON, FORCE_OFF, GRACEFUL_SHUTDOWN, FORCE_RESTART and GRACEFUL_RESTART. The graceful commands ask the operating system to shut down; the forced ones act on the power supply directly. The current power state is powerState on Get service status. The server's management controller also reports the power supplies' health, thermal sensors and power draw, and Reset BMC restarts the controller when it stops answering. Power and remote access walks through each call.

Remote access

A console session opens the server's screen and keyboard in a browser, for an operating system that is not answering on the network or for a BIOS setting. Virtual media mounts an ISO from your ISO library as a drive on the server, to boot an installer the image list does not have. Not every management controller offers all of this, and hardware.capabilities lists what the server's does:

A call the server's controller cannot serve answers 422 OPERATION_NOT_SUPPORTED_PLATFORM, and the cloud console disables the tab.

Boot mode and iPXE

bootMode is LOCAL_DISK or PXE. The mode decides which networks the server's ports carry, so Set boot mode is a network change: it answers 202 while the switches are reconfigured, and networkChange on Get service status follows the change until it has been applied. When a server in PXE mode boots from the network, the provisioning system looks up the booting port's MAC address and serves the iPXE script stored on that service. Custom iPXE scripts shows the calls.

Network ports

interfaces lists the server's segments. A segment is one network port, or two ports bonded with LACP (bondMode LACP), and it carries the virtual networks attached to it. Its name is the interface name a deployment writes on the host: the port's own name, or bond0, bond1 and so on for a bond. Its segmentId is the id the segment, attachment and address calls take, and each port under physicalInterfaces carries the same segmentId.

Get network capabilities lists every port with the segmentId it belongs to, and the bonding groups, one per switch pair, each with the interfaceIds of the ports cabled to that pair and their count as maxBondSize. Create segment takes interfaceIds: one port makes a plain segment and two make a bond. A bond's two ports come from one bonding group, sit on different switches of the pair and use the same port number on both; three or more ports, or two that break one of those rules, answer 422 with a BOND_INVALID detail. A port that already belongs to a segment answers 409 INTERFACE_IN_USE, so delete that segment first. Both calls queue a switch change and are refused while an operation or another network change is running. Attaching virtual networks to a segment is in Setting up virtual networks.

Traffic

bandwidth.includedEgressGb is the service's monthly allowance, and null means unlimited. The allowance counts outbound traffic only, in decimal gigabytes of 10^9 bytes. Traffic past it is not throttled. On an hourly subscription, each GB over the plan's allowance is billed.

Traffic is measured on the switch ports, from the moment the service was created. Get bandwidth usage reports the last 30 days, from periodStart to periodEnd: egressBytes and ingressBytes for the whole window and per day under daily, beside the allowance as includedEgressBytes. Get bandwidth time series returns rates in bits per second, for the server as a whole and per port, between a start and an end (the last 24 hours by default) at a stepSeconds of 60 or more. A step that would yield too many points for the window answers 422 with a BANDWIDTH_STEP_INVALID detail. In both, null means nothing was measured for that day or step, while 0 is a measured value.

Removing a service

Delete bare metal service needs the organization.billing.subscriptions.manage permission and answers 202 with no body. Billing for the server stops at once. The server then reads state DELETING while it is powered off and its networks are torn down, and once that has finished, Get bare metal service answers 404. Sending the delete again during DELETING changes nothing. When the server is the last one on its subscription (Get service subscription names it), the subscription's address blocks are released after the server is gone; Billing covers subscriptions.

A delete is refused when:

Once the server is gone, its disks are securely erased, and the machine is not offered to anyone else until that erase has succeeded. No route reverses a delete, so copy off any data you need before sending it.