One place for hosting & domains

      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:

      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

      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:

      ComandoNotas
      doctl compute droplet listSeus Droplets. Alguns comandos também levam o nome; a maioria exige o valor numérico da coluna ID.
      doctl compute ssh-key listAs chaves SSH associadas à sua conta. Para a criação de Droplets, você pode especificar o ID numérico ou fingerprint.
      doctl compute region listRegiões disponíveis. Use a string na coluna Slug.
      doctl compute image listImagens 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 listTamanhos de Droplets disponíveis. Use a string na coluna Slug.
      doctl compute tag listTags 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 dropletNotas
      actions droplet_idExibir um histórico de ações executadas para um Droplet.
      backups droplet_idListar backups para um Droplet.
      create name --size s-1vcpu-1gb --image image_slug --region nyc1Criar um Droplet. Tamanho, imagem e região são todos obrigatórios.
      delete droplet_id_ou_nomeExcluir um Droplet por ID ou nome.
      get droplet_idObter detalhes de um Droplet específico.
      kernels droplet_idListar kernels para um Droplet.
      listListar seus Droplets atuais.
      neighbors droplet_idListar seus Droplets em execução no mesmo hardware físico que um Droplet específico.
      snapshots droplet_idListar snapshots para um Droplet.
      tag droplet_id/nome_do_dropletColocar uma Tag em um Droplet.
      untag droplet_id/nome_do_dropletRetirar 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-actionNotas
      get droplet_id --action-id action_idObter detalhes sobre a ação em um Droplet.
      disable-backups droplet_idDesativar backups para um Droplet.
      reboot droplet_idReiniciar um Droplet.
      power-cycle droplet_idDesligar e ligar novamente um Droplet.
      shutdown droplet_idDesligar um Droplet.
      power-off droplet_idDesligar 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_idLigue um Droplet. O Droplet deve estar desligado.
      power-reset droplet_idResetar um Droplet.
      enable-ipv6 droplet_idAtivar ipv6 para um Droplet.
      enable-private-networking droplet_idAtivar rede privada para um Droplet.
      upgrade droplet_idFazer upgrade de um Droplet.
      restore droplet_id --image-id image_idRestaurar um Droplet para uma imagem de backup específica. O image_id deve ser um backup do Droplet.
      resize droplet_id --size 2gbRedimensionar 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_idReconstruir um Droplet a partir de uma imagem específica.
      rename droplet_id --droplet-name novo_nomeRenomear um Droplet para novo_nome.
      change-kernel droplet_id --kernel-id kernel_idAlterar o kernel de um Droplet para kernel_id.
      snapshot droplet_id --snapshot-name nome_do_snapshotTirar 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:

      FlagDescrição
      --ssh-user stringNome de usuário a ser usado para a sessão SSH.
      --ssh-port intA porta para a sessão SSH.
      --ssh-key-path stringCaminho para a chave SSH.
      --ssh-agent-forwardingAtivar 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-keyNotas
      listListar chaves SSH associadas à sua conta.
      get ssh_key_id_ou_fingerprintObter 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.pubAssociar uma chave pública à sua conta especificando um arquivo de origem.
      delete ssh_key_id_ou_fingerprintExcluir uma chave da sua conta por ID numérico ou fingerprint.
      update ssh_key_id_ou_fingerprint --key-name novo_nome_da_chaveAlterar 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-ipNotas
      listListar todos os endereços IP flutuantes.
      get endereço_ip_flutuanteObter detalhes de um endereço IP flutuante.
      create --region nyc1Crie um IP flutuante na região nyc1.
      delete endereço_ip_flutuanteExcluir 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-actionNotas
      assign ip_flutuante droplet_idAtribuir um IP flutuante ao Droplet pelo seu ID numérico.
      unassign ip_flutuanteCancelar a atribuição de um IP flutuante.
      get ip_flutuante action_idObter 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 domainNotas
      listListar domínios.
      create nome_de_domínio --ip-address endereço_ip_do_dropletCriar um domínio com registros padrão para endereço_ip_do_droplet.
      get nome_de_domínioObter um registro de domínio.
      delete nome_de_domínioExcluir 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 recordsNotas
      list nome_de_domínioListar registros para determinado domínio.
      create nome_de_domínio --record-type tipo_de_registroCriar um registro para o domínio.
      delete nome_de_domínio record_idExcluir registro pelo ID numérico.
      update nome_de_domínio --record-id record_idAtualizar 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 volumeNotas
      listListar volumes.
      create nome_do_volume --region região_do_volume --size tamanho_do_volumeCriar um volume. O nome, região e tamanho são obrigatórios.
      get volume_IDObter volume pelo ID numérico.
      delete volume_IDExcluir volume.
      snapshot volume_IDFazer 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-actionNotas
      attach volume_id droplet_idAnexar um volume a um Droplet.
      detach volume_id droplet_idDesanexar um volume de um Droplet.
      resize volume_id --region região_do_volume --size novo_tamanhoRedimensionar 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-balancerNotas
      listListar load balancers.
      create --name nome_do_lb --region região_do_lb --tag-name nome_da_tag --forwarding-rules regra_de_encaminhamentoCriar 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_encaminhamentoAtualizar 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_IDObter um load balancer pelo ID.
      delete lb_IDExcluir um load balancer pelo ID.
      add-droplets lb_ID --droplet-ids droplet_IDAdicionar Droplets a um load balancer.
      remove-droplets lb_ID --droplet-ids droplet_IDRemover Droplets de um load balancer.
      add-forwarding-rules lb_ID --forwarding-rules regra_de_encaminhamentoAdicionar regras de encaminhamento a um load balancer.
      remove-forwarding-rules lb_ID --forwarding-rules regra_de_encaminhamentoRemover 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 certificateNotas
      listListar todos os certificados.
      get certificate_idObter um certificado pelo ID.
      create --name nome_do_certificado --leaf-certificate-path caminho_do_cetrificado_em_folhaCriar um certificado. O nome e o caminho do certificado em folha são obrigatórios.
      delete certificate_idExcluir 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 snapshotNotas
      listListar todos os Snapshots.
      get snapshot_IDObter um Snapshot pelo ID.
      delete snapshot_IDExcluir 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 imageNotas
      list --publicListar todas imagens.
      list-distribution --publicListar todas imagens de distribuição disponíveis
      list-application --publicListar todas as imagens de Aplicações de Um Clique.
      list-userListar todas as imagens criadas pelo usuário.
      get image_idObter uma imagem pelo ID.
      update image_id --name nome_da_imagemAtualizar o nome da imagem. O nome é obrigatório.
      delete image_idExcluir 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-actionNotas
      get image_id --action-id action_idObter uma ação para a imagem pelo seu ID. O ID da ação é obrigatório.
      transfer image_id --region regiãoTransferir 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 firewallNotas
      listListar todos os Firewalls.
      list-by-droplet droplet_idListar todos os Firewalls pelo ID numérico do Droplet.
      create --name nome_do_firewall --inbound-rules regras_de_entrada --outbound-rules regras_de_saídaCriar 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ídaAtualizar um Firewall. O ID numérico, o nome e pelo menos uma regra de entrada ou saída são obrigatórios.
      get firewall_idObter um Firewall pelo seu ID numérico.
      delete firewall_idExcluir um firewall pelo ID numérico.
      add-droplets firewall_id --droplet-ids droplet_IDsAdicionar Droplets pelo seu ID numérico ao Firewall.
      remove-droplets firewall_id --droplet-ids droplet_IDsRemover Droplets do Firewall pelos seus IDs numéricos.
      add-tags firewall_id --tag-names tagsAdicionar Tags ao Firewall.
      remove-tags firewall_id --tag-names tagsRemover Tags do Firewall.
      add-rules firewall_id --inbound-rules regras_de_entrada --outbound-rules regras_de_saídaAdicionar regras de entrada ou saída ao Firewall.
      remove-rules firewall_id --inbound-rules regras_de_entrada --outbound-rules regras_de_saídaRemover 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 tagNotas
      create nome_da_tagCriar uma Tag.
      get nome_da_tagObter uma Tag pelo nome.
      listListar todas as Tags.
      delete nome_da_tagExcluir 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

      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:

      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.



      Source link


      Leave a Comment