gcloud compute

La herramienta de línea de comandos gcloud compute te permite administrar de manera sencilla los recursos de Compute Engine en un formato más amigable que con la API de Compute Engine.

La herramienta de gcloud forma parte del SDK de Cloud y es una herramienta de línea de comandos unificada que incluye funciones como actualizaciones in situ, autocompletado de declaraciones, ayuda amplia con estilo de página de manual, integración con el SDK de Google Cloud y formatos de resultados legibles y procesables.

Si nunca usaste Compute Engine, comienza con una de las guías de inicio rápido.

Instala o actualiza gcloud compute

Configura gcloud compute

Compute Engine usa OAuth2 para autenticar y autorizar el acceso. Antes de poder usar gcloud compute, debes autorizar el SDK de Cloud en tu nombre para acceder al proyecto y adquirir un token de autenticación.

Si usas la herramienta de línea de comandos de gcloud por primera vez, gcloud usa la configuración default de forma automática. En la mayoría de los casos, solo necesitas la configuración default.

  1. Ejecuta gcloud init para iniciar el proceso de autenticación. Presiona Intro cuando se te solicite.

    El comando imprime una URL y, luego, intenta abrir una ventana del navegador para solicitar acceso al proyecto. Si se puede abrir una ventana del navegador, verás el siguiente resultado:

    gcloud init
    
    Welcome! This command will take you through the configuration of gcloud.
    
    Your current configuration has been set to: [default]
    
    ...
    
    To continue, you must login. Would you like to login (Y/n)?  y
    
    Your browser has been opened to visit:
    
    https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.co%2
    Fauth%2Fappengine.admin+https%3A%2F%2...

    Si el SDK de Cloud detecta que no se puede abrir un navegador (p. ej., si estás trabajando en una máquina remota), verás el siguiente resultado. O bien, si estás trabajando en una máquina local y el navegador no carga de forma automática la URL, vuelve a ejecutar el comando gcloud init con el marcador --console-only.

    gcloud init --console-only
    

    Copia la URL de autenticación y pégala en un navegador. Luego, vuelve a pegar el código de verificación en la terminal.

    Go to the following link in your browser:
    
    https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.co%2
    Fauth%2Fappengine.admin+https%3A%2F%2...
    
    Enter verification code:
  2. Otorga acceso.

    En la ventana del navegador, revisa los permisos de la aplicación y haz clic en Aceptar cuando estés listo. Si estás trabajando en una máquina remota o usaste el marcador --console-only, copia y pega el código que se muestra en la línea de comandos después de Ingresar código de verificación. De lo contrario, el código se envía de forma automática a la herramienta de línea de comandos.

  3. Elige las credenciales para esta configuración.

    Después de configurar las credenciales, gcloud solicita un proyecto predeterminado para esta configuración. Selecciona un ID del proyecto de la lista.

    Después de establecer esta propiedad, todos los comandos gcloud compute usarán el ID del proyecto predeterminado, a menos que lo anules con el marcador --project o configures la variable de entorno CLOUDSDK_CORE_PROJECT. Si no configuras un proyecto predeterminado o una variable de entorno, debes incluir un marcador --project en cada comando gcloud compute que ejecutes.

Se requiere una zona o región para trabajar con recursos que pertenecen a una zona o región (por ejemplo, cada vez que manipulas una instancia de máquina virtual, debes especificar una zona). Cuando se configura una zona y región predeterminadas, gcloud puede inferir esta información sin requerir que la proporciones con cada solicitud. Siempre puedes anular o cambiar esta configuración predeterminada de forma manual.

Para obtener más información, consulta la sección establece las propiedades predeterminadas.

Usa las configuraciones

gcloud usa el concepto de configurations a fin de que puedas administrar las credenciales para diferentes cuentas. Cada configuración contiene la cuenta de correo electrónico para realizar la autenticación y la configuración específica, como el ID del proyecto predeterminado, la configuración de zona predeterminada, etc. gcloud viene instalado de forma automática con una configuración default. Esta es la configuración cuyas credenciales se usarán para autenticarse en los servicios de Google Cloud Platform.

Para la mayoría de los usuarios, basta con usar la configuración default. Si tienes casos prácticos que requieren una alternancia entre cuentas, puedes crear más configuraciones entre las cuales alternar.

Consulta gcloud topic configurations para obtener información detallada sobre cómo usar las configuraciones.

Establece las propiedades predeterminadas

