BMC Server Management via API

Introduction

The Bare Metal Cloud APIs provide additional flexibility when working with phoenixNAP BMC products. With the APIs herein, you can organize resources by using tags, monitor system logs and API activities for your BMC account, and control private networks for your BMC instances.

In this article, you will get familiar with the following Bare Metal Cloud APIs:

• Server Tag Manager API
• Audit Log API
• Multi-Private Backend Network API

Server Tag Manager API

The Tag Manager API lets users create tags to organize and group servers. You can also filter the resources by tag names or a tag name and value. Hence, tags are key-value pairs that simplify the Bare Metal Cloud server management.

The Tag Manager API uses this HTTP request:

https://api.phoenixnap.com/tag-manager/v1/tags

and the following methods:

• POST – Create a new tag in the tag inventory.
• GET – Retrieve information for your tags and the tag inventory.
• PATCH – Modify/update a tag from the inventory.
• DELETE – Delete a tag from the inventory.

Note: Refer to the Tags API page for in-depth details.

Create Tag

Add a tag using the POST request requires the tag body to contain a tag name and the value for the isBillingTag property (true or false). This property instructs whether the invoice should use the tag to display the servers with recurring costs. The tag description property is optional.

Note: A tag name is case sensitive, must be unique, and 100 characters maximum. It is not possible to create two tags with the same name even if you specify different values for other properties.

For instance, to create ExampleTag, use the /tags endpoint and:

Once you create a tag, it gets a unique ID. You can use the tag name or ID for API requests.

View Tags and Tag Inventory

Use the GET request and the /tags endpoint to view all tags that belong to your BMC account. In our case, we have the tag Environment and the ExampleTag we created above.

The output lists all tags in the inventory with all properties and their current values.

To view a specific tag and its properties, use the /tags/{tagId} endpoint.

Modify a Tag

Use the PATCH method with the /tags/{tagId} endpoint to update a tag’s values. For example, change the isBillingTag from false to true.

If you patch the isBillingTag property, the tag changes on all assigned resources.

Delete a Tag

To completely remove a tag from your BMC account, use the DELETE method with the /tags/{tagId} endpoint.

Note: A tag is automatically removed from any assigned resources upon deletion.

Assign Tag to Server Resources

Use the PUT method and the servers/{serverId}/tags to assign a tag to a BMC server. The tag body must contain a tag name, while the value property can be left empty. However, if this property is populated, you can have multiple servers using the same tag with a different value.

For instance, set the environment tag with the value prod to one BMC server and use the same tag name for another server but with the value QA. Therefore, you can assign one tag to multiple servers but use a different value.

Note: The maximum number of tags per BMC server is 20.

When you request tag details, the body of the tag shows the fields gathered from the server it is assigned to. When the same tag is assigned to multiple BMC servers with different values, then the tag shows that information as well.

If you remove a tag assignment from a resource, the system updates the tag details automatically.

Having tags assigned to servers facilitates resource usage organization when different teams work on multiple projects. Additionally, businesses get a clear breakdown in the invoices for the server usage for their BMC account.

Filter Servers by Using Tags

You can filter BMC servers by using a tag name and tag value if a server has any tags assigned.

Use the GET method in this format to filter server resources:

servers/?tag=tagName.tagValue

Use multiple query parameters to refine the filtering:

servers/?tag=tagName.tagValue&tagName2.tagValue2

Specifying the tag value is optional, so use the tag name to filter the server resources only.

servers/?tag=tagName

For example:

servers/?tag=Environment

Note: Tag names are case-sensitive. If you make a mistake in a tag name you will not get any results, even if the tag value is correct. Therefore, you must specify a tag name and a tag value verbatim.

The query result shows all servers that match the filtering parameters.

Audit Log API

The BMC Audit Log API allows you to monitor API calls and activities on your Bare Metal Cloud account. The system records user actions by creating event logs for each API action automatically.

With this API, you can read the audit log entries and maintain the required security level. The Audit Log API provides business owners the transparency they need to maintain operational best practices.

For example, the system logs when there is an error message or action such as powering off a server, restarting, billing changes, deleting an SSH key, and similar.

Users can see audit logs for their own accounts only.

Retrieve Event Logs

To retrieve API event logs, use the GET method and this request:

https://api.phoenixnap.com/audit/v1/events

