MBuffenoir/exoscale-cheatsheet.md

## exoscale-cheatsheet.md

      
    Raw
  

              exoscale-cheatsheet.md
            
          
    #How to use cs, 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 api key"
CLOUDSTACK_SECRET_KEY="your 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 informations.
##Interact with your virtual machines
List all your VMs:
$ 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 informations about your vm:
```
{
  "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-gva-2"
}
```

Of course you can filter further those informations 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 vms:
$ 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 vms:
$ 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 / proto:
$ 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 / proto:
$ 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 !