El servidor de metadatos contiene información de metadatos sobre un proyecto, incluido el ID del proyecto, el nombre del proyecto, etc. Puedes consultar el servidor de metadatos para obtener y usar la información sobre el proyecto.

Si especificas una región y zona predeterminadas para el proyecto, Compute Engine establece estos valores en el servidor de metadatos del proyecto.

Las regiones y zonas predeterminadas se establecen con los siguientes valores:

  • google-compute-default-zone
  • google-compute-default-region

Para ver cuál es la configuración predeterminada de región y zona, ejecuta el siguiente comando de gcloud:

gcloud compute project-info describe --project [PROJECT_ID]

donde [PROJECT_ID] es el ID del proyecto.

Busca las siguientes claves y valores de metadatos en la respuesta:

- key: google-compute-default-region
  value: ...
- key: google-compute-default-zone
  value: ..

Si la respuesta no contiene las claves ni los valores google-compute-default-region y google-compute-default-zone, no se estableció ninguna zona o región predeterminada.

  • Si no se establece ningún valor predeterminado, gcloud solicitará una región y zona con cada solicitud.
  • Si no se establece ningún valor predeterminado, gcloud usará de forma automática el valor predeterminado de todas las solicitudes de gcloud que realices, a menos que anules la configuración predeterminada de forma manual.

Para cambiar, establecer o anular las propiedades predeterminadas, usa los siguientes métodos.

Cambia la zona y región predeterminadas en el servidor de metadatos

Puedes cambiar la zona y región predeterminadas en el servidor de metadatos si realizas una solicitud al servidor de metadatos. Por ejemplo:

gcloud compute project-info add-metadata \
    --metadata google-compute-default-region=europe-west1,google-compute-default-zone=europe-west1-b

La herramienta de línea de comandos de gcloud solo recoge los cambios nuevos de zona y región predeterminadas una vez que vuelves a ejecutar el comando gcloud init. Después de actualizar los metadatos predeterminados, ejecuta gcloud init para volver a inicializar la configuración default.

Establece la zona y región predeterminadas en el cliente local

Puedes elegir una zona o región diferente de forma manual sin tener que actualizar el servidor de metadatos si estableces estas propiedades de forma local en el cliente de gcloud.

Primero, asegúrate de usar la configuración para la que deseas establecer estas propiedades. Cada configuración tiene sus propios parámetros; para alternar entre las configuraciones, ejecuta el siguiente comando:

gcloud config configurations activate CONFIGURATION_NAME

Luego, para establecer una propiedad de zona o región en el cliente, ejecuta el siguiente comando:

gcloud config set compute/zone ZONE
gcloud config set compute/region REGION

Para quitar una propiedad predeterminada por completo, usa el comando unset.

gcloud config unset compute/zone
gcloud config unset compute/region

Ten en cuenta que, si quitas la propiedad predeterminada por completo, gcloud solicitará una zona o región para cada comando que ejecutes.

Establece los valores predeterminados en las variables de entorno

Puedes establecer las variables de entorno que proporcionen valores a los comandos gcloud compute. Las variables de entorno anulan las propiedades predeterminadas que estableces con los comandos gcloud config, pero no anulan los marcadores explícitos, como --zone o --region.

Linux/macOS
Usa el comando export para establecer las variables de zona y región.
$ export CLOUDSDK_COMPUTE_ZONE=ZONE
$ export CLOUDSDK_COMPUTE_REGION=REGION
Para que las variables de entorno sean permanentes, incluye estos comandos en el archivo ~/.bashrc y reinicia la terminal.
Windows
Usa el comando set para establecer las variables de zona y región.
C:\> set CLOUDSDK_COMPUTE_ZONE=ZONE
C:\> set CLOUDSDK_COMPUTE_REGION=REGION

Puedes anular las variables de entorno si incluyes los marcadores específicos --zone o --region con los comandos.

Establece los valores en cada solicitud

Puedes anular las propiedades predeterminadas si incluyes los marcadores específicos --zone o --region con cada uno de los comandos. Por ejemplo:

gcloud compute instances create example-instance --zone us-central1-f

Estos marcadores solo funcionan para el comando único con el que lo usas. Los marcadores no cambian ninguna configuración predeterminada que tengas, pero la anulan para esa solicitud.

Orden de prioridad de las propiedades predeterminadas

