Getting started with FlexMetal

The FlexMetal API is in BETA active development.

Please get in touch with the i3D.net sales team to learn more about the product state and roadmap or if you wish to be part of the closed Beta program for FlexMetal.

Prerequisites

In order to create a new FlexMetal server you will need to follow 4 prerequisite steps:

An API Token
Geographical Location
Instance Type
Operating System

Note : API URL prefix is https://api.i3d.net

1. API Token

Generate an API token, the procedure is documented in API v3 Authentication
1. Add IP whitelisting for security (whitelist the IP addresses that will access the API)
Include your API key in every request using this HTTP header:
HTTP Header Name
HTTP Header Value
PRIVATE-TOKEN
YOUR_API_KEY
Throughout these documentation pages, we will refer to API endpoints like for instance:
GET /v3/flexMetal/location
This is not a complete endpoint. You must prefix this with the API URI and API version tag:
https://api.i3d.net/v3/
That results in the complete URL:
GET https://api.i3d.net/v3/flexMetal/location

Example HTTP request:

GET /v3/flexMetal/location
Host: api.i3d.net
PRIVATE-TOKEN: abc123xyz789

2. Location

Locations are named for the i3D.net Datacenter where FlexMetal instances are available. Below is a small extract of available locations:

Region

Country / State

Location Name

Europe

Netherlands

EU: Rotterdam

Europe

France

EU: Montreuil 1

USA

Virginia

US: Ashburn - VA

USA

Texas

US: Dallas - TX

USA

California

US: Los Angeles - CA

Asia

Japan

JP: Tokyo

Asia

Hong Kong

HK: Hong Kong

Latam

Brazil

BR: Sao Paulo

Middle East

United Arab Emirates

AE: Dubai

The full list of worldwide locations can be found using the location endpoint: GET /v3/flexMetal/location/

3. Instance Type

The Instance Type defines the hardware configuration of the bare metal server. Here is an extract of available instance types:

Instance

CPU Model

Generation

CPU Specifications

RAM

Storage

Uplinks

bm7.std.8

Intel Xeon E-2278G

Coffee Lake (14nm)

8 Cores / 16 Threads @ 3.40 GHz

32 GB DDR4

1x 960 GB SSD

2x1G

bm8.std.32

AMD EPYC 7502P

Rome Zen3 (7nm)

32 Cores / 64 Threads @ 2.50 GHz

128 GB DDR4

2x 960 GB SSD

2x25G

bm9.hmm.32

AMD EPYC 9354P

Genoa Zen4 (5nm)

32 Cores / 64 Threads @ 3.25 GHz

256 GB DDR5

1x 1.92 TB NVME

2x25G

The full list of Instance Types can be found on the Catalog page.

Instance Type availability can differ per location. Not all Instance Types are available in all locations.

Obtain a list of available Instance Types for a location using the API endpoint. GET /v3/flexMetal/location/

4. Operating System

FlexMetal supports many Operating Systems. Below is a small extract of available OS's:

slug

Ubuntu 22.04 LTS

ubuntu-2204-lts

Ubuntu 24.04 LTS

ubuntu-2404-lts

Talos Omni 1.8.4

talos-omni-184

Debian 12

debian-12

The full list of supported OS's can be found using the API endpoint: GET /v3/operatingsystem.

Creating a Server (POST)

POST /v3/flexMetal/servers

This endpoint allows you to create a new bare-metal server by specifying key details such as the server (host) name, location, instance type, operating system, and additional configurations like SSH keys, post-installation scripts, tags, and contract ID with overflow settings.

Server request body properties

Property

Value type

Required

Description

Example Value

name

string

Required

Human-readable (host) name for the server instance

server1.example.com

location

string

Required

The data center or region where the server will be deployed

EU: Rotterdam

instanceType

string

Required

The type of instance to be provisioned (defines hardware resources)

bm7.std.8

os

object

Required

Specifies the operating system and optional kernel parameters

See table below.

sshKey

array

Required

List of public SSH keys, can also be sshkey UUIDs

"ssh-rsa AAAAB3NzaC1yc..."

postInstallScript

string

Optional

A script that runs automatically after the server is installed

"#!/bin/bash echo Hello"

tags

array

Optional

List of Tags. Each tag must be in the format [A-Za-z0-9_:-]{1,64}

["my-tag1", "set:value"]

contractId

string

Optional

A contractId in format ^[A-Z0-9_\-.]{0,240}$

CTR-1

overflow

bool

Optional

Parameter that indicates if on-demand pool should be used

false

OS Parameter

The os parameter allows you to define the operating system for the server, an optional partitioning scheme and optional kernel parameters.

Field

Type

Description

Example Value

slug

string

The slug identifying the operating system to install (e.g., Linux distro)

ubuntu-2404-lts

kernelParams

array

(Optional) A list of kernel parameters to customize the OS installation, currently only used for Talos installations

See OS Customization

partitions

array

(Optional) A list of custom disk partitions

See OS Customization

SSH Keys

The sshKey parameter allows you to provide your public keys for your root logins.

For Windows OS, there is no SSH key. You will need to know your root password. The root password is accessible here. Note that we support Windows 2022. You must fetch the root password within the first 24 hours after installation.

You can provide actual public keys, or you can give the uuid of already stored SSH keys. The latter can be managed via the SSH CRUD endpoints:

