Uma versão anterior deste tutorial foi escrita por Brennen Bearnes.
Introdução
O painel de controle web da DigitalOcean fornece uma interface de gerenciamento de Droplets usando apontar e clicar . No entanto, você pode preferir uma ferramenta de linha de comando se tiver muitos Droplets para gerenciar, precisar administrar Droplets a partir do terminal sem uma área de trabalho gráfica disponível ou tiver tarefas que se beneficiariam de uma interface com script.
doctl é o cliente oficial de linha de comandos da DigitalOcean. Ele utiliza a API da DigitalOcean para fornecer acesso à maioria dos recursos da conta e dos Droplets.
Pré-requisitos
Para seguir este tutorial, você precisará de:
Este tutorial pretende ser uma referência para a maioria das operações do doctl. Como os comandos doctl são intimamente ligados à API, também pode ser útil ler a documentação da API e Como Usar a API da DigitalOcean v2.
Uso Genérico do doctl
Executando Comandos
No doctl, os recursos individuais são executados, fornecendo ao utilitário um comando, um ou mais subcomandos e, às vezes, uma ou mais opções que especificam valores particulares. Os comandos são agrupados em três categorias principais:
account para informações relacionadas à contaauth para autenticação com a DigitalOceancompute para o gerenciamento de infraestrutura
Para ver uma visão geral de todos os comandos, você pode chamar o doctl por si só. Para ver todos os comandos disponíveis em uma das três categorias principais, você pode usar doctl categoria, como doctl compute. Para um guia de uso de um comando específico, digite o comando com a flag --help, como em doctl compute droplet --help.
Em ambientes de script, ou ao trabalhar na linha de comando com ferramentas de processamento de dados, geralmente é útil obter uma saída legível por máquina a partir de um comando.
Por padrão, o doctl formata sua saída em colunas de texto legível por humanos, mas pode produzir uma saída JSON detalhada usando a opção --output json.
- doctl compute droplet get droplet_id --output json
Sample Output
{
"id": droplet_id,
"name": "nome_do_droplet",
"memory": 1024,
"vcpus": 1,
"disk": 30,
"region": {
"slug": "nyc3",
"name": "New York 3",
"sizes": [
...
Além de ser um formato legível com bibliotecas padrão na maioria das linguagens de programação, a saída JSON pode permitir uma inspeção mais detalhada dos Droplets e de outros recursos.
Geralmente, é útil obter apenas um conjunto de campos da saída. Para fazer isso, você pode usar a flag --format, que pega a lista de campos pelo seu nome. Por exemplo, se você deseja obter apenas o ID, nome e endereço IP dos seus Droplets, você pode usar o seguinte comando:
- doctl compute droplet list --format "ID,Name,PublicIPv4"
Sample output
ID Name Public IPv4
50513569 doctl-1 67.205.152.65
50513570 test 67.205.148.128
50513571 node-1 67.205.131.88
Templates
O comando doctl compute droplet get suporta template de saída, o que lhe permite personalizar o formato da saída. Para usar esse recurso, especifique o template formatado para Go via a flag --template
Por exemplo, se você deseja obter o nome de um Droplet no formato droplet_name: nome_do_droplet, use o seguinte comando get:
- doctl compute droplet get 12345678 --template "nome_do_droplet: {{ .Name}}"
Output
nome_do_droplet: ubuntu-1gb-nyc3-01
Listando Recursos
Para obter uma lista de recursos, como Droplets, você pode usar o comando list sem parâmetros.
- doctl compute droplet list
Sample output for list command
ID Name Public IPv4 Private IPv4 Public IPv6 Memory VCPUs Disk Region Image Status Tags
50513569 test-1 67.205.152.65 512 1 20 nyc1 Ubuntu 16.04.2 x64 active
50513571 test-2 67.205.131.88 512 1 20 nyc1 Ubuntu 16.04.2 x64 active
50513570 site 67.205.148.128 512 1 20 nyc1 Ubuntu 16.04.2 x64 active
O comando list suporta um glob como um parâmetro opcional. Um glob representa um padrão com caracteres curinga que podem ser usados para filtrar recursos específicos por nome. Por exemplo, para obter uma lista de Droplets cujos nomes começam com test, você pode usar o seguinte comando:
doctl compute droplet list 'test*'
Sample output for list command with 'doctl-' as glob
ID Name Public IPv4 Private IPv4 Public IPv6 Memory VCPUs Disk Region Image Status Tags
50513569 test-1 67.205.152.65 512 1 20 nyc1 Ubuntu 16.04.2 x64 active
50513571 test-2 67.205.131.88 512 1 20 nyc1 Ubuntu 16.04.2 x64 active
Criando Recursos
Criar um recurso requer comandos mais longos com parâmetros mais detalhados. Para criar um Droplet, você precisará especificar a imagem que deseja usar, a região do datacenter e o tipo de Droplet que deseja usando o slug associado. Veja New Size Slugs for Droplet Plan Changes
para encontrar o slug que você quer usar. Como alternativa, execute o comando doctl compute size list.
Por exemplo, o comando a seguir cria um Droplet Debian 8 de 64 bits chamado test com 1 GB de memória, uma CPU, uma chave SSH e backups ativados.
- doctl compute droplet create test --size s-1vcpu-1gb --image debian-8-x64 --region nyc1 --ssh-keys 4d:23:e6:e4:8c:17:d2:cf:89:47:36:b5:c7:33:40:4e --enable-backups
Você verá esta saída:
Sample Droplet creation output
ID Name Public IPv4 Memory VCPUs Disk Region Image Status
11450164 test 1024 1 30 nyc1 Debian 8.3 x64 new
A exclusão de um recurso requer um ID de recurso como argumento ou um nome de recurso no caso de não existir um ID para determinado recurso (por exemplo, tags). Para confirmar suas intenções, você precisa confirmar todas as ações de exclusão, respondendo à pergunta de confirmação com y ou yes.
doctl compute droplet delete 123456
Output
Warning: Are you sure you want to delete droplet(s) (y/N) ?
Não fornecer uma resposta ou fornecer uma resposta diferente de y ou yes cancelará a ação sem excluir o recurso. Você pode fazer com que o doctl assuma uma resposta afirmativa sem fornecê-la explicitamente, usando a flag -f (--force):
doctl compute droplet delete -f 123456
Localizando Identificadores Exclusivos para Recursos
O comando de criação de Droplets requer uma série de identificadores, como nyc1 para a região NYC1, debian-8-x64 para a imagem Debian e uma impressão digital ou fingerprint da chave SSH como 4d:23:e6:e4:8c:17:d2:cf:89:47:36:b5:c7:33:40:4e.
Vários recursos, como Droplets e imagens, são identificados por um valor (geralmente numérico) exclusivo no banco de dados da DigitalOcean.
Você pode obter os identificadores exclusivos necessários para a maioria dos comandos da API:
| Comando | Notas |
|---|
doctl compute droplet list | Seus Droplets. Alguns comandos também levam o nome; a maioria exige o valor numérico da coluna ID. |
doctl compute ssh-key list | As chaves SSH associadas à sua conta. Para a criação de Droplets, você pode especificar o ID numérico ou fingerprint. |
doctl compute region list | Regiões disponíveis. Use a string na coluna Slug. |
doctl compute image list | Imagens disponíveis, incluindo snapshots, backups e imagens base de distribuição. Use a string na coluna Slug para a criação de novos Droplets. |
doctl compute size list | Tamanhos de Droplets disponíveis. Use a string na coluna Slug. |
doctl compute tag list | Tags disponíveis. Use a string na coluna Name. |
Criando, Excluindo, e Inspecionando Droplets
O comando doctl compute droplet lhe permite criar, excluir e inspecionar Droplets. Novamente, a maioria dos comandos para trabalhar com Droplets individuais exige o ID exclusivo do Droplet, e estes podem ser encontrados na saída do comando doctl droplet list.
Subcomando doctl compute droplet | Notas |
|---|
actions droplet_id | Exibir um histórico de ações executadas para um Droplet. |
backups droplet_id | Listar backups para um Droplet. |
create name --size s-1vcpu-1gb --image image_slug --region nyc1 | Criar um Droplet. Tamanho, imagem e região são todos obrigatórios. |
delete droplet_id_ou_nome | Excluir um Droplet por ID ou nome. |
get droplet_id | Obter detalhes de um Droplet específico. |
kernels droplet_id | Listar kernels para um Droplet. |
list | Listar seus Droplets atuais. |
neighbors droplet_id | Listar seus Droplets em execução no mesmo hardware físico que um Droplet específico. |
snapshots droplet_id | Listar snapshots para um Droplet. |
tag droplet_id/nome_do_droplet | Colocar uma Tag em um Droplet. |
untag droplet_id/nome_do_droplet | Retirar uma tag de um Droplet. |
Iniciando Ações em Droplets
O comando doctl compute droplet-action lhe permite disparar várias ações para um Droplet, incluindo ações de gerenciamento de energia e alternância de recursos como backups e redes privadas.
Subcomando doctl compute droplet-action | Notas |
|---|
get droplet_id --action-id action_id | Obter detalhes sobre a ação em um Droplet. |
disable-backups droplet_id | Desativar backups para um Droplet. |
reboot droplet_id | Reiniciar um Droplet. |
power-cycle droplet_id | Desligar e ligar novamente um Droplet. |
shutdown droplet_id | Desligar um Droplet. |
power-off droplet_id | Desligar um Droplet. O Droplet deve estar ligado. Geralmente, é melhor fazer isso na linha de comando do próprio Droplet para evitar perda de dados. |
power-on droplet_id | Ligue um Droplet. O Droplet deve estar desligado. |
power-reset droplet_id | Resetar um Droplet. |
enable-ipv6 droplet_id | Ativar ipv6 para um Droplet. |
enable-private-networking droplet_id | Ativar rede privada para um Droplet. |
upgrade droplet_id | Fazer upgrade de um Droplet. |
restore droplet_id --image-id image_id | Restaurar um Droplet para uma imagem de backup específica. O image_id deve ser um backup do Droplet. |
resize droplet_id --size 2gb | Redimensionar um Droplet. O Droplet deve estar desligado. Por padrão, o disco não é redimensionado, o que permite que o Droplet seja rebaixado. Você pode redimensionar o disco usando a flag --resize-disk. |
rebuild droplet_id --image-id image_id | Reconstruir um Droplet a partir de uma imagem específica. |
rename droplet_id --droplet-name novo_nome | Renomear um Droplet para novo_nome. |
change-kernel droplet_id --kernel-id kernel_id | Alterar o kernel de um Droplet para kernel_id. |
snapshot droplet_id --snapshot-name nome_do_snapshot | Tirar um instantâneo ou snapshot de um Droplet, nomeando-o como nome_do_snapshot. |
Fazendo Conexões SSH
Para se conectar a um Droplet individual com SSH, geralmente é necessário saber seu endereço IP ou nome de domínio totalmente qualificado. Você pode usar o doctl para se conectar a um Droplet pelo seu nome, ID numérico ou IP privado:
- doctl compute ssh nome_do_droplet
- doctl compute ssh droplet_id
- doctl compute ssh --ssh-private-ip ip_privado_do_droplet
Além disso, você pode fornecer um comando para executar assim que a conexão SSH for estabelecida usando a flag --ssh-command. Isso executará o comando, cuja saída será impressa no seu terminal local, e então a sessão SSH será fechada.
- doctl compute ssh --ssh-command comando
Nota: No momento, o encaminhamento de comandos SSH não está disponível no Windows.
O nome do usuário SSH padrão é root (core para o CoreOS) e a porta padrão é a 22. Você pode usar flags para definir valores não padrão e ativar outros recursos:
| Flag | Descrição |
|---|
--ssh-user string | Nome de usuário a ser usado para a sessão SSH. |
--ssh-port int | A porta para a sessão SSH. |
--ssh-key-path string | Caminho para a chave SSH. |
--ssh-agent-forwarding | Ativar encaminhamento de agente. |
Você também pode alterar os valores de configuração padrão em um arquivo de configuração. O arquivo README do projeto tem mais detalhes sobre como fazer isso.
Usando Chaves SSH
Você pode gerenciar as chaves públicas SSH associadas à sua conta usando o comando doctl compute ssh-key. A maioria dos comandos que fazem referência às chaves SSH aceitam o ID numérico da chave ou sua fingerprint.
Subcomando doctl compute ssh-key | Notas |
|---|
list | Listar chaves SSH associadas à sua conta. |
get ssh_key_id_ou_fingerprint | Obter informações sobre uma chave específica, por ID numérico ou fingerprint da chave. |
create novo_nome_da_chave --public-key "chave_pública" | Associar uma chave pública à sua conta, especificando seu conteúdo. |
import novo_nome_da_chave --public-key-file ~/.ssh/id_rsa.pub | Associar uma chave pública à sua conta especificando um arquivo de origem. |
delete ssh_key_id_ou_fingerprint | Excluir uma chave da sua conta por ID numérico ou fingerprint. |
update ssh_key_id_ou_fingerprint --key-name novo_nome_da_chave | Alterar o nome de uma chave por ID numérico ou fingerprint. |
Um IP flutuante é um endereço IP estático acessível ao público que pode ser atribuído a um de seus Droplets. Para uma descrição detalhada do recurso, você pode ler Como usar IPs flutuantes na DigitalOcean. Você pode manipular IPs flutuantes com doctl compute floating-ip.
Subcomando doctl compute floating-ip | Notas |
|---|
list | Listar todos os endereços IP flutuantes. |
get endereço_ip_flutuante | Obter detalhes de um endereço IP flutuante. |
create --region nyc1 | Crie um IP flutuante na região nyc1. |
delete endereço_ip_flutuante | Excluir um endereço IP flutuante. |
Atribuir IPs Flutuantes aos Droplets
O comando doctl compute floating-ip-action é usado para atribuir ou cancelar a atribuição de um IP flutuante de um Droplet.
Subcomando doctl compute floating-ip-action | Notas |
|---|
assign ip_flutuante droplet_id | Atribuir um IP flutuante ao Droplet pelo seu ID numérico. |
unassign ip_flutuante | Cancelar a atribuição de um IP flutuante. |
get ip_flutuante action_id | Obter detalhes sobre uma ação de IP flutuante pelo seu ID numérico. |
Trabalhando com Domains
O comando doctl compute domain é usado para gerenciar domínios. Veja nossa Série de Introdução ao gerenciamento de DNS para uma visão geral mais ampla do assunto.
Subcomando doctl compute domain | Notas |
|---|
list | Listar domínios. |
create nome_de_domínio --ip-address endereço_ip_do_droplet | Criar um domínio com registros padrão para endereço_ip_do_droplet. |
get nome_de_domínio | Obter um registro de domínio. |
delete nome_de_domínio | Excluir um domínio. |
Gerenciando Registros de Domínio
O comando doctl compute domain records pode ser usado para criar, excluir, atualizar ou obter informações sobre os registros DNS do domínio.
Subcomando doctl compute domain records | Notas |
|---|
list nome_de_domínio | Listar registros para determinado domínio. |
create nome_de_domínio --record-type tipo_de_registro | Criar um registro para o domínio. |
delete nome_de_domínio record_id | Excluir registro pelo ID numérico. |
update nome_de_domínio --record-id record_id | Atualizar registro pelo ID numérico. |
Criando, Excluindo e Inspecionando Volumes de Armazenamento em Bloco
O comando doctl compute volume pode ser usado para criar, excluir ou obter informações sobre os volumes de armazenamento em bloco da DigitalOcean. Para obter mais informações sobre esse recurso, leia nosso guia Como usar o armazenamento em bloco na DigitalOcean.
Subcomando doctl compute volume | Notas |
|---|
list | Listar volumes. |
create nome_do_volume --region região_do_volume --size tamanho_do_volume | Criar um volume. O nome, região e tamanho são obrigatórios. |
get volume_ID | Obter volume pelo ID numérico. |
delete volume_ID | Excluir volume. |
snapshot volume_ID | Fazer um Snapshot de um volume. |
Iniciando Ações de Volume
O comando doctl compute volume-action lhe permite disparar ações para um volume, incluindo anexar volumes e desanexar volumes de Droplets.
Subcomando doctl compute volume-action | Notas |
|---|
attach volume_id droplet_id | Anexar um volume a um Droplet. |
detach volume_id droplet_id | Desanexar um volume de um Droplet. |
resize volume_id --region região_do_volume --size novo_tamanho | Redimensionar um volume. |
O comando doctl compute load-balancer pode ser usado para criar, excluir ou obter informações sobre os balanceadores de carga ou Load Balancers da DigitalOcean. Para obter mais informações sobre esse recurso, leia nossa Introdução aos balanceadores de carga da DigitalOcean.
Subcomando doctl compute load-balancer | Notas |
|---|
list | Listar load balancers. |
create --name nome_do_lb --region região_do_lb --tag-name nome_da_tag --forwarding-rules regra_de_encaminhamento | Criar um Load Balancer. O nome, a região, uma tag ou lista de IDs de Droplets e pelo menos uma regra de encaminhamento são obrigatórios. |
update --name nome_do_lb --region região_do_lb --tag-name nome_da_tag --forwarding-rules regra_de_encaminhamento | Atualizar um Load Balancer. O nome, a região, uma tag ou lista de IDs de Droplets e pelo menos uma regra de encaminhamento são obrigatórios. |
get lb_ID | Obter um load balancer pelo ID. |
delete lb_ID | Excluir um load balancer pelo ID. |
add-droplets lb_ID --droplet-ids droplet_ID | Adicionar Droplets a um load balancer. |
remove-droplets lb_ID --droplet-ids droplet_ID | Remover Droplets de um load balancer. |
add-forwarding-rules lb_ID --forwarding-rules regra_de_encaminhamento | Adicionar regras de encaminhamento a um load balancer. |
remove-forwarding-rules lb_ID --forwarding-rules regra_de_encaminhamento | Remover regras de encaminhamento de um load balancer. |
Quando usado como argumento para o doctl, as regras de encaminhamento devem ser expressas como: entry_protocol:protocolo,entry_port:porta,target_protocol:protocolo,target_port:porta.
Gerenciando Certificados
O subcomando doctl compute certificate lhe permite fazer upload e gerenciar certificados SSL, chaves privadas e cadeias de certificados.
Subcomando doctl compute certificate | Notas |
|---|
list | Listar todos os certificados. |
get certificate_id | Obter um certificado pelo ID. |
create --name nome_do_certificado --leaf-certificate-path caminho_do_cetrificado_em_folha | Criar um certificado. O nome e o caminho do certificado em folha são obrigatórios. |
delete certificate_id | Excluir um certificado pelo ID. |
O comando doctl compute snapshot pode ser usado para listar, excluir ou obter informações sobre snapshots de Droplet e de Volume.
Subcomando doctl compute snapshot | Notas |
|---|
list | Listar todos os Snapshots. |
get snapshot_ID | Obter um Snapshot pelo ID. |
delete snapshot_ID | Excluir um Snapshot. |
Para criar um novo Snapshot, você precisa usar o comando apropriado na árvore de comandos do recurso relevante. Por exemplo:
doctl compute droplet-action snapshot droplet_ID cria um Snapshot de um Droplet.doctl compute volume snapshot volume_ID cria um Snapshot de um Volume.
O comando doctl compute image lhe permite gerenciar todas as imagens, incluindo imagens de distribuição, imagens de aplicações e imagens criadas pelo usuário, como backups e snapshots. Recomendamos o uso do comando snapshot para gerenciar snapshots, pois ele fornece mais detalhes, possui funcionalidade de exclusão e suporta snapshots de Armazenamento em Bloco.
Subcomando doctl compute image | Notas |
|---|
list --public | Listar todas imagens. |
list-distribution --public | Listar todas imagens de distribuição disponíveis |
list-application --public | Listar todas as imagens de Aplicações de Um Clique. |
list-user | Listar todas as imagens criadas pelo usuário. |
get image_id | Obter uma imagem pelo ID. |
update image_id --name nome_da_imagem | Atualizar o nome da imagem. O nome é obrigatório. |
delete image_id | Excluir uma imagem pelo ID. |
Chamando Ações de Imagens
O comando doctl compute image-action lhe permite transferir imagens e obter detalhes sobre as ações invocadas nas imagens.
Subcomando doctl compute image-action | Notas |
|---|
get image_id --action-id action_id | Obter uma ação para a imagem pelo seu ID. O ID da ação é obrigatório. |
transfer image_id --region região | Transferir uma imagem para outra região. O ID da imagem e a região são obrigatórios. |
O comando doctl compute firewall lhe permite criar e gerenciar Firewalls, incluindo a criação e a manutenção de regras. Para obter mais informações sobre como administrar Firewalls usando o doctl, consulte o tutorial How To Secure Web Server Infrastructure With DigitalOcean Cloud Firewalls Using Doctl.
Comando doctl compute firewall | Notas |
|---|
list | Listar todos os Firewalls. |
list-by-droplet droplet_id | Listar todos os Firewalls pelo ID numérico do Droplet. |
create --name nome_do_firewall --inbound-rules regras_de_entrada --outbound-rules regras_de_saída | Criar um Firewall. O nome e pelo menos uma regra de entrada ou saída são obrigatórios. |
update firewall_id --name nome_do_firewall --inbound-rules regras_de_entrada --outbound-rules regras_de_saída | Atualizar um Firewall. O ID numérico, o nome e pelo menos uma regra de entrada ou saída são obrigatórios. |
get firewall_id | Obter um Firewall pelo seu ID numérico. |
delete firewall_id | Excluir um firewall pelo ID numérico. |
add-droplets firewall_id --droplet-ids droplet_IDs | Adicionar Droplets pelo seu ID numérico ao Firewall. |
remove-droplets firewall_id --droplet-ids droplet_IDs | Remover Droplets do Firewall pelos seus IDs numéricos. |
add-tags firewall_id --tag-names tags | Adicionar Tags ao Firewall. |
remove-tags firewall_id --tag-names tags | Remover Tags do Firewall. |
add-rules firewall_id --inbound-rules regras_de_entrada --outbound-rules regras_de_saída | Adicionar regras de entrada ou saída ao Firewall. |
remove-rules firewall_id --inbound-rules regras_de_entrada --outbound-rules regras_de_saída | Remover as regras de entrada ou saída do Firewall. |
Quando usado como argumento para o doctl, as regras de entrada ou saída devem ser expressas como: protocol:protocolo,ports:portas,droplet_id:droplet-id.
As Tags são usadas para aplicar rótulos personalizados aos recursos, permitindo que você os filtre facilmente. Você pode aprender mais sobre Tags no tutorial How To Tag DigitalOcean Droplets.
Subcomando doctl compute tag | Notas |
|---|
create nome_da_tag | Criar uma Tag. |
get nome_da_tag | Obter uma Tag pelo nome. |
list | Listar todas as Tags. |
delete nome_da_tag | Excluir uma Tag pelo nome. |
Lendo o Histórico de Ações da sua Conta
O sistema da DigitalOcean registra um histórico das ações executadas em seus Droplets, IPs flutuantes e outros recursos. Você pode acessar esses dados com o comando doctl compute action:
- doctl compute action list
Você pode ver ações para um Droplet específico da seguinte maneira:
- doctl compute droplet actions droplet_id
Você pode descobrir detalhes básicos sobre sua conta, como seu endereço de e-mail configurado e o limite de Droplet:
Como as solicitações de API são limitadas por uma taxa de acessos, pode ser útil ver quantas solicitações você fez recentemente e quando o limite deve ser redefinido:
Conclusão
O utilitário doctl é uma ferramenta útil para gerenciar Droplets e outros recursos na linha de comando. Isso pode reduzir bastante a quantidade de interação manual com interfaces baseadas em web, necessárias para tarefas diárias de desenvolvimento e de administração.
Além de aprender sobre a API subjacente, você pode querer explorar bibliotecas que envolvem a API para linguagens de programação populares, e ferramentas como Ansible para automatizar tarefas no nível do sistema.
