Ecosystem

gridscale’s in-house tools and libraries are intended to optimize and simplify workflows. The code is open-sourced and hosted on Github. They are frequently updated to support all of the latest features along with bug fixes and security updates.

Terraform Provider

The provider allows you to interact with gridscale resources. In order to get started, go through our tutorial.

Examples

To make use of the examples which you can find here, you need to generate an API Key.

Simple Server

This is a simple example that shows how to use resources and data sources to create a basic running server.

Set GRIDSCALE_TOKEN and GRIDSCALE_UUID environment variables to the values you got from the Cloud Panel.

$ export GRIDSCALE_TOKEN=your-api-token
$ export GRIDSCALE_UUID=your-user-id

Open server.tf and paste your SSH public key where it says "INSERT KEY". Then do

$ terraform init

Note that this will download the gridscale provider plugin to .terraform/.

Let’s create the server. Do

$ terraform apply

Terraform will now plan the actions it is about to perform. You should see something like:

Plan: 5 to add, 0 to change, 0 to destroy.

Investigate the actions that Terraform is about to perform and type yes. After about 30 seconds, Terraform will print

Apply complete! Resources: 5 added, 0 changed, 0 destroyed.

Go ahead and inspect the Cloud Panel for the newly created objects. When your done, remove all resources again by doing

$ terraform destroy

After a few moments, everything is removed again.

Destroy complete! Resources: 5 destroyed.

Provisioning with Terraform and Ansible

This example provisions a web server using Ansible and Terraform. It creates a local Ansible inventory file containing the server’s IP address and name. In the playbook we can then reference the server by using this name. In this example it is demo-complete-provisioner (as shown in main.yml) which is the same as the resource name we use in the HCL file.

Note: You need Ansible installed and in PATH to run this example.

This example uses a null resource in order to provision the storage with Ansible. This is needed only if the storage is for some reason re-created and you want Ansible to re-provision the storage automatically again. This is achieved using a trigger. The null resource also depends on the server resource implicitly. This is what the echo ${gridscale_server.server.id} is for (so please don’t remove it). It also leverages the remote-exec provisioners operation timeout and retry functionality to wait for SSH to be available for Ansible to work.

If you don’t need the functionality of reprovisioning the storage when it is re-created, just define the provisioner inside the server resource and remove the null resource.

We are currently enhancing the gridscale Terraform provider in a way that makes the null resource obsolete and general usage of provisioners more straight forward.

As usual, set GRIDSCALE_TOKEN and GRIDSCALE_UUID environment variables to the values you got from the Cloud Panel.

$ export GRIDSCALE_TOKEN=your-api-token
$ export GRIDSCALE_UUID=your-user-id

Open server.tf and paste your SSH public key where it says "INSERT KEY". Please make also sure that you have the key loaded in your SSH agent, e.g., by adding it with

$ ssh-add ~/.ssh/your-key

You can check if the key is loaded with

$ ssh-add -L

Then do

$ terraform init

And then do a

$ terraform apply

Type yes when Terraform asks you to. In the end, you should see something like following output in your terminal:

…
null_resource.storage_provisioner: Creation complete after 19s [id=41077748293669291]

Apply complete! Resources: 6 added, 0 changed, 0 destroyed.

Outputs:

server_ip = 45.17.50.177

E voilà, you have a new server resource along with a running Apache web server. Try it:

$ curl -i http://45.17.50.177

Multi-Project Example

This example shows how you can leverage the gridscale Multi-Project feature using Terraform.

In case you don’t know already, you can easily create multiple projects beside the standard “default” project.

Select a project in the panel

Projects allow you to scope your objects and easily control resource usage. For example, with a project you can just throw away all resources within that project all at once to make sure you don’t pay for something you don’t use.

Once you have created a new project, you can create a new API token within that project. API tokens are limited to the scope of the project they are defined in. Different projects require different API tokens.

When you run Terraform, you just need to set the GRIDSCALE_TOKEN environment variable to the value of the token for the specific project. This will make sure that all operations Terraform executes are limited to the corresponding project.

This example shows two projects, “a” and “b” split into sub directories.

├── project-a
│   ├── .envrc
│   └── example.tf
├── project-b
│   ├── .envrc
│   └── example.tf
└── README.md

Each directory contains a simple text file that can be sourced (command to source .envrc file: source .envrc) BEFORE running terraform apply:

