Developer Getting Started#

Many of our clients integrate MetalSoft in their own stack in various ways. This resource is designed to help you get started with that.

Integrating with a customer portal#

There are two major types of integrations with external customer portals:

  1. Direct: End-client uses MetalSoft’s user portal to deploy infrastructure

  2. Indirect: End-client uses customer portal to deploy infrastructure

Direct integration with an upstream customer portal#

In this setup the MetalSoft end user portal (the drag and drop interface) is exposed to the user.

This setup is relatively easy to deploy and provides a good user experience to end-users for bare metal as a service offerings. It is however not suitable if other high level services such as VM-as-a-Service is offered.

There are multiple supported mechanisms for authenticating users in MetalSoft portal. More than one can be active at any give time:

  1. Using SAML (recommended)

  2. Using LDAP

  3. Using built-in authentication

The choice will depend on the capabilities of the portal. For more information visit Authentication Overview.

LDAP-compatible ID service#

If the existing user portal uses a LDAP-based login (FreeIPA, Active Directory) then MetalSoft should be configured to use LDAP protocol from the Global Configuration>Authentication tab.

For an example configuration consult: Configuring LDAP for Microsoft Active Directory

Built-in authentication#

MetalSoft’s built-in user management system is relatively robust. A portal could either:

  1. Create the users and set passwords using the API

  2. Let users signup on MetalSoft’s signup page.

Managing users via the API#

The portal could create users and delete users in MetalSoft via the API:

Note that the users have to have the billable flag set to allow them to deploy infrastructures. user_billable_set can be used to configure this flag.

Enabling user sign-up#

A partner portal could redirect users to the MetalSoft Signup page. To enable the Built-in sign-up process: Global Configuration > Authentication > Signup page enabled. Once enabled the signup button and the signup process will be enabled and available at https:/<env_hostname>/en/signup.

Note that users can also enable or disable authenticator on their account on their own.

Indirect integration with an upstream customer portal#

In many situations the upstream portal will use API calls to managed infrastructures:

Interacting with the API#

Typically, the portal will create infrastructures and configure servers, storage and network configurations. The following is a Postman collection with sample infrastructure related operations:

Authenticating to the API#

API users can use the following methods to authenticate HTTP requests:

  1. Authorization: Bearer <API_Key> header.

  2. Basic authentication, with the username and password of a user.

  3. ?verify=<user_id:signature> http query param where the signature value is calculated as a HEX digest of the MD5 sum of the body with the API key as the key. This is the most secure method as it prevents reply attacks but it is more complicated to operate. Consult the following examples and the API documentation

  4. Oauth2 flow with the API key.

Object Schema#

Here are some MetalSoft objects and their relationships.

  • Infrastructure - A grouping of resources such as Servers, Networks and storage, usually around an application

  • Instance - A mapping to a physical server that has properties such as a server, IP addresses, hostname, drives attached etc.

  • Instance Array - A group of instances that are managed as a single entity

  • Drive - A block device that can be attached to an instance. Can be iSCSI or FC. Can be cloned from an existing volume template or be unformatted.

  • Drive Array - A group of drives

  • Network - A MetalSoft specific abstract construct that informs the system how the network is to be configured. The default behavior is to map a network to a dedicated L2 network but it can be changed via Network Profiles.

  • Network Profile - A policy that defines how an instance is connected to a network. It defines one or more overlay networks (called VLANs but they can map to other implementations). It also defines which subnet pools to be used to allocate subnets and hence IPs within this network.

  • Subnet Pool - A subnet prefix out of which smaller prefixes are allocated to an L2 network

  • Subnet - A smaller prefix mapped to an L2 network from which IPs are allocated. The first IPs are usually the gateway Ips.

  • Subscriptions - Billing helper concept used to store information that can be used to charge a different price for “reserved” instances as opposed to on-demand.

Decrypting credentials#

All credentials in objects are encrypted and when retrieved in objects they are provided in their encrypted form to prevent accidental leaks in logs etc. Some SDKs such as the GO one provides facilities to decrypt this on the fly.

If you use the API directly you need to use the password_decrypt function to decrypt them. Provide the component of the retrieved string that is after the “:”.

Embedding the MetalSoft Remote Console into a customer portal#

The HTML console is a very useful tool for end-users to be able to interact with the server via the out-of-band network in an emergency or even as primary means of managing a server.

This console can be integrated into a 3rd party customer portal for a seamless experience.

Building an integration requires also a server-side component (NGINX) that acts as a proxy between MetalSoft and the client portal.

For more details on integrating with the remote console follow this guide:

github.com/metalsoft-io/UI-console-implementation-example

Customizing operating system templates behavior#

In many situations users want to change the way operating systems get installed, the settings they use, the SSH keys deployed, etc. MetalSoft provides a robust mechanism for customizing this behavior.

How OS deployment works#

MetalSoft Operating System deployment mechanism uses the unattended install process of each OS vendor and as such the configuration files differ from OS to OS but the process is more or less the same:

  1. A copy of the original ISO is made

  2. Several dynamic configuration files are compiled with data regarding the target server during which variables mentioned in the configuration file templates are replaced with the correct values such as the WAN IP.

  3. The compiled files are injected into the new ISO.

  4. The iso is downloaded to the agent

  5. The server or switch is instructed to boot from it

  6. The server uses the unattended install files to perform the installation automatically

  7. MetalSoft awaits until the server is shutdown to mark the server as deployed

Changing the unattended install file#

To change an unattended install process, for example to add a post-install command, go to Templates > select template > Assets

In this screenshot you notice the source ISO and also the files that will get injected.

Click on preseed.cfg then go to Content tab.

The syntax of this file depends on the operating system. In this screenshot it is a Debian preseed file.

Notice the use of variables such as {{wan_interface_0_ipv4_ip_0_address}}. These get replaced during the compilation phase. See The variables glossary for a list of variables that gets passed during compilation.

Note that there are two types of template files:

  • Simple - only variable replacement takes place

  • Advanced - a Nunjucks- based language can be used that includes support for if-else,for etc.

By editing this file you can add post-install steps and alter the way the default deployment happens. Don’t forget to click Save.

For more information consult: OS Templates section.

Calling outside systems#

To interact with outside systems as part of deployment processes MetalSoft provides the Workflows mechanism.

There are two types of workflows:

  1. Infrastructure -> can be applied to certain infrastructures but the user has to select them in the infrastructure editor (or added via APIs).

  2. Global -> automatically added to all deploys either at the start or the end of the flow.

Add a deployment finished callback#

The following example will add a call to an external system as a deployment finished callback.

Create an HTTP task for callback#

  1. go to Workflows section and click Add task button.

  2. From the dropdown select HTTP request

  3. Fill in the required information.

  4. From the list select the newly created task and from the Overview tab select Visibility: Public from the dropdown.

Create a global workflow and add the task#

  1. go to the Workflows tab. Click Add Workflow.

  2. Fill in the required information. Select Global as option for the Usage field.

  3. Check the Automatically add the task to post-deploys. checkbox.

  4. Select the newly created workflow and go to Workflow Editor tab.

  5. Click on New Task item in the flow, select the desired task.

The task will now be added to every deploy. If you need to disable the workflow but not delete it uncheck the “Automatically add the task to post-deploys””.

For more information visit Workflows section.