Creating a SSH Key : POST /v3/sshKey
Listing SSH Keys : GET /v3/sshKey
Deleting SSH Keys : DELETE /v3/sshKey

Contract Id and Overflow

The contractId parameter allows you to specify the contract under which the server should be billed. If you want the server to be charged against a specific contract and use your Committed Quota (Guaranteed Resources), provide the appropriate contract ID here. The contract ID must match the format: ^[A-Z0-9_\-.]{0,240}$.

The overflow parameter determines whether the server should be created from the On-Demand pool when your Committed Quota for the specified contract ID is exhausted. If set to true, the server will be provisioned from the On-Demand pool. Please note that resource availability in the on-demand pool is not guaranteed and is allocated on a first-come, first-served basis. Default value is false.

Example request

POST /v3/flexMetal/servers

Request Body

{
  "name": "MyFlexServer",
  "location": "EU: Rotterdam",
  "instanceType": "bm7.std.8",
  "os": {
    "slug": "ubuntu-2404-lts"
  },
  "sshKey": [
    "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBIWrzxdeW3hhkejzSfFBFzPzcEBJBGtggOUJpLBCakbqmV/NztCaUoh631Xnk46MFn2snF89tSZZzlp9ySpqW7c= ecdsa-key-example"
  ],
  "postInstallScript": "#!/bin/bash\necho \"Hello flex world\" > /tmp/test.txt",
  "tags": [
    "My-tag1",
    "env:dev"
  ],
  "contractId": "CTR-1",
  "overflow": true
}

Response

If the request is successful, you will receive a response containing the details of the new server.

The Server UUID will be provided and can be used for getting server-specific details and releasing the server.

The server IP address will also be populated once the provisioning process has been finished.

Example Response:

[
    {
        "uuid": "019257a3-dxxxx-xxxx-xxxx-84c78b711f6e",
        "name": "MyFlexServer",
        "status": "created",
        "statusMessage": "OK",
        "location": {
            "id": 18,
            "name": "EU: Rotterdam"
        },
        "instanceType": {
            "id": 129,
            "name": "bm7.std.8"
        },
        "os": {
            "slug": "ubuntu-2404-lts"
        },
        "ipAddresses": [
            {
                "ipAddress": "x.x.x.x"
            }
        ],
        "tags": [
            "My-tag1",
            "env:dev"
        ],
        "createdAt": 1728047209,
        "deliveredAt": null,
        "releasedAt": null,
        "contractId": "CTR-1"
    }
]

Server Statuses

You can track the progress of server delivery via the status field which can have the following values:

created
discovering
discovered
allocating
allocated
configuring_network
network_configured
provisioning
provisioned
delivered
failed
releasing
released

There are three end states for all servers:

End state

Meaning

delivered

After creating a server, the requested OS will be installed. When the server status reaches delivered, it will be available for usage. You can then login with the root user and your SSH key.

failed

If a problem arises during the server creation, the status will be set to failed and the specific problem will be described in the statusMessage field of the response.

released

After deleting a server, its status will be set to released, indicating that you can no longer use it. The data on the server will then be securely erased.

Billing will start at the deliveredAt date and will end when the server is released with the date shown as releasedAt.
Billed hours will be rounded up to the full hour used.

Contract Id

If a contractId was provided in the request and is also present in the response body, it means the server was allocated from the Committed Quota pool. If the contractId is not present in the response body, the server was allocated from the On-Demand pool.

List FlexMetal servers (GET)

This endpoint retrieves information about all servers currently provisioned in your FlexMetal account.

The FlexMetal API allows users to retrieve detailed information about all existing servers or specific servers in the FlexMetal environment. This guide provides documentation for the following endpoints:

GET /v3/flexMetal/servers: Retrieve a list of all servers.
GET /v3/flexMetal/servers/{uuid}: Retrieve detailed information about a specific server by its unique identifier.

Server can be filtered by statuses by using, for example : /v3/flexMetal/servers?status=delivered

Filtering on Tags

Tags can be used to filter results for example: /v3/flexMetal/servers?tag=My-tag1

You can provide more than one tag to filter on, for example: /v3/flexMetal/servers?tag=My-tag1&tag=env:dev

Only servers with all the provided tags will be returned when searching by multiple tags.

Pagination

The server's entries returned by the API can be paginated using HTTP Header key RANGED-DATA and the value start=xx,results=yy

Where xx is starting index number beginning at 0 and yy is the number of entries to return, with a maximum to 50

Example HTTP request:

GET /v3/flexMetal/servers?status=delivered
Host: api.i3d.net
PRIVATE-TOKEN: abc123xyz789
RANGED-DATA: start=15,results=30

The default pagination returns a maximum of 15 server entries.

Servers that are in a failed or released state will only be visible in your GET responses for 24 hours.

Releasing FlexMetal servers (DELETE)

This operation cannot be undone, so back up any necessary data before deleting the server.

DELETE /v3/flexMetal/servers/{uuid}

This endpoint releases or deletes a FlexMetal server from your infrastructure. Once a server is released, it is no longer available, and all resources such as storage, network configurations, and data are removed.

FlexMetal server commands: power_on, power_off, and reboot

With FlexMetal, you can utilize the following commands for your servers:

POST /server/{uuid}/commands

"power_on"
"power_off"
"reboot"

Commands are executed immediately. Verify execution by checking if the server is rebooting or if the power status is on or off.

PreviousFlexMetal NextOS Customization

Last updated 16 days ago

Was this helpful?