$ cd project-a
$ cat .envrc
export GRIDSCALE_TOKEN=project-a-api-token
export GRIDSCALE_URL=https://api.gridscale.io
export GRIDSCALE_UUID=your-user-id
$ source .envrc
$ terraform apply
$ cd project-b
$ cat .envrc
export GRIDSCALE_TOKEN=project-b-api-token
export GRIDSCALE_URL=https://api.gridscale.io
export GRIDSCALE_UUID=your-user-id
$ source .envrc
$ terraform apply

Tip: you can use tools such as direnv(1) to easily switch between environment variables.

Load SSH Public Key From File

This is a small example that shows how to load a SSH public key file from disk with file():

resource "gridscale_sshkey" "demo" {
  name   = "demo"
  sshkey = file("/home/john/.ssh/id_rsa.pub")
}

gsclient-go

The Go-based API client facilitates an application to interact with the gridscale Cloud Platform and allows you to create and manage resources.

gsclient-js

The JS-based API client facilitates an application to interact with the gridscale Cloud Platform and allows you to create and manage resources.

gscloud

The official command-line interface for the gridscale API. The tool allows you to manage your virtual infrastructure and is written in Go. You can either compile the gscloud binary yourself or download the latest release.

In order to get started with gscloud, you can take a look at this tutorial.

Examples

Create a server object with storage

$ gscloud server create \
    --name test-1 \
    --cores=1 \
    --mem=1 \
    --with-template="CentOS 8 (x86_64)" \
    --hostname test-1
Server created: xxxx-xxxx-xxxx-xxxx-xxxx
Storage created: xxxx-xxxx-xxxx-xxxx-xxxx
Password: xxxxxxxxxxxxxxxxxxxx:^

Pull an IP address and assign to a server

$ gscloud ip add -6
IP added: xxxx:xxx:x❌x:xxxx

$ gscloud ip assign --to=xxxx-xxxx-xxxx-xxxx-xxxx xxxx:xxx:x❌x:xxxx

List servers

$ gscloud server ls
ID                                    NAME    CORE  MEM  CHANGED                    POWER
xxxx-xxxx-xxxx-xxxx-xxxx  test-1  1     1    2021-02-19T20:07:59+01:00  off

List storages

$ gscloud storage ls
ID                                    NAME    CAPACITY  CHANGED                    STATUS
xxxx-xxxx-xxxx-xxxx-xxxx  test-1  10        2021-02-19T20:08:04+01:00  active

List IPs

% gscloud ip ls
IP                  ASSIGNED  FAILOVER  FAMILY  REVERSE DNS                                      ID
xxxx:xxx:x❌x:xxxx  assigned  no        v6      static-xxxx:xxx:x❌x:xxxx.gridserver.io      xxxx-xxxx-xxxx-xxxx-xxxx

Remove a server along with assigned IPs and storages

$ gscloud server rm -i xxxx-xxxx-xxxx-xxxx-xxxx
ID                        TYPE          NAME
xxxx-xxxx-xxxx-xxxx-xxxx  Server        test-1
xxxx-xxxx-xxxx-xxxx-xxxx  Storage       test-1
xxxx-xxxx-xxxx-xxxx-xxxx  IPv6 address  xxxx:xxx:x❌x:xxxx
This can destroy your data. Re-run with --force to remove above objects

And if you are really sure what you do:

$ % gscloud server rm -i -f 2090776c-f428-40b4-a97b-f61081516eb2
ID                        TYPE          NAME
xxxx-xxxx-xxxx-xxxx-xxxx  Server        test-1
xxxx-xxxx-xxxx-xxxx-xxxx  Storage       test-1
xxxx-xxxx-xxxx-xxxx-xxxx  IPv6 address  xxxx:xxx:x❌x:xxxx
Removed xxxx-xxxx-xxxx-xxxx-xxxx
Removed xxxx-xxxx-xxxx-xxxx-xxxx
Removed xxxx-xxxx-xxxx-xxxx-xxxx

Foreman

Foreman helps you kick start things with infrastructure lifecycle management, allowing you to automate repetitive tasks, quickly deploy applications, and proactively manage servers. The Github link for the same is located here.

Take a look at our tutorial in order to get started.

fog-gridscale

A library that can be used as a module for fog or as standalone gridscale provider.

Libcloud

Libcloud is Python library that allows you to interact and manage your resources withing gridscale and other cloud providersusing a unified API. The library enables developers to build products that work between any of the services that it supports. To learn a little bit more about libcloud and how you can use it with the gridscale platform, take a look at the official Libcloud documentation.