Note: Date and time are represented in the UTC time zone.

Use different query parameters to customize the filter result:

• Limit. Instructs the API to limit the response output to a specified number of events. The endpoint is /events?limit=value.
• Verb. Shows the results for the specified verb events. For example, to see the POST events, use the /events?verb=POST endpoint.
• Username. Displays the API event log for the specified username. The endpoint is /events?username=value.
• Order. Set the sorting order of the event audit log according to the time stamp in ascending (ASC) or descending (DESC) order. The default is DESC if no value is specified. The endpoint is /events?order=ASC_or_DESC.
• Date. Filters by the specified date range using from and to. The endpoint is /events?from=data&to=date.

Multi-Private Backend Network API

The multi-private backend feature provides added control and flexibility when using private networks with BMC servers. With the multi-private backend networking APIs, users can now customize private IP space when provisioning a server.

The HTTP Request URL is:

https://api.phoenixnap.com/networks/v1/private-networks

The Network API has the following properties:

Property	Input​	Description​
ID​	system​	Unique network identifier​ assigned by the system.
Name​	required	The network name must be unique for all networks for an account. (case insensitive)​
Description​	optional	Network description​, if not defined it will be nulled.
Type​	​system	A field returned for backend networks, in this case PRIVATE.
Location​	required	Network location​.
Location Default​	required ​	Boolean representing the default network for an account in a location​.
CIDR​	required ​	Network subnet from which users can assign IP addresses.
VLAN ID​	​system	Client VLAN ID used for issue reporting in case of network problems.​
Servers​	​system	List of servers assigned to the network in question​.

This API allows users to:

• Provision a server and assign it to a specific private network. If no network details are specified, then the system adds a server to the default network for the location and automatically assigns the first available IP. For example, provision a server within multiple private networks and specify network settings for each. One server can be assigned up to 10 private IP addresses. It is not possible to combine different networks, and only one gateway is supported.

• Add an existing server to another private network. This can be any network for that location. You can also assign multiple networks in the same manner as when you provision a server.
• Remove an existing server from a private network. You can remove a server from any private network, even when that is the only network the server is connected to. When you deprovision a server, the server is removed from any associated private networks, and the IP allocation is freed up.

Below is the table of the default private networks for all locations:

Location​	CIDR​
Phoenix​ (PHX)	10.0.0.0/24​
Ashburn (ASH)	10.1.0.0/24​
Singapore​ (SGP)	10.2.0.0/24​
Netherlands (NLD)	10.3.0.0/24​
Chicago (CHI)	10.4.0.0/24​
Seattle​ (SEA)	10.5.0.0/24​

Create Private Network API

Use the POST method and the /private-networks endpoint to create a private network.

Note: The first created network is the default network. The maximum number of private networks per account is 15.

The request contains the following fields:

• name
• location
• locationDefault
• cidr
  • Supported ranges are:
    • 10.0.0.0 – 10.255.255.255
    • 172.16.0.0 – 172.31.255.255
    • 192.168.0.0. – 192.168.255.255
• description (optional)

For example:

Retrieve Private Network Details

Use the GET method and the /private-networks endpoint to retrieve the list of all private networks for all locations owned by the account.

To get the details of a specific private network, use the /private-networks/{network_id}​ endpoint.

The result also shows the servers assigned to a private network with server IDs and IPs.

Optionally, filter the results by the location with this endpoint:

/private-networks?location=PHX

Replace PHX with the desired location.

Modify Private Network

Use the PUT method and the /private-networks/{network_id}​ endpoint to update a private network’s details.

The fields you can modify are:

• name – either leave the same name or specify a new unique name.
• locationDefault – for example, if a network is not default, set the value to true to make that network default. Only one network can be default per location.
• description – optional field.

Delete Private Network

To remove a known private network, use the DELETE method and the /private-networks/{network_id}​ endpoint.

Note: If a network is assigned to a BMC server, you cannot delete it. Additionally, it is not possible to delete a default network as this would leave that location without a default network. If the default network is the only network, then you can remove it from the location.

Once you delete a network, you cannot retrieve any previous information on it.

Conclusion

The guide provided an overview of the Tag Manager API, Audit Log API, and the Multi-Private Backend Network API.

To get more details on the response types, errors, and other details for our APIs, visit the Developers Portal.