La herramienta de línea de comandos de gcloud evalúa las propiedades predeterminadas en el siguiente orden para cada configuración:

  • Si proporcionas un marcador explícito --zone, --region o --project, se anulan las demás opciones de configuración para esa única solicitud.
  • Si las propiedades de zona y región predeterminadas se definen solo en el servidor de metadatos, la herramienta de línea de comandos de gcloud establece el cliente local de gcloud para estas propiedades cuando ejecutas gcloud init. La herramienta te solicitará la zona en solicitudes posteriores.
  • Si las propiedades de zona y región predeterminadas se definen tanto en el servidor de metadatos como en el cliente local para esa configuración, la herramienta usa las propiedades predeterminadas en el cliente local.
  • Si las propiedades de zona y región predeterminadas se definen en el servidor de metadatos, el cliente local y las variables de entorno, la herramienta usa las propiedades predeterminadas en las variables de entorno sin importar la configuración que estés utilizando.

Comandos comunes de gcloud compute

A continuación, se muestran ejemplos de tareas comunes cuando se trabaja con instancias. Para obtener más detalles sobre cómo trabajar con instancias en general, consulta la sección sobre instancias.

Crea instancias

Usa el comando instances create para crear una instancia nueva. Por ejemplo, el siguiente comando crea una instancia llamada “my-instance” en la zona “us-central1-a”.

gcloud compute instances create my-instance

Si omites el marcador --zone, gcloud puede inferir la zona que deseas según las propiedades predeterminadas.

Si en el comando “create” no se especifican otras configuraciones necesarias de la instancia, como el tipo de máquina y la imagen, se establecerán los valores predeterminados. Puedes consultar los valores predeterminados si solicitas que se muestre la ayuda del comando create command:

gcloud compute instances create --help

Muestra la lista de instancias

Existen varias formas de mostrar una lista de instancias con el comando instances list. Puedes crear una tabla legible con el siguiente comando:

gcloud compute instances list

Puedes usar expresiones regulares para reducir la lista de instancias que se muestran por nombre. Por ejemplo, el siguiente comando muestra todas las instancias cuyos nombres comienzan con “my-”.

gcloud compute instances list --filter="name ~ ^my-.*"

Para obtener más información sobre cómo filtrar y mostrar una lista de recursos, consulta la sección sobre cómo recuperar los recursos.

Para mostrar información detallada sobre una instancia, usa el comando instances describe. Por ejemplo, el siguiente comando muestra información sobre la instancia “my-instance”.

gcloud compute instances describe my-instance --zone us-central1-a

El comando anterior muestra los resultados en formato YAML. Puedes usar el marcador --format para cambiar el modo en que se muestran los resultados. Para ver más ejemplos sobre cómo obtener y mostrar una lista de recursos, incluidas las instancias, consulta la sección sobre cómo recuperar los recursos.

Conéctate a las instancias

gcloud compute facilita la conexión a las instancias. Los comandos gcloud compute ssh y gcloud compute scp proporcionan wrappers para SSH y SCP que se encargan de la autenticación y la asignación del nombre de la instancia a la dirección IP.

Por ejemplo, para establecer una conexión mediante SSH con “my-instance” en la zona “us-central1-a”, puedes usar el siguiente comando:

gcloud compute ssh my-instance --zone us-central1-a

Para copiar el archivo local “file-1” en “my-instance”, que está en la zona “us-central1-a”, puedes usar el siguiente comando:

gcloud compute scp ~/file-1 my-instance:~/remote-destination --zone us-central1-a

También puedes usar el comando scp para copiar los archivos de una instancia en la máquina local. Por ejemplo, si quieres crear una copia local de “file-1”, que se encuentra en la instancia “my-instance” y en la zona “us-central1-a”, puedes usar el siguiente comando:

gcloud compute scp my-instance:~/file-1 ~/local-destination --zone us-central1-a

De forma predeterminada, los comandos gcloud compute ssh y gcloud compute scp usan el archivo de claves privadas ubicado en “~/.ssh/google_compute_engine”. Si no quieres usar este archivo de claves privadas, puedes especificar la archivo de claves distinto especificando una ubicación diferente con el marcador --ssh-key-file. Por ejemplo, puede que quieras usar una clave privada existente o claves privadas distintas en proyectos distintos.

Usa programas basados en SSH de manera directa

Si prefieres usar ssh y scp de manera directa, gcloud compute puede generar un archivo de configuración de SSH que contiene los alias de host de las instancias con la configuración de autenticación. Para ello, ejecuta el siguiente comando:

