Pular para o conteúdo principal
Voltar à Cloud

MGC CLI - Guia do Usuário

A Magalu Cloud (MGC) está sempre trabalhando no desenvolvimento de melhorias e novas funcionalidades para a CLI, por isso é importante que você verifique qual a versão atual que você possui e a mantenha atualizada para usufruir dos novos benefícios e evoluções da ferramenta.

 

Instalação e configuração


Nas seções a seguir vamos fornecer as instruções para instalação e configuração da CLI no seu sistema. Tenha certeza de seguir as instruções adequadas para o seu sistema operacional (Linux/Mac/Windows) e arquitetura (amd64/arm).

 

Pré-requisitos


Para conseguir acessar a Magalu Cloud através da CLI você precisará de:

  • Sua credencial criada no sistema ID Magalu
  • Uma conta previamente criada na Magalu Cloud

Cada sistema operacional possui seus próprios pré-requisitos que estão listados nas suas respectivas instruções de instalação.


Instalação


Neste tópico vamos descrever passo-a-passo como fazer a instalação da CLI no seu sistema. Encontre a seção correta para o seu sistema operacional dentre as listadas abaixo.

 

A CLI possui arquivos de instalação separados para cada arquitetura. Baixe o arquivo correspondente a sua arquitetura e sistema operacional no repositório abaixo:

 

https://github.com/MagaluCloud/mgccli/releases


Linux

Siga as instruções de acordo com o tipo de pacote que você deseja utilizar.

 

Debian / Ubuntu

 

Para instalar a CLI apartir do pacote deb, basta executar o comando abaixo em um terminal dentro do diretório onde está o pacote. Atualize o nome do arquivo .deb de acordo com aquele que você baixou.

 

sudo dpkg -i mgccli_x.xx.x_linux_amd64.deb

 

Fedora/ CentOS

 

Para instalar a CLI apartir do pacote rpm, basta executar o comando abaixo em um terminal dentro do diretório onde está o pacote. Atualize o nome do arquivo .rpm de acordo com aquele que você baixou.

 

sudo rpm -i mgccli_x.xx.x_linux_amd64.rpm

 

Arquivo .tar.gz

 

Abra um terminal e execute o seguinte comando para criar um diretório dedicado a CLI na sua home de usuário.

 

mkdir ~/mgc_cli

 

Execute o comando abaixo na mesma pasta onde está o arquivo .tar.gz. Atualize o nome do arquivo de acordo com aquele que você baixou.

 

tar -xvf mgccli_x.xx.x_linux_amd64.tar.gz -C ~/mgc_cli

 

Para melhor experiência com a CLI, recomendamos que o diretório de instalação seja adicionado na variável PATH. Rode o comando abaixo e depois adicione essa linha ao arquivo ~/.bashrc ou ~/.zshrc dependendo do seu shell.

 

export PATH=$HOME/mgc_cli:$PATH


Confirme a instalação com o seguinte comando:

 

mgc --version

 

Windows

 

A CLI possui arquivos de instalação separados para cada arquitetura. Baixe o arquivo correspondente a sua arquitetura (amd64 / arm) no repositório oficial.

 

Para instalar a CLI no seu sistema Windows 10/11 siga os passos abaixo.

  1. Extraia o conteúdo do arquivo ZIP para uma pasta de sua preferência.
  2. Abra um Prompt de Comando ou terminal Powershell na pasta onde você extraiu os arquivos.
  3. Rode o comando abaixo para confirmar a instalação:

mgc --version

 

MacOS

 

Você pode optar por usar a ferramenta Homebrew, que facilita a instalação e atualizações, ou então o arquivo tar.gz.

 

Homebrew

 

Para instalar a CLI utilizar a ferramenta Homebrew, você precisa ter certeza de que ela está corretamente instalada no seu sistema. Visite o site oficial: https://brew.sh/

 

Depois abra um terminal e execute o comando tap no nosso repositório oficial:

 

brew tap MagaluCloud/homebrew-mgccli


e por final execute o comando de instalação:

 

brew install mgc

 

Arquivo tar.gz

 

Abra um terminal e execute o seguinte comando para criar um diretório dedicado a CLI na sua home de usuário.

 

mkdir ~/mgc_cli

 

Execute o comando abaixo na mesma pasta onde está o arquivo .tar.gz. Atualize o nome do arquivo de acordo com aquele que você baixou.

 

tar -xvf mgccli_x.xx.x_linux_amd64.tar.gz -C ~/mgc_cli

 

Para melhor experiência com a CLI, recomendamos que o diretório de instalação seja adicionado na variável PATH. Rode o comando abaixo e depois adicione essa linha ao arquivo ~/.bashrc ou ~/.zshrc dependendo do seu shell.

 

export PATH=$HOME/mgc_cli:$PATH


Confirme a instalação com o seguinte comando:

 

mgc --version

 

IMPORTANTE: Será necessário dar permissão de execução ao binário. Na primeira vez que você executá-lo no terminal, o macOS exibirá um alerta. Ignore o alerta e vá até "Configurações do Sistema", na aba "Privacidade e Segurança". Lá você deverá confirmar que aceita a execução do binário "mgc".

 

