List of API Keys
API keys to access your project.
API
Serverspace Public API - a public API for interaction with the Serverspace services. Actions performed in the Serverspace control panel can also be performed using the public API.
Authorization
To work with the public API, create an API key for the project and pass it in the X-API-KEY header with every request. For example, when using the cURL utility, the header would look like this:
All API requests must be made through HTTPS, here is the URL of the endpoint of the public API:
Usage Examples
Let's get information about the project by sending a request using the cURL utility:
https://api.serverspace.io/api/v1/project
-H 'content-type: application/json'
-H 'x-api-key: lmGwbvllpIqIrKROOCLgE5Z941MKP5EYfbkgwtqJZGigfXUTpuYRpNQkCqShmm6r'
This will return information about the project:
"project": {
"balance": 400.07,
"created": "2019-04-08T10:35:53.7021047Z",
"currency": "EUR",
"id": 1,
"state": "Active"
}
}
Let's create a server with the following configuration: Amsterdam, name: "api-example", Debian 10.7 operating system, server configuration - 1 GB RAM, 1 CPU, 25 GB SSD boot drive, 50 Mbps:
https://api.serverspace.io/api/v1/servers
-H 'content-type: application/json'
-H 'x-api-key: lmGwbvllpIqIrKROOCLgE5Z941MKP5EYfbkgwtqJZGigfXUTpuYRpNQkCqShmm6r'
-d '{
"location_id": "am2",
"image_id": "Debian-10.7-X64",
"cpu": 1,
"ram_mb": 1024,
"volumes": [
{
"name": "boot",
"size_mb": 25600
}
],
"networks": [
{
"bandwidth_mbps": 50
}
],
"name": "api-example"
}'
The result returns a task ID, which can be used to track the server creation process:
"task_id" : "lt1507097"
}
CLI
s2ctl is a Serverspace in the command line. The CLI gives you the ability to control your infrastructure via terminal, just like via the control panel. The tool is available on our Github.
Installation
s2ctl is available for Linux and Windows as a separate binary file. Download the archive from Github and unzip it.
Installation on Linux
- Download the archive from the GitHub repository:
wget https://github.com/itglobalcom/s2ctl/releases/download/vX.X.X/s2ctl-vX.X.X-linux.tar.gz
X.X.X.X is the number of the latest version of the utility.
- Unzip the downloaded archive:
tar -xzf s2ctl-vX.X.X-linux.tar.gz
- Navigate to the created directory and run the s2ctl utility:
cd s2ctl-vX.X.X-linux
./s2ctl --help - (Optional) You can also add the directory which contains the s2ctl executable to the $PATH environment variable to access the utility from anywhere in the operating system. To see what is in the $PATH variable right now, type the command:
echo $PATH
To add a new directory to the list, use the command:
export PATH=$PATH:""The $PATH variable is set by the shell each time it starts, but you can make it include the path to the utility in every new shell you open. The exact method depends on which shell you're using.
For example, for bash you need to add the following line about the corresponding file:echo 'export PATH=$PATH:""' >> .bashrcUse the command to apply the changes:
source ~/.bashrc
Installation on Windows
- Download the file s2ctl-vX.X.X-windows.zip from Github and unzip it.
- Run the command line:
- Press Win+R or Start → Search → Enter run → OK
- Enter cmd command → OK
- By default, the command line displays the home directory of the current user. Navigate to the directory with the extracted file:
- Go to the desired directory and run the command:
- (Optional) You can also add the directory where you placed the s2ctl binary to the PATH environment variable to access the utility from anywhere in the operating system.
- Find System (Control Panel) in Search, and open it.
- Click the Advanced system settings.
- Click on Environment Variables. In the System Variables section find the PATH variable and select it. Click Edit. If the PATH variable does not exist, click New.
- In the Edit System Variable (or New System Variable) window, specify the value for the PATH environment variable. Click OK. Close all remaining windows by clicking OK.
Authorization
In order to work with the CLI you must create an API key for the project and also a context. Otherwise, you will need to pass the API key with each request.
Context Creation
Using contexts simplifies the use of the s2ctl utility. In this case you do not have to explicitly specify the API key for each command.
To create a context, use the following command:
For example:
Key Transfer
To pass the API key explicitly, it must be specified at the end of the command with the --apikey option:
For example:
Usage Examples
Get information about the project with the following command:
This will return information about the project:
balance: '400.24'
currency: EUR
state: Active
created: '2019-04-08T10:35:53.7021047Z'
Create server:
This will return the task ID, which can be used to track the server creation process:
Terraform
Terraform provider Serverspace allows you to manage cloud resources using the Infrastructure as Code approach. Management is done using special configuration files in which you describe the desired state of your infrastructure.
Installing Terraform
First, let’s install Terraform in your operating system. We recommend using the Terraform developer's manual.
Provider Configuration
- Create an API key for the project that will work with Terraform.
- Create and navigate to the directory which will be used to work with Terraform Provider.
- Create and open the provider.tf configuration file.
- Insert the provider information in the file, where is your API key, and save the changes:
required_providers {
serverspace = {
source = "itglobalcom/serverspace"
version = "0.2.0"
}
}
}
variable "s2_token" {
type = string
default = ""
}
provider "serverspace" {
key = var.s2_token
}
- Open a command prompt and navigate to the directory where you created the file. Perform an initialization to verify that it is correct:
You will see the following message if initialization is successful:
Initializing provider plugins...
- Finding itglobalcom/serverspace versions matching "0.2.0"...
- Installing itglobalcom/serverspace v0.2.0...
- Installed itglobalcom/serverspace v0.2.0 (self-signed, key ID 062XXXXXXXXXXXX)
Partner and community providers are signed by their developers.
If you'd like to know more about provider signing, you can read about it here: https://www.terraform.io/docs/cli/plugins/signing.html
Terraform has created a lock file .terraform.lock.hcl to record the provider selections it made above. Include this file in your version control repository so that Terraform can guarantee to make the same selections by default when you run "terraform init" in the future.
Terraform has been successfully initialized!
You may now begin working with Terraform. Try running "terraform plan" to see any changes that are required for your infrastructure. All Terraform commands should now work.
If you ever set or change modules or backend configuration for Terraform, rerun this command to reinitialize your working directory. If you forget, other commands will detect it and remind you to do so if necessary.
Your Infrastructure Description
With Serverspace Terraform Provider, you can create infrastructure with various configurations. You can find detailed documentation in the Terraform Registry.
Let's take a look at the example of creating a simple infrastructure with two servers connected via isolated network:
- Server in Amsterdam called "server-1" with Ubuntu 20.04 operating system. Server configuration - 2 GB RAM, 2 CPUs, 40 GB SSD boot drive, additional 20 GB SSD drive, 50 Mbit/s. SSH connection to the server. Redis data storage installed on the server.
- Server in Amsterdam called "server-2" with Ubuntu 20.04 operating system. Server configuration - 8 GB RAM, 4 CPUs, 40 GB SSD boot drive, 70 Mbps.
- Isolated network in Amsterdam addressing 192.168.0.0/24
Follow the steps below to set up this infrastructure:
- Create and open the file ssh_key.tf, which will contain the public part of the ssh key to create the server.
- Insert the information about the public part of the ssh key into the file ssh_key.tf and save the changes, replacing the contents of the public_key variable with your value:
name = "terraform-key"
public_key = "ssh-rsa AAAAB3Nza...JUDjlM= root@CentOS.local"
}
variable "pvt_key" {
type = string
default = ""
}
- Create and open the main.tf file that will contain the infrastructure description.
- Insert the description of your infrastructure into the file.
image = "Ubuntu-20.04-X64"
name = "server-1"
location = "am2"
cpu = 2
ram = 2048
boot_volume_size = 40*1024
volume {
name = "bar"
size = 20*1024
}
nic {
network = ""
network_type = "PublicShared"
bandwidth = 50
}
nic {
network = resource.serverspace_isolated_network.my_net.id
network_type = "Isolated"
bandwidth = 0
}
ssh_keys = [
resource.serverspace_ssh.terraform.id,
]
connection {
host = self.public_ip_addresses[0]
user = "root"
type = "ssh"
private_key = file(var.pvt_key)
timeout = "2m"
}
provisioner "remote-exec" {
inline = [
"export PATH=$PATH:/usr/bin",
"sudo apt-get update",
"sudo apt-get install -y redis-server",
"exit 0"
]
}
}
resource "serverspace_server" "server2" {
image = "Ubuntu-20.04-X64"
name = "server-2"
location = "am2"
cpu = 4
ram = 8192
boot_volume_size = 40*1024
nic {
network = ""
network_type = "PublicShared"
bandwidth = 70
}
nic {
network = resource.serverspace_isolated_network.my_net.id
network_type = "Isolated"
bandwidth = 0
}
}
resource "serverspace_isolated_network" "my_net" {
location = "am2"
name = "my_net"
description = "Example for Terraform"
network_prefix = "192.168.0.0"
mask = 24
}
- To create the infrastructure described above, run the command:
A dialog window will appear:
Resource actions are indicated with the following symbols:
+ create
Terraform will perform the following actions:
# serverspace_isolated_network.my_net will be created
+ resource "serverspace_isolated_network" "my_net" {
+ description = "Example for Terraform"
+ id = (known after apply)
+ location = "am2"
+ mask = 24
+ name = "my_net"
+ network_prefix = "192.168.0.0"
}
# serverspace_server.server1 will be created
+ resource "serverspace_server" "server1" {
+ boot_volume_id = (known after apply)
+ boot_volume_size = 40960
+ cpu = 2
+ id = (known after apply)
+ image = "Ubuntu-20.04-X64"
+ location = "am2"
+ name = "server-1"
+ public_ip_addresses = (known after apply)
+ ram = 2048
+ ssh_keys = (known after apply)
+ nic {
+ bandwidth = 0
+ id = (known after apply)
+ ip_address = (known after apply)
+ network = (known after apply)
+ network_type = "Isolated"
}
+ nic {
+ bandwidth = 50
+ id = (known after apply)
+ ip_address = (known after apply)
+ network_type = "PublicShared"
}
+ volume {
+ id = (known after apply)
+ name = "bar"
+ size = 20480
}
}
# serverspace_server.server2 will be created
+ resource "serverspace_server" "server2" {
+ boot_volume_id = (known after apply)
+ boot_volume_size = 40960
+ cpu = 4
+ id = (known after apply)
+ image = "Ubuntu-20.04-X64"
+ location = "am2"
+ name = "server-2"
+ public_ip_addresses = (known after apply)
+ ram = 8192
+ ssh_keys = (known after apply)
+ nic {
+ bandwidth = 0
+ id = (known after apply)
+ ip_address = (known after apply)
+ network = (known after apply)
+ network_type = "Isolated"
}
+ nic {
+ bandwidth = 70
+ id = (known after apply)
+ ip_address = (known after apply)
+ network_type = "PublicShared"
}
}
# serverspace_ssh.terraform will be created
+ resource "serverspace_ssh" "terraform" {
+ id = (known after apply)
+ name = "terraform-key"
+ public_key = "ssh-rsa AAAAB3Nza...JUDjlM= root@CentOS.local"
}
Plan: 4 to add, 0 to change, 0 to destroy.
Do you want to perform these actions?
Terraform will perform the actions described above.
Only 'yes' will be accepted to approve.
- Enter yes to create the infrastructure.
serverspace_ssh.terraform: Creating...
serverspace_isolated_network.my_net: Creating...
serverspace_ssh.terraform: Creation complete after 1s [id=3181]
serverspace_isolated_network.my_net: Creation complete after 8s [id=l2n403]
serverspace_server.server2: Creating...
serverspace_server.server1: Creating...
serverspace_server.server1: Still creating... [10s elapsed]
serverspace_server.server2: Still creating... [10s elapsed]
...
serverspace_server.server1 (remote-exec): (Reading database ...
serverspace_server.server1 (remote-exec): (Reading database ... 5%
serverspace_server.server1 (remote-exec): (Reading database ... 10%
...
serverspace_server.server1: Creation complete after 1m3s [id=l2s190038]
Apply complete! Resources: 4 added, 0 changed, 0 destroyed.
- To view the current infrastructure, run the command:
- This will display the current infrastructure configuration:
resource "serverspace_isolated_network" "my_net" {
description = "Example for Terraform"
id = "l2n403"
location = "am2"
mask = 24
name = "my_net"
network_prefix = "192.168.0.0"
}
# serverspace_server.server1:
resource "serverspace_server" "server1" {
boot_volume_id = 58909
boot_volume_size = 40960
cpu = 2
id = "l2s190038"
image = "Ubuntu-20.04-X64"
location = "am2"
name = "server-1"
public_ip_addresses = [
"45.138.24.19",
]
ram = 2048
ssh_keys = [
3181,
]
nic {
bandwidth = 0
id = 59576
ip_address = "192.168.0.1"
network = "l2n403"
network_type = "Isolated"
}
nic {
bandwidth = 50
id = 59575
ip_address = "45.138.24.19"
network_type = "PublicShared"
}
volume {
id = 58910
name = "bar"
size = 20480
}
}
# serverspace_server.server2:
resource "serverspace_server" "server2" {
boot_volume_id = 58911
boot_volume_size = 40960
cpu = 4
id = "l2s190039"
image = "Ubuntu-20.04-X64"
location = "am2"
name = "server-2"
public_ip_addresses = [
"31.44.3.68",
]
ram = 8192
ssh_keys = []
nic {
bandwidth = 0
id = 59578
ip_address = "192.168.0.2"
network = "l2n403"
network_type = "Isolated"
}
nic {
bandwidth = 70
id = 59577
ip_address = "31.44.3.68"
network_type = "PublicShared"
}
}
# serverspace_ssh.terraform:
resource "serverspace_ssh" "terraform" {
id = "3181"
name = "terraform-key"
public_key = "ssh-rsa AAAAB3Nza...JUDjlM= root@CentOS.local"
}
Congrats with your first infrastructure as a code implementation.