Transición de gsutil a gcloud storage

Google Cloud CLI es la herramienta de línea de comandos recomendada para interactuar con Cloud Storage. En esta página, se te ayudará a realizar la transición de gsutil a los comandos gcloud storage de la gcloud CLI. Para ello, se describen las principales diferencias y las asignaciones de comandos entre las dos herramientas. Si tienes secuencias de comandos que usan gsutil, puedes usar la información de esta página para actualizarlas con los comandos gcloud storage comparables.

Para obtener información sobre cómo comenzar a usar gcloud CLI, consulta Instala Google Cloud CLI.

Para obtener una descripción detallada de los comandos gcloud storage, consulta la documentación de referencia de gcloud storage.

Diferencias de comportamiento

En las siguientes secciones, se describen las diferencias de comportamiento entre gsutil y gcloud storage.

Invocaciones paralelas

gcloud storage no admite invocaciones paralelas con varias terminales en la misma máquina.

Procesamiento paralelo

gcloud storage admite el procesamiento paralelo.

Manejo de comodines

gcloud storage simplifica varios asteriscos. Si usas tres o más asteriscos seguidos (***), los trata como un solo asterisco (*).

Manejo de buckets con espacios de nombres jerárquicos

gcloud storage se puede usar para crear y administrar buckets con el espacio de nombres jerárquico habilitado.

Compatibilidad con la copia de archivos de local a local

gcloud storage está diseñado exclusivamente para interactuar con Cloud Storage y no admite la copia de archivos de local a local. Para mover datos correctamente con gcloud storage, al menos un argumento (origen o destino) debe ser un URI de recurso de Cloud Storage. Por ejemplo: gs://my-bucket.

Formato de salida

Los comandos gcloud storage y gsutil dan formato a su salida de manera diferente. Si bien los cambios menores, como el formato de registro, podrían no afectarte, las diferencias más significativas en los mensajes de error y las listas de datos pueden interrumpir las secuencias de comandos automatizadas.

Si tienes secuencias de comandos que dependen del análisis del resultado del comando gsutil, debes revisarlas y actualizarlas para el formato gcloud storage antes de realizar la transición.

Comandos equivalentes de gcloud

Todos los comandos gsutil existentes tienen comandos equivalentes en gcloud storage, con algunas excepciones. Para obtener una lista completa de los gcloud storage comandos, visita la documentación de referencia o ejecuta gcloud storage --help. En la siguiente tabla, se describen brevemente los cambios de los comandos gsutil populares.

Operación Comando de gsutil Comando de gcloud storage
Administrar listas de control de acceso (ACL) 
gsutil acl get
gsutil acl set
gsutil acl ch

gcloud storage RESOURCE describe --format="multi(acl:format=json)"
gcloud storage RESOURCE update --acl-file=ACL_FILE_PATH
gcloud storage RESOURCE update --add-acl-grant=GRANT
gcloud storage RESOURCE update --remove-acl-grant=GRANT
Operación Comando de gsutil Comando de gcloud storage
Concatenar objetos y mostrar el contenido del objeto 
gsutil cat
 
gcloud storage cat
Operación Comando de gsutil Comando de gcloud storage
Concatenar objetos combinándolos en un objeto nuevo 
gsutil compose
 
gcloud storage objects compose
Notas
Para aplicar condiciones previas en gcloud storage objects compose, usa marcas específicas, como --if-generation-match o --if-metageneration-match.
Operación Comando de gsutil Comando de gcloud storage
Copiar objetos y otros recursos 
gsutil cp
 
gcloud storage cp
Notas

Las carpetas simuladas creadas con la Google Cloud consola se reconocen como objetos de marcador de posición de 0 bytes. Se puede usar gcloud storage cp para copiar carpetas simuladas, mientras que gsutil cp no.

Cuando se manejan errores, gcloud storage cp intenta copiar todos los recursos, incluso si uno de ellos no es válido o no existe. gsutil cp puede detener toda la operación en cuanto encuentra un recurso no válido.

Cuando se descarga un objeto, gcloud storage cp crea los directorios locales faltantes que se especifican en la ruta de destino. gsutil cp falla si el directorio de destino no existe.
Operación Comando de gsutil Comando de gcloud storage
Mostrar el espacio total en disco que usan los objetos 
gsutil du
 
gcloud storage du
Operación Comando de gsutil Comando de gcloud storage
Calcular hashes de archivos 
gsutil hash
 
gcloud storage hash
Notas

gsutil hash usa marcas aditivas para incluir hashes específicos, como -c o -m. gcloud storage hash usa marcas sustractivas para excluir hashes, como --skip-md5 o --skip-crc32c.
Operación Comando de gsutil Comando de gcloud storage
Administrar etiquetas de bucket 
gsutil label get
gsutil label set
gsutil label ch

gcloud storage buckets describe
gcloud storage buckets update
gcloud storage buckets update
Notas

La combinación de agregar, actualizar y quitar etiquetas en un solo comando gsutil label ch puede comportarse de manera diferente que las operaciones equivalentes con gcloud storage buckets update. Las secuencias de comandos que dependen de un comportamiento específico de lectura, modificación y escritura de gsutil se deben probar con cuidado después de la transición a gcloud storage.
Operación Comando de gsutil Comando de gcloud storage
Enumerar buckets, objetos y carpetas 
gsutil ls
 
