Transición 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 describen las principales diferencias y las asignaciones de comandos entre las dos herramientas para ayudarte a realizar la transición de gsutil a gcloud storage. Para obtener una descripción detallada de la herramienta gcloud storage, consulta la documentación de referencia de gcloud storage.

Para obtener información sobre cómo instalar y comenzar a usar Google Cloud CLI, consulta Instala 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 admite la ejecución de varias instancias de la CLI desde diferentes terminales de forma simultánea.

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 interpretarán 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.

Formato de resultado

Los comandos gcloud storage y gsutil formatean sus resultados 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 los listados de datos pueden interrumpir los 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 realizar la transición.

Equivalentes de los 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 gcloud storage si visitas la documentación de referencia o si ejecutas gcloud storage --help. En la siguiente tabla, se describen con brevedad los cambios de los comandos populares de gsutil.

Operación Comando de gsutil Comando de 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 de gcloud storage
Concatenar objetos y mostrar el contenido de los objetos 
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
Copia objetos y otros recursos 
gsutil cp
 
gcloud storage cp
Notas

Las carpetas simuladas creadas con la consola 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 de gcloud storage
Cómo mostrar el espacio total en disco que usan los objetos 
gsutil du
 
gcloud storage du
Operación Comando de gsutil Comando de gcloud storage
Cómo 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 resta para excluir hashes, como --skip-md5 o --skip-crc32c.
Operación Comando de gsutil Comando de gcloud storage
Administra 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 a las operaciones equivalentes que usan gcloud storage buckets update. Las secuencias de comandos que dependen del comportamiento específico de lectura-modificación-escritura de gsutil deben probarse cuidadosamente después de la transición a gcloud storage.
Operación Comando de gsutil Comando de 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 devolver fichas detalladas como resultado, se aplican los siguientes comportamientos:

  • Las etiquetas de cada fragmento de metadatos (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 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 de gcloud storage
Mueve y cambia el nombre de objetos o directorios 
gsutil mv
 
gcloud storage mv
Operación Comando de gsutil Comando de gcloud storage
Reescribe objetos en su lugar 
gsutil rewrite
 
gcloud storage objects update
Notas

Si se configura 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 las claves de encriptación proporcionadas por el cliente (CSEK) o las claves de encriptación administradas por el cliente (CMEK) del objeto. 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 cambiaría 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
Cómo quitar objetos o buckets 
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 manera diferente cuando se usan juntas las marcas -l y -r. Las secuencias de comandos que canalizan una lista de directorios para que se borren de forma recursiva se deben probar exhaustivamente antes de pasar de usar gsutil a gcloud storage.
Operación Comando de gsutil Comando de 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 cambió si su tamaño y la última hora de modificación coinciden entre la fuente y el destino. Solo realiza una comparación más exhaustiva de la suma de verificación si a un objeto le falta la hora de modificación o si la fuerzas manualmente con la marca -c. gcloud storage rsync también comienza verificando el tamaño y la hora de la última modificación de un archivo. 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.

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
Configura 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 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 y se toman 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 de gcloud storage
Estado del objeto de pantalla 
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 escritas para analizar el resultado de gsutil stat requieran ajustes para controlar el nuevo formato de salida.