Bare metal services

A bare metal service is one physical server assigned to your organization. The service object describes the machine (hardware), where it stands (region: datacenter, city, facility and rack), its network ports (interfaces), its addresses (primaryIpv4, primaryIpv6), the operating system last installed (operatingSystem) and the monthly traffic allowance (bandwidth.monthlyAllowanceGb). Get bare metal service returns all of it; List bare metal services returns the organization's services a page at a time.

States

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

The schema also lists PENDING_SETUP, which the platform does not set.

locked sits beside the state and does not change it. Lock and unlock set and clear it. A locked server refuses deployments, hardware tests, cancelling either of them, power commands, BMC resets, logical interface changes and virtual network attachments, each with 422 and SERVICE_LOCKED. Renaming, iPXE and boot mode, KVM, virtual media and IP address changes still work, and so does a delete request. Any member whose role holds the baremetal.lock permission can unlock it.

A suspended server refuses everything a locked one does and more: renaming, iPXE and boot mode changes, KVM 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.

Operations

Anything that rewrites the disks runs as an operation. There are three types, DEPLOYMENT, WIPE and TEST, and only one runs on a server at a time: starting a second answers 409 with OPERATION_IN_PROGRESS.

A deployment installs an operating system from the image list (List OS images). The deploy request takes the image's operatingSystemId, either sshKeyIds or a username and password, 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: applicationId, from List applications, takes the place of operatingSystemId, and a request that sends both, or neither, is refused with a DEPLOY_SELECTION_INVALID detail. applicationMetadata carries the settings described by that application's metadataSchema. Deploy your first server lists the other checks a deploy request has to pass.

A hardware test exercises the machine without installing anything. Run hardware test takes four switches, runCpu, runMemory, runDisk and runSmart, plus optional durations and load settings for each stage.

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. The schema lists PRECONFIGURATION and REBOOTING as well, which the platform never sets. 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, and Get operation returns one run in detail. A deployment or test that is still running can be stopped with Cancel deployment or Cancel hardware test; with none of that type running, the cancel 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 same group reads the power state, the power supplies' health, thermal sensors and power draw from the server's management controller, and resets the controller when it stops answering. Power and remote access walks through each call.

Remote access

A KVM session opens the server's console 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 console disables the tab. Power and remote access covers each call.

Boot mode and iPXE

bootMode is LOCAL_DISK or PXE. When a server boots from the network, the provisioning system looks up the booting port's MAC address and, if the service has a custom iPXE script stored, serves that script. Custom iPXE scripts shows the calls.

Network ports

interfaces lists the server's logical interfaces, each with its physical ports and the virtual networks attached to it. Get network capabilities lists the ports that are still free and the bonding groups the hardware supports, and Create logical interface builds a new logical interface from port ids. Attaching virtual networks is in Setting up virtual networks.

Traffic

bandwidth.monthlyAllowanceGb is the service's monthly allowance. Get bandwidth usage reports the running total, Get daily bandwidth one figure per day, and Get bandwidth time series a series between a start and an end at a step you choose.

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.

Removing a service

Delete bare metal service is a cancellation request. It answers 204 and opens a cancellation ticket with our staff, who remove the server afterwards. Until they do, the server keeps running, Get bare metal service still returns it with state ACTIVE, and nothing on it shows the pending cancellation. The service's subscription reads CANCELLATION_REQUESTED from the moment of the request; Billing says what that stops.