gcloud storage ls
Notas

Cuando se usa un comodín para enumerar objetos en un proyecto, gsutil ls muestra una lista plana de objetos, mientras que gcloud storage ls muestra objetos con agrupación por nombre de bucket.

Cuando se usa gcloud storage ls -L para mostrar listas detalladas como resultado, se aplican los siguientes comportamientos:

  • Las etiquetas de cada metadato (también conocidas como “clave”) tienen la primera letra de cada palabra en mayúscula.
  • Si un metadato de un objeto no tiene un valor, gcloud storage omite esa línea del resultado.

gcloud storage siempre muestra las fechas y horas en UTC.

gcloud storage muestra los mensajes de error al final del resultado del comando.
Operación Comando de gsutil Comando de gcloud storage
Mover y cambiar el nombre de objetos o directorios 
gsutil mv
 
gcloud storage mv
Operación Comando de gsutil Comando de gcloud storage
Reescribir objetos en su lugar 
gsutil rewrite
 
gcloud storage objects update
Notas

Si se establece una encryption_key en tu archivo de configuración de boto, gsutil rewrite -k aplica la clave a los objetos. Si no se establece encryption_key, el equivalente de gsutil rewrite -k es gcloud storage objects update --clear-encryption-key. Esto quita del objeto las claves de encriptación proporcionadas por el cliente (CSEK) o las claves de encriptación administradas por el cliente (CMEK). Luego, el objeto se encripta con la clave KMS predeterminada del bucket o con la encriptación Google-administrada.

gsutil rewrite incluye lógica para omitir la reescritura de un objeto si la transformación solicitada no cambia su estado (por ejemplo, si el objeto ya está en una clase de almacenamiento de destino). gcloud storage objects update podría no realizar las mismas verificaciones, lo que podría generar operaciones innecesarias.
Operación Comando de gsutil Comando de gcloud storage
Quitar objetos o buckets 
gsutil rm
 
gcloud storage rm
Notas

No se admiten los alias gsutil del, delete y remove.

Hay un problema conocido en el que gsutil y gcloud storage se comportan de manera diferente cuando se usan las marcas -l y -r juntas. Las secuencias de comandos que canalizan una lista de directorios que se borrarán de forma recursiva se deben probar minuciosamente antes de realizar la transición del uso de gsutil a gcloud storage.
Operación Comando de gsutil Comando de gcloud storage
Sincronizar el contenido de dos buckets o directorios 
gsutil rsync
 
gcloud storage rsync
Notas

De forma predeterminada, gsutil rsync considera que un objeto no cambia si su tamaño y la hora de la última modificación coinciden entre el origen y el destino. Solo realiza una comparación de suma de comprobación más exhaustiva si a un objeto le falta la hora de modificación o si la fuerzas de forma manual con la marca -c. gcloud storage rsync también comienza verificando el tamaño de un archivo y la hora de la última modificación. Sin embargo, si los tamaños de los objetos coinciden, pero las horas de modificación difieren o faltan, realiza automáticamente una comparación de suma de comprobación.

gcloud storage rsync realiza operaciones en paralelo de forma predeterminada para mejorar el rendimiento. gsutil rsync se ejecuta de forma secuencial, a menos que se use la marca -m de nivel superior.

gsutil rsync sigue los vínculos simbólicos de forma predeterminada. gcloud storage rsync los ignora de forma predeterminada, a menos que se use la marca --no-ignore-symlinks.
Operación Comando de gsutil Comando de gcloud storage
Establecer metadatos en objetos subidos 
gsutil setmeta
 
gcloud storage objects update
Notas

gsutil setmeta usa una sola marca -h repetible para especificar qué metadatos establecer o quitar. gcloud storage objects update usa marcas distintas para cada campo de metadatos (por ejemplo: --content-type, --clear-cache-control o --update-custom-metadata).

En gsutil setmeta, se usa la marca -h para establecer el nombre completo del encabezado (por ejemplo: -h "x-goog-meta-icecreamflavor:vanilla"). En gcloud storage objects update, se usa la marca --update-custom-metadata en su lugar y toma pares clave-valor (por ejemplo: --update-custom-metadata=icecreamflavor=vanilla). Para quitar un campo de metadatos personalizados,gsutil setmeta usa -h "x-goog-meta-icecreamflavor", mientras que gcloud storage objects update usa --remove-custom-metadata=icecreamflavor.
Operación Comando de gsutil Comando de gcloud storage
Mostrar el estado del objeto 
gsutil stat
 
gcloud storage objects list --stat --fetch-encrypted-object-hashes
Notas

El formato de salida de gcloud storage objects list --stat difiere del formato de salida de gsutil stat, con problemas conocidos relacionados con el espaciado incoherente. Es posible que las secuencias de comandos que se escribieron para analizar la salida de gsutil stat requieran ajustes para controlar el formato de salida de gcloud storage objects list --stat.

¿Qué sigue?

Para obtener más detalles sobre las asignaciones de comandos y marcas, consulta la referencia de migración en el repositorio de GitHub gsutil.