gcloud compute


La herramienta de línea de comandos de gcloud te permite administrar los recursos de Compute Engine mediante el grupo de comandos gcloud compute. gcloud compute es una alternativa al uso de 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 el autocompletado de declaraciones, la actualización local, la ayuda de la línea de comandos, los formatos de resultado legibles y procesables, además de la integración con el SDK de Cloud.

Si nunca usaste Compute Engine, comienza con la guía de inicio rápido de Linux o la guía de inicio rápido de Windows.

Antes de comenzar

  • Si deseas ejecutar gcloud compute en un símbolo del sistema, instala, actualiza e inicializa el SDK de Cloud.
  • Si no tienes un símbolo del sistema disponible, intenta usar gcloud compute en Cloud Shell. Cloud Shell se instala, actualiza e inicializa de manera automática con el SDK de Cloud más reciente.

Usa las opciones de configuración

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

Para la mayoría de los usuarios, basta con usar la configuración default. Si tienes casos de uso en los que debes cambiar de cuenta, puedes crear más configuraciones entre las que alternar.

Propiedades predeterminadas

El servidor de metadatos contiene información de metadatos sobre un proyecto, incluido el ID del proyecto, el nombre del proyecto, etcétera. Puedes usar la herramienta de línea de comandos de gcloud para consultar el servidor de metadatos a fin de obtener y usar la información del proyecto.

Visualiza las propiedades predeterminadas

Para ver cuáles son las propiedades predeterminadas, ejecuta el siguiente comando mediante la herramienta de línea de comandos de gcloud. Reemplaza PROJECT_ID por el ID del proyecto.

gcloud compute project-info describe --project PROJECT_ID

Visualiza la región y la zona predeterminadas

Para ver cuál es la configuración de la región y la zona predeterminadas, ejecuta los siguientes comandos:

gcloud config get-value compute/zone
gcloud config get-value compute/region

Si las respuestas google-compute-default-region o google-compute-default-zone son (unset), significa que no se estableció ninguna zona o región predeterminada.

  • Si no hay ningún valor predeterminado, la herramienta de gcloud te solicitará una región y una zona con cada solicitud.

  • Si existe un valor predeterminado, la herramienta de gcloud usa de forma automática el valor predeterminado para todas las solicitudes de la herramienta de gcloud que realices, a menos que anules de forma manual la configuración predeterminada.

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

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

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

Establece las regiones y las zonas predeterminadas mediante los siguientes comandos:

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

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 detecta los cambios predeterminados de zona y región nuevos después de que vuelves a ejecutar el comando gcloud init. Después de actualizar tus metadatos predeterminados, ejecuta gcloud init para reiniciar tu configuración default.

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

Puedes elegir de forma manual una zona o una región diferente sin actualizar el servidor de metadatos si configuras estas propiedades de forma local en tu 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 los parámetros de configuración, 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, 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, la herramienta de gcloud solicitará una zona o una región para cada comando que ejecutes.

Establece los valores predeterminados en las variables de entorno

Puedes establecer 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 las marcas explícitas como --zone o --region.

Linux/macOS
Usa el comando export para establecer las variables del proyecto, la zona y la región.
export CLOUDSDK_CORE_PROJECT=PROJECT
export CLOUDSDK_COMPUTE_ZONE=ZONE
export CLOUDSDK_COMPUTE_REGION=REGION
Para hacer que estas 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 del proyecto, zona y la región.
C:\> set CLOUDSDK_CORE_PROJECT=PROJECT
C:\> set CLOUDSDK_COMPUTE_ZONE=ZONE
C:\> set CLOUDSDK_COMPUTE_REGION=REGION

Puedes anular las variables de entorno si incluyes marcas específicas --zone o --region en tus comandos.

Establece los valores en cada solicitud

Puedes anular las propiedades predeterminadas si incluyes marcas --zone o --region específicas con cada uno de tus comandos. Como en el siguiente 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 una marca --zone, --region o --project explícita, esta anula todas los demás parámetros de configuración de esa única solicitud.
  • Si las propiedades de la región y la zona predeterminadas se definen solo en el servidor de metadatos, la herramienta de línea de comandos de gcloud configura el cliente local de gcloud con estas propiedades cuando ejecutas gcloud init. La herramienta de gcloud te solicitará la zona en solicitudes posteriores.
  • Si las propiedades de la zona y la región predeterminadas se definen tanto en el servidor de metadatos como en el cliente local para esa configuración, la herramienta de gcloud usa las propiedades predeterminadas en el cliente local.
  • Si las propiedades de la zona y la región predeterminadas se definen en el servidor de metadatos, el cliente local y las variables de entorno, la herramienta de gcloud usa las propiedades predeterminadas en las variables de entorno sin importar la configuración que uses.

