Cloud Stack API

Gerenciamento de recursos da
Internuvem através de API
Como utilizar a API do CloudStack e o aplicativo CloudMonkey no
gerenciamento de recursos e automatização de ações na Internuvem
Stênio Firmino – USP/STI/Internuvem – [email protected]
Agenda
CloudStack API
CloudMonkey
•
•
•
•
•
•
•
•
•
•
•
•
Requisitos básicos
Guia de referência da API
Chamadas API
Interpretando as respostas
Paginação de respostas
Comandos assíncronos
Funcionalidades
Instalação/Configuração
Uso
Formato dos resultados
Perfis
Tarefas assíncronas
CloudStack API
Informações básicas de como utilizar a API CloudStack em atividades básicas e
avançadas oferecidas pela Internuvem
Requisitos básicos
• Para utilizar a API CloudStack na Internuvem é necessário:
–
–
–
–
–
A URL utilizada para enviar as chamadas de API
Uma API key e uma secret que irão identificar a conta
Familiaridade com consultas HTTP GET/POST
Conhecimento de XML/JSON
Conhecimento de linguagens de programação capazes de gerar requisições HTTP.
Ex: PHP, Java, Python…
– http://docs.cloudstack.apache.org/
• Permissões de acesso
– Root Admin
– Domain Admin
– User
Recuperando a API key e Secret
2
3
1
4
Recuperando a API key e Secret
Clicar para gerar chaves
Clicar para trocar chaves
Guia de referência da API
•
•
•
•
Documentação online com todos comandos da API
Comandos marcados com (A) são assíncronos
Request Parameters e Response Tags
http://cloudstack.apache.org/api.html
ROOT
ADMIN
DOMAIN
ADMIN
USER
Chamada API
https://internuvem.usp.br/client/api?apiKey=ifNzuw
2bOYDcf1MEhmu38ufkUxIpYKc5ybRQANNF3eiOJ8CwlubHxsQtv7cptahHKArZ2NVOXdlBq8Q7CZcow&command=l
istUsers&listall=true&response=json&signature=tRNl
S%2FocWMnhRGk7jy3V49h4%2Bkw%3D
HTTP GET/POST
API request
Cliente
Internuvem
API response
1
2
Chamada API
1. https://internuvem.usp.br/client/api?
2. apiKey=ifNzuw2bOYDcf1MEhmu38ufkUxIpYKc5ybR
QANNF3eiOJ8CwlubHxsQtv7cptahHKArZ2NVOXdlBq8Q7CZcow
3. &command=listUsers
4. &listall=true
5. &response=json
6. &signature=tRNlS%2FocWMnhRGk7jy3V49h4%2Bkw
%3D
1. URL base / api path 2. API key 3. Comando 4. Parâmetro(s) do comando 5. Formato resposta 6. Assinatura
Como assinar uma chamada API
• Hash em SHA-1 (HMAC-SHA1)
– Formatado em Base64
– URL encoded
• Secret key
• Parâmetros da API
– URL encoded
– Caracteres minúsculos
– Ordenados alfabeticamente
• Incorporar o hash como parâmetro (signature) da URL
Como assinar uma chamada API
• URL Base
– https://internuvem.usp.br/client/api
• API Key
– ifNzuw2bOYDcf1MEhmu38ufkUxIpYKc5ybR
• Comando
– listUsers
• Parâmetro
– listall=True
• Formato resposta
– json
Como assinar uma chamada API
• Gerar a URL da chamada API
command=listUsers&listall=True&apikey=ifNzuw2bOYDcf1MEhmu38ufkUxIpYKc5ybR&response=json
• Converter em minúsculas
command=listusers&listall=true&apikey=ifnzuw2boydcf1mehmu38ufkuxipykc5ybr&response=json
• Ordernar os parâmetros da URL
apikey=ifnzuw2boydcf1mehmu38ufkuxipykc5ybr&command=listusers&listall=true&response=json
• Gerar o hash da URL HMAC-SHA1 Base64 URL encoded
t8ma4%2Bbx0q3bUnIUUJhSmalEuFo%3D
• Acrescentar na URL
https://internuvem.usp.br/client/api?command=listUsers&listall=True&apikey=ifNzuw2bOYDcf1MEh
mu38ufkUxIpYKc5ybR&response=json&signature=t8ma4%2Bbx0q3bUnIUUJhSmalEuFo%3D
6
Interpretando as respostas
JSON
XML
3
4
Dicas de segurança
• Replay attacks
– Utilizar HTTPS sempre
– Utilizar o parâmetro ”expire” para limitar o tempo de validade da
chamada
• DOS attacks
– Limitar o API request rate
– Paginar as respostas (máximo de registros por página)
Paginando as respostas
• Repostas com 500 registros (máximo).
• Consultas com mais registros terão respostas paginadas
• Ex: Uma consulta de listagem de máquinas virtuais com 720 registros. A
resposta será retornada em 2 páginas (500 + 220)
• Parâmetros da consulta
– listVirtualMachines
– pagesize=500
– page=2
5
Comandos assíncronos
•
•
•
•
Comandos potencialmente demorados para completar a tarefa
Evita bloquear a sessão enquanto se espera o termino da tarefa
Identificados com (A) no documento de chamadas de API
Imediatamente retorna o ID do job para acompanhamento do
estado da execução da tarefa (queryAsyncJobResult)
• Estado da tarefa
– 0 : Tarefa em execução
– 1 : Tarefa terminada com sucesso
– 2 : Tarefa terminada com FALHA na execução (jobresultcode)
SF2
Slide 16
SF2
Criar um script para mostrar a execução com sucesso de um job assincrono e uma FALHA. Lembrar do job result
Stenio Firmino; 22/02/2016
Não sei programar, mas...
Gostaria de poder usar API sem
precisar aprender uma linguagem
de programação.
Queria automatizar algumas tarefas
rotineiras sem precisar criar um
programa para isso
Queira
trabalhar
com
uma
quantidade grande de VMs sem
precisar programar
Calma, ainda há alguma
chance, desde que...
• Saiba o básico de shell script como
bash ou powershell
• Tenha familiaridade com linhas de
comando
• Consiga trabalhar com processadores
de texto como sed, awk, cut, grep e
comandos semelhantes no
powershell
CloudMonkey
Aplicativo em Python para gerenciamento de recursos da Internuvem por linhas de
comando
Funcionalidades
•
•
•
•
•
•
•
•
•
Ferramenta CLI escrita em Python
Utilizável como comando CLI ou shell interativo
Múltiplos perfis
CLI auto complete
Busca reversa
Teclas de atalho EMACS
Uso de ”pipes” entre comandos
Suporta API assíncrona permitindo ou não o bloqueio do terminal
Formato de resposta em tabela, json, csv, xml
Instalação e configuração
• Requisitos
– Python 2.6
– readline, requests, Pygments, prettytable, argcomplete
• Instalação
pip install cloudmonkey
pip install --upgrade cloudmonkey
• Arquivos de configuração
~/.cloudmonkey/config
~/.cloudmonkey/history
~/.cloudmonkey/log
Configuração inicial
• Por padrão, o perfil local é criado ao executar o
cloudmonkey
# cloudmonkey
(local) > set url https://internuvem.usp.br
(local) > set apikey dhabsu73-38373...
(local) > set secret uehfb4y47373j3...
(local) > sync
512 APIs discovered and cached
Uso
Autocomplete
Help
> <tab><tab>
> list <tab><tab>
> list users <tab><tab>
>
>
>
>
>
>
help list
help list users
?list
?list users
list users --help
list users -h
Gerenciamento de perfil
set profile <nome>
[<nome>]
url = http://localhost:8080/client/api
username = admin
password = password
apikey =
secretkey =
timeout = 3600
expires = 600
Formato dos resultados
• Formato padrão
> set display default
> list users filter=username,email
count = 1
user:
email = [email protected]
username = api-admin
Formato dos resultados
• Formato tabela
> set display table
> list users filter=username,email
count = 1
user:
+-----------+-------------------+
| username |
email
|
+-----------+-------------------+
| api-admin | [email protected] |
+-----------+-------------------+
Formato dos resultados
• Formato json
> set display json
> list users filter=username,email
{
"count": 1,
"user": [
{
"email": "[email protected]",
"username": "api-admin”
}
]
}
Formato dos resultados
• Formato xml
> set display xml
> list users filter=username,email
<?xml version="1.0" ?>
<CloudStack-geinfo-admin>
<count>1</count>
<user>
<item>
<username>api-admin</username>
<email>[email protected]</email>
</item>
</user>
</CloudStack-geinfo-admin>
Formato dos resultados
• Formato csv
> set display csv
> list users filter=username,email
username,email
api-admin,[email protected]
Tarefas assíncronas
• No CloudMonkey, chamadas de API assíncronas, por padrão,
bloqueia o terminal
set asyncblock false
query asyncjobresult jobid=<job-id>
!
Demonstração
Atividades avançadas que podem ser executadas utilizando API CloudStack
Demonstração - Atividades avançadas
• Criação e destruição de múltiplas VMs
! • Troca de template básico de VMs
8 • Adição e remoção de VMs no balanceamento
de carga
9
• Adição e remoção de discos em múltiplas VMs
7