Cómo conectarte a Hyperlift usando Hyperlift CLI

Hyperlift CLI es una herramienta de línea de comandos para administrar aplicaciones de Hyperlift en la plataforma Spaceship mediante la terminal. 

La herramienta es de código abierto aquí. Se comunica con la API Externa de Spaceship y se autentica con una clave y un secreto de API. Con su ayuda, puedes hacer lo siguiente:

• Ver y administrar la aplicación;

• Compilar, iniciar, detener y reiniciar la aplicación;

• Ver registros de ejecución y compilación;

• Ver métricas de la aplicación;

• Administrar variables de entorno;

• Usar salida JSON para scripts y automatización;

• Mantén el CLI actualizado.

El CLI se comunica con la API externa de Spaceship y usa una clave y un secreto de API de Spaceship para la autenticación. Por lo tanto, la información interna y administrativa se mantiene oculta, ya que el CLI accede directamente a los servicios internos.

En este artículo, cubriremos:

1. Cómo instalar Hyperlift CLI

2. Cómo crear credenciales de API

3. Cómo iniciar sesión en la CLI

4. Cómo administrar una aplicación de Hyperlift mediante CLI

   
   

1. Instala Hyperlift CLI

Hyperlift CLI se puede instalar en macOS, Windows y Linux. Según tu sistema operativo, ejecuta el comando de instalación. El script detecta automáticamente tu sistema operativo y arquitectura, descarga la versión adecuada, la verifica e instala el comando hyperlift.

macOS

Si usas Homebrew, ejecuta:

brew install nccloud/tap/hyperlift

Windows

Si usas Scoop, ejecuta:

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

scoop install hyperlift

Linux o macOS

También puedes usar el script de instalación:

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

Instalación manual

Como alternativa, descarga el archivo para tu sistema operativo desde la página de versiones de Hyperlift CLI, extráelo y agrega el ejecutable hyperliftal PATH de tu sistema.

2. Crea credenciales de API

Hyperlift CLI usa una clave y un secreto de API de Spaceship para autenticar tus solicitudes.

Para crear credenciales de API:

1. Inicia sesión en tu cuenta de Spaceship.

2. Abre API Manager.

3. Haz clic en el botón + New API key para crear una nueva clave:
   
   

   

   
   

4. Asigna un nombre a la clave y selecciona los permisos necesarios para las acciones que deseas realizar:
   
   

   

   
   

5. Si seleccionas el nivel Custom access, hay tres opciones de acceso para Hyperlift:
   

   

Una clave con solo el alcance Read es suficiente si solo necesitas ver tus aplicaciones, registros o métricas. Se requieren alcances adicionales para la administración de aplicaciones y las variables de entorno.

6. Copia la clave de API creada y el secreto, y guarda los detalles.

Importante: El secreto de API se muestra solo una vez cuando creas las credenciales. Asegúrate de guardarlo de forma segura.

Haz clic en Done:

7. La clave creada aparecerá en la lista del menú API Manager:

3. Inicia sesión en Hyperlift CLI

Después de instalar la CLI y crear tus credenciales de API, ejecuta:

hyperlift auth login

La CLI te pedirá que ingreses tu clave y secreto de API.

Después de una autenticación exitosa, la clave de API se almacena en el archivo de configuración de Hyperlift, mientras que el secreto de API se almacena de forma segura en el llavero de tu sistema operativo cuando está disponible.

Para comprobar el estado de tu inicio de sesión, ejecuta:

hyperlift auth whoami

Para cerrar sesión y eliminar tus credenciales almacenadas, ejecuta:

hyperlift auth logout

Consejo: Si recibes un mensaje de "Not logged in", ejecuta hyperlift auth login nuevamente. Si recibes un error 403, es posible que a tu clave de API le falte el alcance requerido. 

Autenticación no interactiva

Si necesitas autenticarte desde un script, puedes proporcionar las credenciales usando opciones de línea de comandos:

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

Sin embargo, usar --secret expone el secreto como un argumento de línea de comandos. Para mayor seguridad, puedes pasar el secreto a través de la entrada estándar:

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

4. Comandos básicos para administrar una aplicación de Hyperlift

Usa los comandos apps para ver y administrar tus aplicaciones de Hyperlift.

Ver aplicaciones

Usa los comandos appspara ver y administrar tus aplicaciones de Hyperlift.

Compilar una aplicación

Para comenzar a compilar una aplicación, ejecuta:

hyperlift apps build <app-id>

De forma predeterminada, el comando regresa después de que la API acepta la solicitud de compilación.

Si quieres que la CLI espere hasta que se complete la compilación, agrega la opción --wait:

hyperlift apps build <app-id> --wait

También puedes especificar cuánto tiempo debe esperar la CLI:

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

El tiempo de espera predeterminado es de 10 minutos.

Inicia, detén o reinicia una aplicación

Usa los siguientes comandos para administrar el estado de la aplicación:

De forma predeterminada, estos comandos regresan después de que la API acepta la solicitud. Agrega --wait si quieres que el CLI espere hasta que se complete la operación.

Por ejemplo:

hyperlift apps restart <app-id> --wait

Ver registros de la aplicación

Puedes usar el comando logs para ver tanto los registros de tiempo de ejecución como los de compilación.

Nota: La opción --follow comprueba periódicamente si hay nuevas entradas de registro. No establece una conexión de transmisión en vivo.

Ver métricas de la aplicación

Usa el comando metrics para supervisar el uso de recursos de tu aplicación. Las métricas disponibles incluyen:

• Uso de memoria;

• Uso de CPU;

• Tasa de recepción de red;

• Tasa de transmisión de red;

• Uso de almacenamiento efímero;

• Uso de almacenamiento persistente.

Administrar variables de entorno

Puedes usar los comandos envpara ver, agregar, actualizar y eliminar variables de entorno.

Importante: Actualizar las variables de entorno reinicia la aplicación. Espera hasta que la aplicación vuelva a estar en ejecución antes de hacer otro cambio en una variable de entorno.

Hyperlift usa la variable de entorno APPLICATION_PORT para determinar el puerto en el que la aplicación está disponible. Su valor predeterminado es 8080.

Personaliza la salida del comando 

De forma predeterminada, los comandos de Hyperlift CLI muestran la información en un formato legible para humanos.

Si necesitas usar la salida en scripts u otras herramientas, puedes usar las siguientes opciones.

Nota: Las opciones --json y --quiet no se pueden usar juntas.

Actualizar Hyperlift CLI

Obtener ayuda por comando

Cada comando de Hyperlift CLI tiene su propia información de ayuda.

La salida de ayuda incluye las opciones y argumentos disponibles para el comando seleccionado.

Para obtener la lista más reciente de comandos y detalles técnicos, consulta el repositorio de Hyperlift CLI.