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 describe cómo realizar la transición de gsutil a los comandos gcloud storage de gcloud CLI. Para ello, se detallan las principales diferencias y 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 actualizar tus secuencias de comandos con los comandos gcloud storage comparables.

Para aprender a comenzar a usar gcloud CLI, consulta Instala Google Cloud CLI.

Para obtener una descripción detallada de los comandos de 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.

Control de comodines

gcloud storage simplifica varios asteriscos. Si usas tres o más asteriscos seguidos (***), se 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 un entorno local a otro

gcloud storage está diseñado exclusivamente para interactuar con Cloud Storage y no admite la copia de archivos de forma 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 resultado

Los comandos gcloud storage y gsutil dan formato a su resultado de manera diferente. Si bien es posible que los cambios menores, como el formato de registro, no te afecten, 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.

Equivalentes de comandos de gcloud

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

Operación Comando de gsutil Comando gcloud storage
Administra listas de control de acceso (LCA) 
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 gcloud storage
Concatenar objetos y mostrar su contenido 
gsutil cat
 
gcloud storage cat
Operación Comando de gsutil Comando 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 gcloud storage
Copia objetos y otros recursos 
gsutil cp
 
gcloud storage cp
Notas

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

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

Cuando descargas 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 gcloud storage
Muestra el espacio total en el disco que usan los objetos 
gsutil du
 
gcloud storage du
Operación Comando de gsutil Comando gcloud storage
Calcula 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 gcloud storage
Administra las 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 de gsutil label ch puede comportarse de manera diferente que las operaciones equivalentes con gcloud storage buckets update. Las secuencias de comandos que dependen del comportamiento específico de lectura, modificación y escritura de gsutil deben probarse con cuidado después de la transición a gcloud storage.
Operación Comando de gsutil Comando gcloud storage
Enumera buckets, objetos y carpetas 
gsutil ls
 
gcloud storage ls
Notas

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

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

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

gcloud storage siempre genera fechas y horas en UTC.

gcloud storage devuelve cualquier mensaje de error al final del resultado del comando.
Operación Comando de gsutil Comando gcloud storage
Mueve objetos o directorios y cámbiales el nombre 
gsutil mv
 
gcloud storage mv
Operación Comando de gsutil Comando gcloud storage
Vuelve a escribir objetos en el lugar 
gsutil rewrite
 
gcloud storage objects update
Notas

Si se establece un 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 de KMS predeterminada del bucket o con la encriptación administrada por Google.

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). Es posible que gcloud storage objects update no realice las mismas verificaciones, lo que podría generar operaciones innecesarias.
Operación Comando de gsutil Comando gcloud storage
Quita objetos o buckets 
gsutil rm
 
gcloud storage rm
Notas

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

Existe 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 para que se borren de forma recurrente deben probarse exhaustivamente antes de pasar de usar gsutil a gcloud storage.
Operación Comando de gsutil Comando gcloud storage
Sincroniza 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 hora de ú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 su hora de modificación o si lo fuerzas de forma manual con la marca -c. gcloud storage rsync también comienza por verificar 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 la suma de comprobación.

De forma predeterminada, gcloud storage rsync realiza operaciones en paralelo 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 gcloud storage
Configura metadatos en los objetos subidos 
gsutil setmeta
 
gcloud storage objects update
Notas

gsutil setmeta usa una sola marca -h repetible para especificar qué metadatos se deben 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, la marca -h se usa 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 personalizado, 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 gcloud storage
Muestra 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 el resultado 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 de gsutil.