Comandos de gcloud compute comunes

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 Instancias.

Crea instancias

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

gcloud compute instances create my-instance

Si omites la marca --zone, la herramienta de gcloud puede inferir la zona deseada en función de las propiedades predeterminadas.

Si en el comando create no se especifican otras configuraciones necesarias sobre la instancia, como el tipo de máquina y la imagen, se establecerán los valores predeterminados. Puedes ver los valores predeterminados si muestras la ayuda para create command:

gcloud compute instances create --help

Muestra la lista de instancias

Existen varias formas de enumerar tus 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 detalles de 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 la marca --format para cambiar cómo se muestran los resultados. Para ver más ejemplos sobre cómo obtener y mostrar una lista de recursos, incluidas las instancias, consulta Recupera recursos.

Conéctate a instancias

gcloud compute facilita la conexión con tus 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 instancia de 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

El comando scp también se puede usar para copiar archivos de una instancia a tu 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 deseas usar este archivo de claves, puedes especificar un archivo de claves diferente al determinar una ubicación diferente con la marca --ssh-key-file. Por ejemplo, tal vez 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 forma directa, gcloud compute puede generar un archivo de configuración de SSH que contiene los alias de host para tus instancias con la configuración de autenticación. Para ello, ejecuta el siguiente comando:

gcloud compute config-ssh

Este es un ejemplo de un alias agregado 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 por usuario con la marca --ssh-config-file.

Cada vez que agregas o quitas una instancia, debes volver a ejecutar el comando config-ssh.

Después de actualizar tus archivos de configuración de SSH con el comando config-ssh, puedes usar cualquier programa basado en SSH para acceder a tus 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 más información sobre cómo trabajar con metadatos, consulta Almacena y recupera metadatos.

Agrega y quita los metadatos de instancias

Puedes configurar metadatos de instancia con gcloud compute cuando creas una instancia mediante el comando create, o con una instancia existente mediante los comandos add-metadata y remove-metadata. Los metadatos se especifican como pares clave-valor separados con un signo igual (“=”) mediante la marca --metadata. O bien, los metadatos se pueden leer desde un archivo local con la marca --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 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 herramientas de Compute Engine, hay dos claves de metadatos que se reservan para la función de creación de secuencias de comandos de inicio:

  • startup-script: Indica el contenido de la secuencia de comandos que se ejecuta cuando se inicia la instancia. Si este es muy extenso, puedes usar la marca --metadata-from-file para indicar una ruta a un archivo que contiene el contenido de la secuencia de comandos.
  • startup-script-url: Indica que, cuando se inicia la instancia, se ejecuta una secuencia de comandos en la ubicación especificada de acceso público.

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 la marca --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 la instancia se reinicia, por ejemplo, cuando usas gcloud computeinstances reset.

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 fragmentos de metadatos a 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 los dos fragmentos 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:

  • Usa la marca --keep-disks del comando instances delete.
  • Inhabilita la eliminación automática 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 la marca --delete-disks del comando instances delete borrará los discos sin importar la configuración de eliminación automática.

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 en un proyecto, puedes usar el comando operations list:

gcloud compute operations list

Las operaciones tienen distintos alcances que se pueden usar para limitar las operaciones mostradas en una solicitud de lista. Por ejemplo, puedes usar las marcas --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 muestran cómo acceder a diferentes tipos de ayuda, desde ayuda general con el comando gcloud compute hasta ayuda específica con un grupo de recursos (instances) o un comando (create). La ayuda completa para todos los recursos y comandos sigue este patrón:

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

Puedes obtener ayuda con rapidez mediante la marca -h en lugar de --help. También puedes consultar la ayuda completa en la referencia del SDK de Cloud.

A fin de obtener la ayuda completa de comandos específicos para configurar la herramienta de gcloud, ejecuta el siguiente comando:

<pre class="devsite-click-to-copy>gcloud topic <var>TOPIC</var></pre>

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

Próximos pasos