Como ligar ao Hyperlift com o Hyperlift CLI

Hyperlift CLI é uma ferramenta de linha de comandos para gerir aplicações Hyperlift na plataforma Spaceship através do terminal. 

A ferramenta é open source aqui. Comunica com a Spaceship External API e autentica-se com uma chave e um segredo de API. Com a sua ajuda, podes fazer o seguinte:

• Ver e gerir a aplicação;

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

• Ver registos de execução e de compilação;

• Ver métricas da aplicação;

• Gerir variáveis de ambiente;

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

• Mantém a CLI atualizada.

A CLI comunica com a API Externa da Spaceship e usa uma chave e um segredo da API da Spaceship para autenticação. Por isso, as informações internas e administrativas permanecem ocultas, uma vez que a CLI acede diretamente aos serviços internos.

Neste artigo, vamos abordar:

1. Como instalar o Hyperlift CLI

2. Como criar credenciais de API

3. Como iniciar sessão no CLI

4. Como gerir uma aplicação Hyperlift através do CLI

   
   

1. Instalar o Hyperlift CLI

O Hyperlift CLI pode ser instalado em macOS, Windows e Linux. Consoante o teu SO, executa o comando de instalação. O script deteta automaticamente o teu sistema operativo e arquitetura, transfere a versão adequada, verifica-a e instala o comando hyperlift.

macOS

Se usares Homebrew, executa:

brew install nccloud/tap/hyperlift

Windows

Se usares Scoop, executa:

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

scoop install hyperlift

Linux ou macOS

Também podes usar o script de instalação:

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

Instalação manual

Em alternativa, transfere o arquivo para o teu sistema operativo a partir da página de versões do Hyperlift CLI, extrai-o e adiciona o executável hyperliftao PATH do teu sistema.

2. Criar credenciais de API

O Hyperlift CLI usa uma chave e um segredo da API Spaceship para autenticar os teus pedidos.

Para criar credenciais de API:

1. Inicia sessão na tua conta Spaceship.

2. Abre o API Manager.

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

   

   
   

4. Dá um nome à chave e seleciona as permissões necessárias para as ações que queres realizar:
   
   

   

   
   

5. Se selecionares o nível de acesso Custom access, existem três opções de acesso para o Hyperlift:
   

   

Uma chave apenas com o âmbito Read é suficiente se só precisares de ver as tuas aplicações, registos ou métricas. São necessários âmbitos adicionais para a gestão de aplicações e de variáveis de ambiente.

6. Copia a chave de API criada e o segredo, e guarda os detalhes.

Importante: O segredo da API é apresentado apenas uma vez quando crias as credenciais. Certifica-te de que o guardas em segurança.

Clica em Done:

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

3. Iniciar sessão no Hyperlift CLI

Depois de instalares o CLI e criares as tuas credenciais de API, executa:

hyperlift auth login

O CLI vai pedir-te que introduzas a tua chave e o teu segredo de API.

Após a autenticação bem-sucedida, a chave de API é armazenada no ficheiro de configuração do Hyperlift, enquanto o segredo da API é armazenado em segurança no porta-chaves do teu sistema operativo, quando disponível.

Para verificar o estado da tua sessão, executa:

hyperlift auth whoami

Para terminar sessão e remover as tuas credenciais armazenadas, executa:

hyperlift auth logout

Dica: Se receberes uma mensagem "Not logged in", executa novamente hyperlift auth login. Se receberes um erro 403, a tua chave de API pode não ter o âmbito necessário. 

Autenticação não interativa

Se precisares de autenticar a partir de um script, podes fornecer as credenciais usando opções da linha de comandos:

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

No entanto, usar --secret expõe o segredo como argumento da linha de comandos. Para maior segurança, podes passar o segredo através da entrada padrão:

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

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

Usa os comandos apps para ver e gerir as tuas aplicações Hyperlift.

Ver aplicações

Usa os comandos appspara ver e gerir as tuas aplicações Hyperlift.

Compilar uma aplicação

Para começar a compilar uma aplicação, executa:

hyperlift apps build <app-id>

Por predefinição, o comando devolve o controlo depois de a API aceitar o pedido de compilação.

Se quiseres que o CLI espere até a compilação estar concluída, adiciona a opção --wait:

hyperlift apps build <app-id> --wait

Também podes especificar quanto tempo o CLI deve esperar:

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

O tempo limite predefinido é de 10 minutos.

Inicia, para ou reinicia uma aplicação

Usa os seguintes comandos para gerir o estado da aplicação:

Por predefinição, estes comandos devolvem o controlo depois de a API aceitar o pedido. Adiciona --wait se quiseres que a CLI espere até a operação estar concluída.

Por exemplo:

hyperlift apps restart <app-id> --wait

Ver registos da aplicação

Podes usar o comando logs para ver os registos de execução e de compilação.

Nota: A opção --follow verifica periodicamente se existem novas entradas de registo. Não estabelece uma ligação de transmissão em direto.

Ver métricas da aplicação

Usa o comando metrics para monitorizar a utilização de recursos da tua aplicação. As métricas disponíveis incluem:

• Utilização de memória;

• Utilização de CPU;

• Taxa de receção da rede;

• Taxa de transmissão da rede;

• Utilização de armazenamento efémero;

• Utilização de armazenamento persistente.

Gerir variáveis de ambiente

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

Importante: Atualizar variáveis de ambiente reinicia a aplicação. Espera até que a aplicação volte a estar em execução antes de fazeres outra alteração a uma variável de ambiente.

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

Personalizar a saída do comando 

Por predefinição, os comandos do Hyperlift CLI apresentam informações num formato legível por humanos.

Se precisares de usar a saída em scripts ou noutras ferramentas, podes usar as seguintes opções.

Nota: As opções --json e --quiet não podem ser usadas em conjunto.

Atualizar o Hyperlift CLI

Obter ajuda por comando

Cada comando do Hyperlift CLI tem a sua própria informação 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, consulta o repositório do Hyperlift CLI.