Get started with the Exoscale API client

DevOps engineers like to automate things. Once you’ll start programming your infrastructure with Exoscale services, you will quickly need to create scripts to test, monitor and automate actions on your virtual machines. Knowing this, the Exoscale team created a tool called CS, which allows to interact directly with their Cloudstack API through the command line or a script.

As the Cloudstack API allows for numerous possibilities, this document narrows it to a selection of commands available on Exoscale API. This list is non exhaustive but should help you to get started in most cases.

If you want to go further, the exhaustive list of the API calls you can use with your Exoscale account is documented here.

Requirements

You will need to install on your machine the following tools:

• cs to interact with the API
• jq to format the CS JSON output in a more readable way.

As per CS documentation, export the following values in your shell:

CLOUDSTACK_ENDPOINT="https://api.exoscale.ch/compute"
CLOUDSTACK_KEY="your Exoscale API key"
CLOUDSTACK_SECRET="your Exoscale secret key"
EXOSCALE_ACCOUNT_EMAIL="your@email.net"

Is it also possible to put those value in a .cloudstack.ini in your current folder. Refer to the documentation for more information.

Interact with your virtual machines

List all your Instances:

$ cs listVirtualMachines | jq

List only the running ones:

$ cs listVirtualMachines state=Running | jq

Or the stopped ones:

$ cs listVirtualMachines state=Stopped | jq

Note that the output of listVirtualMachines gives you access to a lot of useful information about your Instance:

{
  "account": "me@email.net",
  "affinitygroup": [],
  "cpunumber": 1,
  "cpuspeed": 2198,
  "cpuused": "0.54%",
  "created": "2016-02-10T09:17:54+0100",
  "diskioread": 45034,
  "diskiowrite": 42300,
  "diskkbsread": 1145504,
  "diskkbswrite": 2151632,
  "displayname": "swarm-queen-primary",
  (...),
  "id": "8ec6f4b1-0594-4a66-ab47-3f8a920fec54",
  "templatename": "Linux Ubuntu 15.10 64-bit",
  "zoneid": "1128bd56-b4d9-4ac6-a7b9-c715b187ce11",
  "zonename": "ch-dk-2"
}

Of course you can filter further those information using the powerful jq.

Start a vm:

$ cs startVirtualMachine id="your_vm_id"

Stop a vm:

$ cs stopVirtualMachine id="your_vm_id"

List available templates

This list the different OS and disk size templates available for your virtual machines:

$ cs listTemplates templatefilter=featured

List only the template names:

$ cs listTemplates templatefilter=featured | jq '.template[].displaytext'

Add the template id in the output:

$ cs listTemplates templatefilter=featured | jq '{name:.template[].displaytext, id:.template[].id}'

Search for a template id using its displaytext:

$ cs listTemplates templatefilter=featured | jq '.template[] | select(.displaytext=="Linux Ubuntu 15.04 64-bit 10G Disk (2015-04-22-c2595b)")'

Search for all templates based on CoreOS:

$ cs listTemplates templatefilter=featured | jq '.template[] | select(.displaytext | contains("CoreOS"))'

List available service offering

This list the different cpu and memory templates available for your Instances:

$ cs listServiceOfferings | jq '.serviceoffering[]'

Manage firewalling

You should always isolate your virtual machines in different security group according to their usage. To do so, you will need to create security groups in which rules are added to allow network connections on specific ports and protocol.

First, Create a security group:

$ cs createSecurityGroup name="my-security-group-1"

Then, add a rule from one security group to another for a specific port / protocol:

$ cs authorizeSecurityGroupIngress protocol=TCP startPort=80 endPort=80 securityGroupName=consul 'usersecuritygrouplist[0].account'=$EXOSCALE_ACCOUNT_EMAIL 'usersecuritygrouplist[0].group'=my-security-group-1

Or add a rule from one CIDR to a security group for a specific port / protocol:

$ cs authorizeSecurityGroupIngress protocol=TCP startPort=80 endPort=80 securityGroupName=my-security-group-1 cidrList=<your IP address/32>

Virtual machine creation

Once your firewall policies are defined, you can create virtual machines with the appropriate security group, OS flavor, disk size (specified by templateid), CPU and memory amount(specified by serviceofferingid):

$ cs deployVirtualMachine templateid="cdefccdb-996d-41c4-9ffc-7e493ba24957" zoneid="1128bd56-b4d9-4ac6-a7b9-c715b187ce11" serviceofferingid="21624abb-764e-4def-81d7-9fc54b5957fb" name="my new vm" securitygroupnames="my-security-group-1, my-security-group-2"`

Conclusion

Those commands should help you get started and optimize your virtual machine monitoring and creation process using shell scripts or python scripts (as CS is also available as a python module).

Now it’s time to explore the possibilities of the API !