gcloud compute config-ssh

A continuación, se muestra un ejemplo de cómo agregar un alias al archivo de configuración de SSH (~/.ssh/config):

Host my-instance.us-central1-a.myproject
HostName 107.178.220.224
IdentityFile ~/.ssh/google_compute_engine
UserKnownHostsFile=/dev/null
CheckHostIP=no
StrictHostKeyChecking=no

Puedes especificar un archivo de configuración de SSH alternativo para cada usuario con el marcador --ssh-config-file.

Debes volver a ejecutar el comando config-ssh cada vez que agregues o quites una instancia.

Después de actualizar los archivos de configuración de SSH con el comando config-ssh, puedes usar cualquier programa basado en SSH para acceder a las instancias. Por ejemplo, en el caso de la instancia llamada “my-instance”, que se encuentra en la zona “us-central1-a” y en el proyecto “myproject”, puedes usar el cliente SSH OpenSSH de la siguiente manera:

$ ssh my-instance.us-central1-a.myproject

Para hacer una copia local del archivo “file-1” de la instancia, puedes usar el cliente scp de la siguiente manera:

$ scp my-instance.us-central1-a.myproject:~/file-1 .

Trabaja con metadatos

Puedes configurar los metadatos personalizados para una instancia o un proyecto fuera de los metadatos que define el servidor. Esto resulta útil para pasar los valores arbitrarios al proyecto o la instancia que el código puede consultar en la instancia. En esta sección, se muestran algunas operaciones de metadatos comunes. Para obtener información más detallada sobre cómo trabajar con metadatos, consulta la sección sobre cómo guardar y recuperar los metadatos.

Agrega y quita los metadatos de instancias

Puedes configurar los metadatos de instancias con gcloud compute cuando creas una instancia con el comando create o con una instancia existente con los comandos add-metadata y remove-metadata. Los metadatos se especifican como pares clave-valor separados por un signo igual (“=”) con el marcador --metadata. O bien, los metadatos se pueden leer desde un archivo local con el marcador --metadata-from-file.

Por ejemplo, para agregar las claves de metadatos personalizadas “role”, “unique-id” y “build-num” a una instancia existente llamada “my-instance” que se encuentra en la zona “us-central1-a”, puedes usar el siguiente comando:

gcloud compute instances add-metadata my-instance \
    --zone us-central1-a \
    --metadata role=worker unique-id=1234 build-num=4.32

Para quitar las claves de metadatos personalizadas “role” y “unique-id”, puedes usar el siguiente comando:

gcloud compute instances remove-metadata my-instance \
    --zone us-central1-a \
    --keys role unique-id

Después de agregar y quitar los metadatos de una instancia existente, puedes ejecutar el siguiente comando para ver los cambios:

gcloud compute instances describe my-instance --zone us-central1-a
...
metadata:
  fingerprint: eU448B6JGQw=
  items:
  - key: build-num
    value: '4.32'
  kind: compute#metadata
...

Para cambiar los metadatos existentes o agregar metadatos nuevos, usa el comando add-metadata. Las actualizaciones de metadatos de instancias son aditivas. Esto significa que solo debes especificar las claves de metadatos que deseas agregar o cambiar. Si especificas una clave existente, el valor de la clave se actualizará con el valor nuevo.

En las imágenes que tienen instaladas las herramientas de Compute Engine, hay dos claves de metadatos que se reservan para la funcionalidad de secuencias de comandos de inicio:

  • startup-script: indica el contenido de la secuencia de comandos que se ejecuta cuando se inicia la instancia. En un contenido de secuencia de comandos más extenso, puedes usar el marcador --metadata-from-file para pasar una ruta de acceso a un archivo que contiene el contenido de la secuencia de comandos.
  • startup-script-url: indica que se ejecuta una secuencia de comandos en la ubicación de acceso público especificada cuando se inicia la instancia.

Por ejemplo, para crear una instancia llamada “my-instance” en la zona “us-central1-a” con el contenido de la secuencia de comandos de inicio especificado con el marcador --metadata, puedes usar el siguiente comando:

gcloud compute instances create my-instance --zone us-central1-a \
    --metadata startup-script="echo 'hello world'"

Si estableces una conexión mediante SSH con “my-instance” y verificas el registro del sistema (/var/log/syslog), verás el resultado de la secuencia de comandos de inicio.