Configuração da CLI

Aqui vamos guiar você na configuração da Command Line Interface (CLI) da Magalu Cloud que já está instalada no seu sistema. Dentre as configurações principais estão:

  • Autenticação - processo obrigatório de identificação do seu usuário da CLI para que você possa executar os comandos sobre a sua conta. Este é o primeiro passo antes de executar qualquer outro comando sobre seus produtos.
  • Região - você pode pré-definir uma região na qual todos os seus comandos serão executados. Desta forma não haverá a necessidade de informar a região em cada comando.
  • Padrão de Saída - é possível definir qual o tipo padrão de saída para os comandos (tabela, json, yaml, etc).

Você pode ver todas as opções de configurações disponíveis (exceto autenticação, que é feita separadamente) rodando o seguinte comando:

mgc config list


As configurações alteradas pela CLI serão armazenadas em um arquivo local dentro da sua
pasta de usuário:

$HOME/.config/mgc/<PERFIL>/cli.yaml.


No Windows essa pasta se localiza em:

%APPDATA%\Roaming\mgc\<PERFIL>\


Onde <PERFIL> é o nome do perfil que você deseja configurar.


Autenticando na CLI

Para fazer a autenticação na CLI e ter sua credencial armazenada no arquivo de configuração, você precisa rodar o seguinte comando:

mgc auth login


Este comando abrirá uma janela do seu navegador padrão diretamente no site do ID Magalu, onde você deverá fazer seu login. Ao terminar o procedimento e fechar o navegador, a CLI exibirá a confirmação e seu token de acesso será salvo no arquivo abaixo.

$HOME/.config/mgc/<PERFIL>/auth.yaml

 

Definindo padrões


Algumas configurações padrão são importantes para agilizar a execução de comandos que repetem os mesmos valores para flags como region ou cli.output.

Formato de Saída


O comando abaixo executa a alteração permanente do tipo de saída da CLI para JSON, ou seja, todos os comandos executados após este terão suas saídas nesse formato se não houver um outro formato especificado na linha do comando.

mgc config set --key defaultOutput --value json


Outros valores possíveis para essa configuração seriam: jsonpath-file, table, table-file, template, template-file, yaml, json, jsonpath.


Para mais detalhes de como utilizar cada um dos formatos, execute o comando de ajuda abaixo.

mgc --cli.output help


Neste guia vamos utilizar como padrão a saída do tipo json.


Região


Ao definir uma região padrão para a CLI todos os comandos executados farão referência a ela,
salvo se outra região for informada na linha de comando. Para definir a região padrão como
sendo br-ne1 execute o comando abaixo.

mgc config set --key region --value br-ne1


Há outros valores possíveis para essa variável de configuração, como por exemplo br-se1 .
Consulte a lista de regiões disponíveis rodando o comando abaixo.

mgc config get-schema region -o jsonpath=$.enum

 

Usando a CLI

Abaixo vamos explorar alguns dos comandos mais frequentemente usados para ver e administrar seus recursos na Magalu Cloud.


Object Storage


Através da CLI é possível criar e gerenciar seus buckets e objetos armazenados neles. Abaixo vamos explorar alguns dos comandos mais utilizados na gestão de Object Storage na Magalu Cloud.

 

Configurando o API Key 

Antes de começar a usar o Object Storage você precisa criar um API Key. Execute o comando abaixo. 

mgc object-storage api-key create --name my_key 


Defina a nova key como prioritária. Ao executar o comando abaixo a CLI vai listar as api-keys disponíveis e permitir que você selecione uma interativamente. 

mgc object-storage api-key select


Agora a CLI está habilitada a operar sobre seus buckets de object storage. 

 

Criando um Bucket 


Para criar um novo bucket você pode rodar o comando abaixo especificando o nome de sua preferência (sem espaços). 

mgc object-storage buckets create --name "mgc-bucket-1" 


A partir de agora você pode referenciar este bucket diretamente pelo nome ao administrar seus objetos. E para validar a criação do novo bucket vamos listar todos os buckets existentes com o seguinte comando. 

{
 "Buckets": [
  {
   "CreationDate": "2024-01-19T13:57:23.000Z",
   "Name": "mgc-bucket-1"
  },
  {
   "CreationDate": "2024-01-30T19:35:24.000Z",
   "Name": "mgc-bucket-2"
  }
 ],
 "Owner": {
  "DisplayName": "cloud_br-ne-1_prod_bf610b24-b802-46d6-9d57-32c6a053d7a8:cloud_br-ne-1_prod_bf610b24-b802-46d6-9d57-32c6a053d7a8",
  "ID": "cloud_br-ne-1_prod_bf610b24-b802-46d6-9d57-32c6a053d7a8:cloud_br-ne-1_prod_bf610b24-b802-46d6-9d57-32c6a053d7a8"
 }
}


Usando a flag -o e especificando uma expressão jsonpath para conseguimos filtrar só a informação que desejamos no JSON de retorno. 

 

