Ativar buckets do Cloud Storage usando o Cloud Storage FUSE

Opções da CLI do Cloud Storage FUSE

Este documento descreve várias maneiras de ativar buckets do Cloud Storage no sistema de arquivos local usando o Cloud Storage FUSE.

Antes de começar

Para montar e acessar buckets, primeiro conclua as tarefas a seguir. Não é possível usar o Cloud Shell para montar buckets do Cloud Storage. Em vez disso, execute os comandos fornecidos neste documento no terminal da máquina Debian ou Ubuntu.

Ter os papéis necessários para ativar e acessar um bucket

Para montar, acessar e realizar operações de leitura e gravação em um bucket, peça ao proprietário para conceder a você o papel de Usuário do objeto do Storage (roles/storage.objectUser) no bucket.

Esse papel predefinido contém as permissões necessárias para ler em um bucket ativado e gravar em um bucket ativado. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

  • storage.objects.create
  • storage.objects.delete
  • storage.objects.get
  • storage.objects.list
  • storage.objects.update

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Para instruções sobre como conceder papéis nos buckets, consulte Definir e gerenciar políticas do IAM em buckets.

Instale o Cloud Storage FUSE

Instale o Cloud Storage FUSE na sua máquina, caso ainda não tenha feito isso.

Autenticar solicitações do FUSE do Cloud Storage

Para autenticar as solicitações do FUSE do Cloud Storage no Cloud Storage, você precisa configurar o Application Default Credentials. Por padrão, o Cloud Storage FUSE carrega automaticamente o Application Default Credentials existente sem nenhuma configuração adicional.

Para usar a Google Cloud CLI para configurar o Application Default Credentials, siga estas etapas:

  1. Install the Google Cloud CLI.

  2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  3. To initialize the gcloud CLI, run the following command: 

    gcloud init

  4. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

Quando você cria uma máquina virtual (VM) do Compute Engine, a conta de serviço também pode ser usada para autenticar o acesso ao Cloud Storage FUSE.

Montar um bucket

Para ativar buckets no sistema de arquivos local, execute o seguinte comando na máquina local:

gcsfuse GLOBAL_OPTIONS BUCKET_NAME MOUNT_POINT

Substitua:

  • GLOBAL_OPTIONS são as opções que você pode incluir para controlar como a ativação é configurada. Para mais informações sobre as opções e como usá-las, consulte a referência da CLI do Cloud Storage FUSE ou as páginas do arquivo de configuração do Cloud Storage FUSE.

    • BUCKET_NAME é o nome do bucket que você quer ativar. Por exemplo, my-bucket. Se você quiser executar a montagem dinâmica, exclua um nome de bucket do comando.

    • MOUNT_POINT é o diretório local em que o bucket é ativado. Por exemplo, /path/to/mount/point.

Opcional: para criar diretórios definidos implicitamente que permitem navegar até pastas que contêm apenas objetos aninhados mais profundamente, inclua a flag --implicit-dirs no comando gcsfuse. Para saber mais sobre diretórios definidos implicitamente, consulte Semântica de diretório.

Depois que o Cloud Storage FUSE sair, é possível acessar seus buckets montados executando ls no ponto de ativação do bucket. Se preferir que o Cloud Storage FUSE permaneça em primeiro plano (por exemplo, para a geração de registros de depuração), execute o comando gcsfuse com o campo foreground ou a opção --foreground.

Exemplos de montagem

Nesta seção, descrevemos diferentes exemplos de comandos para a montagem de buckets.

Montagem estática

A montagem estática se refere à ativação de um bucket específico. Por exemplo, para ativar um bucket chamado my-bucket no diretório /path/to/mount/point, execute os seguintes comandos:

mkdir /path/to/mount/point
gcsfuse my-bucket /path/to/mount/point

Montagem dinâmica

A montagem dinâmica refere-se à ativação de todos os buckets a que um usuário tem acesso como subdiretórios.

Quando você executa a montagem dinâmica, exclui os nomes dos buckets do comando. Por exemplo, digamos que você tenha acesso a buckets chamados my-bucket-1, my-bucket-2 e my-bucket-3. Para ativar todos os buckets no diretório /path/to/mount/point, execute os seguintes comandos:

mkdir /path/to/mount/point
gcsfuse /path/to/mount/point

Em seguida, é possível acessar os buckets como subdiretórios:

ls /path/to/mount/point/my-bucket-1/
ls /path/to/mount/point/my-bucket-2/
ls /path/to/mount/point/my-bucket-3/

Buckets montados dinamicamente não podem ser listados a partir do ponto de montagem raiz. Em vez disso, o nome do bucket precisa ser especificado como parte da operação de lista.

Como ativar um bucket como somente leitura

Para ativar um bucket como somente leitura, transmita a opção -o ro para o comando gcsfuse. Por exemplo, para ativar um bucket chamado my-bucket como somente leitura no diretório /path/to/mount/point, execute o seguinte comando:

gcsfuse -o ro my-bucket  /path/to/mount/point

Montar um diretório em um bucket

Por padrão, o Cloud Storage FUSE monta totalmente os buckets, o que inclui todo o conteúdo e as estruturas de diretório do bucket. Para ativar um diretório específico em um bucket, transmita a opção --only-dir para a CLI gcsfuse ou o campo only-dir em um arquivo de configuração do Cloud Storage FUSE. Por exemplo, para ativar o diretório my-bucket/a/b no diretório /path/to/mount/point, execute o seguinte comando:

gcsfuse --only-dir a/b my-bucket /path/to/mount/point

Como ativar usando o comando mount do Linux

