Como se conectar ao Hyperlift usando a Hyperlift CLI

Hyperlift CLI é uma ferramenta de linha de comando para gerenciar aplicações Hyperlift na plataforma Spaceship via terminal. 

A ferramenta é open source aqui. Ela se comunica com a API Externa da Spaceship e autentica com uma chave e um segredo de API. Com a ajuda dela, você pode fazer o seguinte:

• Ver e gerenciar a aplicação;

• Fazer build, iniciar, parar e reiniciar a aplicação;

• Ver logs de runtime e de build;

• Ver métricas da aplicação;

• Gerenciar variáveis de ambiente;

• Usar saída JSON para scripts e automação;

• Mantenha a CLI atualizada.

A CLI se comunica com a API Externa da Spaceship e usa uma chave e um segredo da API da Spaceship para autenticação. Portanto, as informações internas e administrativas permanecem ocultas, já que a CLI acessa os serviços internos diretamente.

Neste artigo, vamos abordar:

1. Como instalar o Hyperlift CLI

2. Como criar credenciais de API

3. Como fazer login no CLI

4. Como gerenciar uma aplicação Hyperlift via CLI

   
   

1. Instale o Hyperlift CLI

O Hyperlift CLI pode ser instalado no macOS, Windows e Linux. Dependendo do seu SO, execute o comando de instalação. O script detecta automaticamente seu sistema operacional e arquitetura, baixa a versão apropriada, verifica-a e instala o comando hyperlift.

macOS

Se você usa Homebrew, execute:

brew install nccloud/tap/hyperlift

Windows

Se você usa Scoop, execute:

scoop bucket add nccloud https://github.com/NCCloud/scoop-bucket

scoop install hyperlift

Linux ou macOS

Você também pode usar o script de instalação:

curl -fsSL https://raw.githubusercontent.com/NCCloud/hyperlift-cli/main/scripts/install.sh | sh

Instalação manual

Como alternativa, baixe o arquivo compactado para seu sistema operacional napágina de Releases do Hyperlift CLI, extraia-o e adicione o executável hyperliftao PATH do seu sistema.

2. Crie credenciais de API

O Hyperlift CLI usa uma chave e um segredo de API da Spaceship para autenticar suas solicitações.

Para criar credenciais de API:

1. Faça login na sua conta Spaceship.

2. Abra o API Manager.

3. Clique no botão + New API key para criar uma nova chave:
   
   

   

   
   

4. Dê um nome à chave e selecione as permissões necessárias para as ações que você deseja realizar:
   
   

   

   
   

5. Se você selecionar o nível de acesso Custom access, há três opções de acesso para o Hyperlift:
   

   

Uma chave com apenas o escopo Leitura é suficiente se você só precisa ver suas aplicações, logs ou métricas. Escopos adicionais são necessários para gerenciamento de aplicações e variáveis de ambiente.

6. Copie a chave de API criada e o segredo, e salve os detalhes.

Importante: O segredo da API é exibido apenas uma vez quando você cria as credenciais. Certifique-se de salvá-lo com segurança.

Clique em Done:

7. A chave criada será listada no menu API Manager:

3. Faça login no Hyperlift CLI

Após instalar o CLI e criar suas credenciais de API, execute:

hyperlift auth login

O CLI solicitará que você insira sua chave e seu segredo de API.

Após a autenticação bem-sucedida, a chave de API é armazenada no arquivo de configuração do Hyperlift, enquanto o segredo da API é armazenado com segurança no chaveiro do seu sistema operacional, quando disponível.

Para verificar seu status de login, execute:

hyperlift auth whoami

Para sair e remover suas credenciais armazenadas, execute:

hyperlift auth logout

Dica: Se você receber a mensagem "Not logged in", execute hyperlift auth login novamente. Se você receber um erro 403, sua chave de API pode não ter o escopo necessário. 

Autenticação não interativa

Se você precisar autenticar a partir de um script, poderá fornecer as credenciais usando opções de linha de comando:

hyperlift auth login --key "$KEY" --secret "$SECRET"

No entanto, usar --secret expõe o segredo como um argumento de linha de comando. Para maior segurança, você pode passar o segredo pela entrada padrão:

printf '%s' "$SECRET" | hyperlift auth login --key "$KEY" --with-stdin

4. Comandos básicos para gerenciar uma aplicação Hyperlift

Use os comandos apps para ver e gerenciar suas aplicações Hyperlift.

Ver aplicações

Use os comandos appspara ver e gerenciar suas aplicações Hyperlift.

Fazer build de uma aplicação

Para começar o build de uma aplicação, execute:

hyperlift apps build <app-id>

Por padrão, o comando retorna depois que a API aceita a solicitação de build.

Se você quiser que o CLI aguarde até que o build seja concluído, adicione a opção --wait:

hyperlift apps build <app-id> --wait

Você também pode especificar por quanto tempo o CLI deve aguardar:

hyperlift apps build <app-id> --wait --timeout 15m

O tempo limite padrão é de 10 minutos.

Inicie, pare ou reinicie um aplicativo

Use os seguintes comandos para gerenciar o status do aplicativo:

Por padrão, esses comandos retornam depois que a API aceita a solicitação. Adicione --wait se quiser que a CLI aguarde até que a operação seja concluída.

Por exemplo:

hyperlift apps restart <app-id> --wait

Ver logs do aplicativo

Você pode usar o comando logs para ver os logs de tempo de execução e de compilação.

Observação: A opção --follow verifica periodicamente novas entradas de log. Ela não estabelece uma conexão de streaming ao vivo.

Ver métricas da aplicação

Use o comando metrics para monitorar o uso de recursos da sua aplicação. As métricas disponíveis incluem:

• Uso de memória;

• Uso de CPU;

• Taxa de recebimento de rede;

• Taxa de transmissão de rede;

• Uso de armazenamento efêmero;

• Uso de armazenamento persistente.

Gerenciar variáveis de ambiente

Você pode usar os comandos envpara ver, adicionar, atualizar e remover variáveis de ambiente.

Importante: Atualizar variáveis de ambiente reinicia a aplicação. Aguarde até que a aplicação esteja em execução novamente antes de fazer outra alteração em variável de ambiente.

O Hyperlift usa a variável de ambiente APPLICATION_PORT para determinar a porta na qual a aplicação está disponível. O valor padrão é 8080.

Personalizar a saída do comando 

Por padrão, os comandos do Hyperlift CLI exibem informações em um formato legível por humanos.

Se você precisar usar a saída em scripts ou outras ferramentas, poderá usar as seguintes opções.

Observação: As opções --json e --quiet não podem ser usadas juntas.

Atualizar o Hyperlift CLI

Obter ajuda por comando

Cada comando do Hyperlift CLI tem suas próprias informações de ajuda.

A saída da ajuda inclui as opções e os argumentos disponíveis para o comando selecionado.

Para a lista de comandos mais recente e detalhes técnicos, consulte orepositório do Hyperlift CLI.