Fazendo upload e download de objetos 


Agora que já temos um bucket criado, podemos começar a fazer upload de objetos. Para realizar essa ação vamos pressupor a existência de um arquivo texto chamado arquivo_teste.tx.


Ao executar o comando abaixo, CLI vai enviar o arquivo local indicado pela flag --src para o caminho dentro do bucket informado na flag --dst.

mgc object-storage objects upload --src "arquivo_teste.txt" --dst "mgc-bucket-1/arquivo_teste.txt"


Saída no terminal:

arquivo_teste.txt                                     .. done! [23B in 1ms]
{
"file": "arquivo_teste.txt",
"uri": "mgc-bucket-1/arquivo_teste.txt"
}


E para baixar o arquivo para sua máquina local basta executar um comando similar de download, como mostra o exemplo abaixo. 

mgc object-storage objects download --src "mgc-bucket-1/arquivo_teste.txt" --dst "arquivo_teste_downloaded.txt"


Saída no terminal:

arquivo_teste_downloaded.txt                         ... done! [23B in 0s]
{
  "dst": "arquivo_teste_downloaded.txt",
  "src": "my-test/arquivo_teste.txt"
}


Neste caso o nome do arquivo destino foi alterado propositalmente para não conflitar o arquivo já existente, demonstrando essa possibilidade e flexibilidade de informar qual o nome do arquivo destino independente do seu nome na origem.

 

Virtual Machine

As principais opções para Virtual Machine na CLI são:

  • Images: para ver as imagens disponíveis para novas VMs.
  • Machine-types: para ver os tamanho de VM disponíveis
  • Instances: para gerenciar suas instâncias (create, delete, stop, start, etc)
  • Snapshot: para gerenciar os snapshots de suas instâncias de VM.

Vamos ver como são os comandos para instâncias. Antes, você deve garantir que já adicionou ao menos uma chave SSH através do Console Magalu Cloud para que seu nome possa ser referenciado no comando.

 

Criando uma nova instância


Para criar uma instância de VM extra-small com sistema operacional Ubuntu você pode rodar o comando abaixo, assumindo que há uma chave SSH já cadastrada com o nome my_key.

mgc virtual-machine instances create –image.name cloud-ubuntu-23.04 –machine-
type cloud-bs1.xsmall –name "my_new_vm" –ssh-key-name "my_key"


Retorno:

  {
    "id": "2346a34d-af48-4d5e-888f-9802cffbb3db"
  }


Se o comando   virtual-machine instances create   executou com sucesso, ele retornará o ID da nova máquina virtual como mostra o exemplo acima.


Agora que temos uma máquina virtual disponível podem consultá-la diretamente através do comando virtual-machine instances get como mostra o exemplo abaixo.

mgc virtual-machine instances get 2346a34d-af48-4d5e-888f-9802cffbb3db


Retorno:

{
 "created_at": "2024-01-19T18:14:44Z",
 "id": "2346a34d-af48-4d5e-888f-9802cffbb3db",
 "image": {
  "id": "a051a382-5d1d-469f-8881-39cd2db2486a"
 },
 "machine_type": {
  "id": "45d57c50-61d3-46fc-992e-77f5605dd561"
 },
 "name": "my_new_vm",
 "network": {
  "ports": [
   {
    "id": "44a48b11-374d-417c-afd0-16771590cbc4"
   }
  ]
 },
 "ssh_key_name": "my_key",
 "state": "running",
 "status": "completed",
 "updated_at": "2024-01-19T18:15:33Z"
}


O retorno do comando mostra no conteúdo do JSON outros recursos associados à máquina virtual e que podem ser consultados pela CLI em outros comandos e utilizando seus identificadores listados acima.

 

Listando as instâncias existentes


Um dos comandos mais úteis na CLI da Magalu Cloud é o list , que está disponível em diversos recursos. Em Virtual Machine vamos utilizá-lo como mostra o exemplo abaixo para listar as instâncias já criadas na sua conta.

mgc virtual-machine instances list


Retorno:

 {
   "instances": [
      {
         "created_at": "2024-01-19T18:14:44Z",
         "id": "2346a34d-af48-4d5e-888f-9802cffbb3db",
         "image": {
         "id": "a051a382-5d1d-469f-8881-39cd2db2486a"
         },
         "machine_type": {
         "id": "45d57c50-61d3-46fc-992e-77f5605dd561"
         },
         "name": "my_new_vm",
         "network": {
         "ports": [
         {
            "id": "44a48b11-374d-417c-afd0-16771590cbc4"
         }
         ]
         },
         "ssh_key_name": "my_new_vm",
         "state": "running",
         "status": "completed",
         "updated_at": "2024-01-19T18:15:33Z"
      }
   ]
}


O retorno se dá com um array de objetos de instâncias. No caso acima só há uma máquina virtual, que foi criada durante este roteiro.

Esse artigo foi útil?

Não encontrou a resposta que precisava?

Enviar um Ticket

ou envie um email para help@magalu.cloud