A instalação do Cloud Storage FUSE inclui um auxiliar compreendido pelo comando mount do Linux, que permite usar o comando mount para ativar buckets. Se você estiver usando o Linux, execute o comando mount na raiz. Por exemplo, o comando a seguir monta um bucket chamado my-bucket para o caminho /path/to/mount/point:

sudo mount -t gcsfuse -o rw,user my-bucket /path/to/mount/point

Durante a montagem com o comando mount do Linux, as opções gcsfuse podem ser transmitidas como um argumento para a opção -o, mas os hifens (-) precisam ser substituídos por sublinhados (_). Por exemplo, implicit_dirs no lugar de implicit-dirs.

sudo mount -t gcsfuse -o implicit_dirs my-bucket /path/to/mount/point

Montagem permanente

A instalação do FUSE do Cloud Storage inclui um auxiliar instalado no sistema no caminho /sbin/mount.gcsfuse. Esse auxiliar permite criar pontos de montagem usando o arquivo /etc/fstab. Assim, você consegue manter as ativações.

Por exemplo, quando adicionada ao arquivo /etc/fstab, a linha a seguir define um ponto de ativação para o bucket my-bucket no caminho /mount/point:

my-bucket /mount/point gcsfuse rw,noauto,user

Em que:

  • A opção rw especifica que o ponto de ativação será criado com permissões de leitura e gravação.

  • A opção noauto especifica que o sistema de arquivos não deve ser montado no momento da inicialização.

  • A opção user permite que qualquer pessoa crie o ponto de ativação especificado no arquivo /etc/fstab. Depois que a linha de amostra é adicionada ao arquivo /etc/fstab, é possível executar mount /mount/point como um usuário não raiz.

Se você quiser ativar o bucket automaticamente na inicialização, talvez seja necessário incluir a opção x-systemd.requires=network-online.target ou _netdev na entrada /etc/fstab para garantir que o Cloud Storage FUSE aguarde para o sistema de rede estar pronto antes da ativação. Por exemplo:

my-bucket /mount/point gcsfuse rw,x-systemd.requires=network-online.target,user

É possível ativar um bucket automaticamente como um usuário não raiz específico incluindo as opções uid e/ou gid na sua entrada /etc/fstab. Por exemplo:

my-bucket /mount/point gcsfuse rw,_netdev,allow_other,uid=1001,gid=1001

Assim como o comando mount do Linux, as flags usadas para montagem no arquivo /etc/fstab precisam usar sublinhados (_) no lugar de hifens (-). Por exemplo, implicit_dirs no lugar de implicit-dirs.

Montar um bucket com pastas

É possível montar buckets com vários tipos de pastas.

Montar um bucket com pastas gerenciadas

Para ativar um bucket incluindo as pastas gerenciadas, inclua a opção --implicit-dirs ou o campo implicit-dirs no comando.

Por exemplo, para ativar um bucket chamado my-bucket e as pastas gerenciadas no diretório /path/to/mount/point, execute os seguintes comandos:

gcsfuse --implicit-dirs my-bucket /path/to/mount/point

Ao montar um bucket com pastas gerenciadas, lembre-se das seguintes limitações e considerações:

  • As pastas gerenciadas vazias não aparecem em buckets montados.

  • Não é possível definir ou gerenciar permissões do IAM em uma pasta gerenciada usando o Cloud Storage FUSE. Para definir ou gerenciar permissões do IAM em uma pasta gerenciada, consulte Usar IAM com pastas gerenciadas.

  • É possível copiar e mover uma pasta gerenciada em um bucket ativado usando os comandos cp e mv. Quando você copia ou move uma pasta gerenciada, as políticas do IAM na pasta gerenciada original não permanecem na nova pasta gerenciada. É necessário definir novas políticas do IAM na nova pasta gerenciada.

Montar um bucket com pastas definidas implicitamente

É possível montar pastas definidas implicitamente usando a opção --implicit-dirs gcsfuse na CLI gcsfuse ou o campo implicit-dirs em um arquivo de configuração do Cloud Storage FUSE. As pastas definidas implicitamente não são criadas explicitamente como objetos no Cloud Storage. A opção --implicit-dirs permite que você veja as pastas ao montar um bucket.

Por exemplo, para ativar um bucket chamado my-bucket no diretório /path/to/mount/point com pastas definidas implicitamente, execute o seguinte comando:

gcsfuse --implicit-dirs my-bucket /path/to/mount/point

Montar um bucket com namespace hierárquico e pastas

É possível montar um bucket com o namespace hierárquico ativado, incluindo as pastas. Ao montar um bucket com namespace hierárquico, não é necessário especificar a opção --implicit-dirs gcsfuse ou o campo implicit-dirs para que as pastas apareçam no bucket montado.

Por exemplo, para ativar um bucket chamado my-bucket com pastas no diretório /path/to/mount/point, execute o seguinte comando:

gcsfuse my-bucket /path/to/mount/point

Controlar permissões de acesso ao ponto de montagem

Por padrão, o Cloud Storage FUSE cria pontos de ativação do bucket com permissões que permitem apenas que o usuário que invoca acesse o conteúdo dos buckets ativados. Essa é uma medida de segurança implementada no kernel do FUSE.

Para ativar um bucket e permitir que outras pessoas acessem o ponto de ativação do bucket, execute o comando mount como raiz com a opção -o allow_other:

mount -t gcsfuse -o allow_other my-bucket /path/to/mount/point

Se você quiser evitar a ativação do bucket como raiz, adicione user_allow_other ao arquivo /etc/fuse.conf para permitir que outras pessoas acessem o ponto de ativação do bucket.

Desconectar um bucket

Para desativar um bucket, use a ferramenta fusermount:

fusermount -u /path/to/mount/point

A seguir