Con una instancia existente llamada “my-instance”, puedes agregar la siguiente secuencia de comandos de inicio desde un archivo local con el marcador --metadata-from-file:

gcloud compute instances add-metadata my-instance \
    --metadata-from-file startup-script=/local/path/to/script/startup

En este ejemplo, la secuencia de comandos de inicio se ejecuta cuando se reinicia la instancia; es decir, cuando usas el comando instances reset gcloud compute.

Agrega y quita metadatos a nivel de proyecto

Todas las instancias de un proyecto tienen acceso a los metadatos a nivel de proyecto. De forma predeterminada, un proyecto reservó los metadatos a nivel de proyecto. También puedes agregar y quitar los metadatos personalizados a nivel de proyecto. Al igual que los metadatos de instancias, las actualizaciones de metadatos del proyecto son aditivas. Esto significa que solo debes especificar las claves de metadatos que deseas agregar o cambiar. Si especificas una clave existente, el valor de la clave se actualizará con el valor nuevo.

Para ver los metadatos existentes a nivel de proyecto, usa el comando project-info describe:

gcloud compute project-info describe

El siguiente comando agrega dos partes de metadatos de todo el proyecto.

gcloud compute project-info add-metadata \
    --metadata-from-file startup-script=/local/path/to/script
    --metadata startup-id=1234

Ten en cuenta que la clave startup-script está reservada y significa que el contenido del archivo local especificado se ejecutará cuando se inicien las instancias.

Para quitar las dos partes de metadatos que acabas de agregar, usa el siguiente comando:

gcloud compute project-info remove-metadata --keys startup-script startup-id

Borra instancias

Si quieres borrar la instancia llamada “my-instance” que se encuentra en la zona “us-central1-a”, puedes usar el comando instances delete:

gcloud compute instances delete my-instance --zone us-central1-a

Cuando creas una instancia, también se crea un disco persistente. Este disco usará tu cuota de discos persistentes y generará cargos mensuales asociados. De forma predeterminada, cuando se usa el comando instances delete para quitar una instancia, también se quita el disco persistente asociado a esa instancia. Para anular este comportamiento, tienes dos opciones:

  • Usar el marcador --keep-disks del comando instances delete.
  • Inhabilitar el borrado automático en la configuración del disco. Después de crear una instancia, y en cualquier momento antes de borrarla, puedes usar el comando instances set-disk-auto-delete para conservar el disco persistente. Ten en cuenta que el marcador --delete-disks del comando instances delete borrará los discos sin importar la configuración de borrado automático.

Para obtener más información, consulta la sección sobre cómo configurar el estado de borrado automático de un disco persistente.

Enumera operaciones

Las operaciones son un registro de los cambios en los recursos de Compute Engine. Para obtener una lista de todas las operaciones de un proyecto, puedes usar el comando operations list:

gcloud compute operations list

Las operaciones tienen alcances que se pueden usar para reducir las operaciones que se muestran en una solicitud de lista. Por ejemplo, puedes usar --global, --zones y --regions para definir mejor los resultados. El siguiente comando solo muestra las operaciones en las zonas “us-central1-a” y “us-central1-b”:

gcloud compute operations list --filter="zone:(us-central1-a us-central1-b)"

Para ver más ejemplos de cómo obtener y mostrar una lista de recursos, incluidas las operaciones, consulta la sección sobre cómo recuperar los recursos.

Obtén páginas de ayuda

Los siguientes comandos te muestran cómo acceder a los diferentes tipos de ayuda, desde la ayuda general sobre el comando gcloud compute hasta la ayuda específica sobre un grupo de recursos (instances) o un comando (create). La ayuda completa de todos los recursos y comandos sigue este patrón:

gcloud compute --help
gcloud compute instances --help
gcloud compute instances create --help

Puedes obtener ayuda rápidamente si usas el marcador -h en vez de --help. También puedes consultar la ayuda completa en la referencia del SDK de Cloud.

Si deseas consultar la ayuda completa de los comandos específicos para configurar la herramienta de gcloud, ejecuta el siguiente comando:

gcloud topic TOPIC

TOPIC es el tema correspondiente con el que necesitas ayuda. Para obtener una lista de temas de ayuda, consulta la documentación de referencia de gcloud topic.

Próximos pasos

¡Eso es todo! Ahora puedes comenzar a usar la herramienta de gcloud compute por tu cuenta. A continuación, le ofrecemos algunas ideas para comenzar:

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Documentación de Compute Engine