Como Usar o Doctl, o Cliente de Linha de comandos Oficial da DigitalOcean

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:

• Um computador local com o doctl instalado seguindo as instruções de instalação e configuração do projeto.

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 à conta
• auth para autenticação com a DigitalOcean
• compute 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.

Recuperando Dados no Formato JSON

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.

Formatação

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

Trabalhando com Recursos

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:

Trabalhando com Droplets

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.

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.

Trabalhando com SSH

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

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:

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.

Trabalhando com IPs Flutuantes

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.

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.

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.

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.

Trabalhando com Volumes de Armazenamento em Bloco

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.

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.

Trabalhando com Load Balancers

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.

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.

Trabalhando com Snapshots

O comando doctl compute snapshot pode ser usado para listar, excluir ou obter informações sobre snapshots de Droplet e de Volume.

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.

Trabalhando com Images

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.

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.

Trabalhando com Firewalls

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.

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.

Trabalhando com Tags

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.

Trabalhando com sua Conta

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

Recuperando Informações da sua Conta

Você pode descobrir detalhes básicos sobre sua conta, como seu endereço de e-mail configurado e o limite de Droplet:

doctl account get

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:

doctl account ratelimit

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.