Migrar de gsutil a gcloud storage

gcloud storage (disponibilidad general) es la herramienta de línea de comandos recomendada para interactuar con Cloud Storage. En esta página se explica cómo pasar de gsutil a gcloud storage. Para ello, se describen las principales diferencias y las asignaciones de comandos entre las dos herramientas. Para obtener una descripción detallada de la herramienta gcloud storage, consulta la gcloud storage documentación de referencia.

Para saber cómo instalar y empezar a usar Google Cloud CLI, consulta el artículo Instalar Google Cloud CLI.

Diferencias de comportamiento

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

Invocaciones paralelas

gcloud storage no permite ejecutar varias instancias de la CLI desde diferentes terminales simultáneamente.

Procesamiento en paralelo

gcloud storage admite el procesamiento en paralelo.

Gestión de comodines

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

Gestión de segmentos de espacios de nombres jerárquicos

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

Formato de salida

Los comandos gcloud storage y gsutil dan formato a su salida de forma diferente. Aunque los cambios menores, como el formato de registro, no te afecten, las diferencias más significativas en los mensajes de error y los listados 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 al formato gcloud storage antes de hacer la transición.

Equivalentes de comandos de gcloud

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

Operación Comando gsutil Comando gcloud storage
Gestionar listas de control de acceso (LCAs) 
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 gsutil Comando gcloud storage
Concatenar objetos y mostrar el contenido de un objeto 
gsutil cat
 
gcloud storage cat
Operación Comando gsutil Comando gcloud storage
Concatenar objetos combinándolos en un objeto nuevo 
gsutil compose
 
gcloud storage objects compose
Notas
Para aplicar precondiciones en gcloud storage objects compose, usa marcas específicas, como --if-generation-match o --if-metageneration-match.
Operación Comando gsutil Comando gcloud storage
Copiar objetos y otros recursos 
gsutil cp
 
gcloud storage cp
Notas

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

Al gestionar errores, gcloud storage cp intenta copiar todos los recursos, aunque uno de ellos no sea válido o no exista. gsutil cp puede detener toda la operación en cuanto detecte un recurso no válido.

Al descargar un objeto, gcloud storage cp crea los directorios locales que falten y que se especifiquen en la ruta de destino. gsutil cp falla si el directorio de destino no existe.
Operación Comando gsutil Comando gcloud storage
Mostrar el espacio total en disco utilizado por los objetos 
gsutil du
 
gcloud storage du
Operación Comando gsutil Comando 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 de sustracción para excluir hashes, como --skip-md5 o --skip-crc32c.
Operación Comando gsutil Comando gcloud storage
Gestionar etiquetas de segmentos 
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 añadir, actualizar y quitar etiquetas en un solo comando gsutil label ch puede comportarse de forma diferente a las operaciones equivalentes con gcloud storage buckets update. Las secuencias de comandos que dependan de un comportamiento de lectura-modificación-escritura específico de gsutil deben probarse cuidadosamente después de cambiar a gcloud storage.
Operación Comando gsutil Comando gcloud storage
Listar segmentos, objetos y carpetas 
gsutil ls
 
gcloud storage ls
Notas

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

Cuando se usa gcloud storage ls -L para devolver listados detallados como resultado, se aplican los siguientes comportamientos:

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

gcloud storage siempre genera fechas y horas en formato UTC.

gcloud storage devuelve los mensajes de error al final de la salida del comando.
Operación Comando gsutil Comando gcloud storage
Mover y cambiar el nombre de objetos o directorios 
gsutil mv
 
gcloud storage mv
Operación Comando gsutil Comando gcloud storage
Reescribir objetos in situ 
gsutil rewrite
 
gcloud storage objects update
Notas

Si se define un encryption_key en el archivo de configuración de boto, gsutil rewrite -k aplica la clave a los objetos. Si no se define encryption_key, el equivalente de gsutil rewrite -k es gcloud storage objects update --clear-encryption-key. De esta forma, se eliminan las claves de encriptado proporcionadas por el cliente (CSEK) o las claves de encriptado gestionadas por el cliente (CMEK) del objeto. A continuación, el objeto se cifra con la clave de KMS predeterminada del segmento o con el cifrado gestionado 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). gcloud storage objects update puede que no realice las mismas comprobaciones, lo que puede provocar operaciones innecesarias.
Operación Comando gsutil Comando gcloud storage
Eliminar objetos o segmentos 
gsutil rm
 
gcloud storage rm
Notas

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

Hay un problema conocido por el que gsutil y gcloud storage se comportan de forma diferente cuando se usan juntas las marcas -l y -r. Las secuencias de comandos que canalizan una lista de directorios que se van a eliminar de forma recursiva deben probarse a fondo antes de pasar de usar gsutil a gcloud storage.
Operación Comando gsutil Comando gcloud storage
Sincronizar el contenido de dos cubos o directorios 
gsutil rsync
 
gcloud storage rsync
Notas

De forma predeterminada, gsutil rsync considera que un objeto no ha cambiado 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 fuerza manualmente con la marca -c. gcloud storage rsync también empieza comprobando 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 son diferentes o faltan, realiza automáticamente una comparación de la 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 enlaces 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 gsutil Comando gcloud storage
Definir metadatos en objetos subidos 
gsutil setmeta
 
gcloud storage objects update
Notas

gsutil setmeta usa una sola marca -h repetible para especificar qué metadatos se deben definir o eliminar. 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 definir 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, que 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 gsutil Comando gcloud storage
Mostrar el estado de un objeto 
gsutil stat
 
gcloud storage objects list --stat --fetch-encrypted-object-hashes
Notas

El formato de salida de gcloud storage objects list --stat es diferente del de gsutil stat, y hay problemas conocidos relacionados con la inconsistencia del espaciado. Es posible que las secuencias de comandos escritas para analizar el resultado de gsutil stat requieran ajustes para gestionar el nuevo formato de salida.