CLI do Cloud Storage FUSE

Nesta página, descrevemos as opções de comando gcsfuse usadas para interagir com o Cloud Storage FUSE. Se você estiver usando o driver CSI do Cloud Storage FUSE para ativar seus buckets no sistema de arquivos local no Google Kubernetes Engine, consulte Opções de ativação para o driver CSI do Cloud Storage FUSE.

Visão geral da CLI do Cloud Storage FUSE

A interface de linha de comando (CLI) do Cloud Storage FUSE, ou CLI gcsfuse, é usada para ativar buckets do Cloud Storage como sistemas de arquivos em uma máquina local.

Estrutura de comando da CLI gcsfuse

O exemplo a seguir mostra a estrutura do comando gcsfuse, incluindo comandos obrigatórios e opções gcsfuse opcionais.

gcsfuse GLOBAL_OPTIONS BUCKET_NAME MOUNT_POINT

Em que:

  • GLOBAL_OPTIONS são as opções gcsfuse que controlam como a montagem é configurada e o comportamento do Cloud Storage FUSE.

  • BUCKET_NAME é o nome do bucket a ser ativado. Por exemplo, my-mount-bucket. Opcional. Exclua um nome de bucket desse comando para realizar a montagem dinâmica.

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

Opções da CLI gcsfuse

Opção gcsfuse Descrição Valor válido Valor padrão
Desativa a autenticação para solicitações. Essa opção deve ser definida se você estiver usando um endpoint personalizado que não é compatível com autenticação. Essa opção também deve ser definida se você estiver usando o Cloud Storage FUSE com buckets públicos. Valor booleano: true, false. false
O nome do aplicativo da montagem. Valor de string, por exemplo: my-bucket-mount. ""
Especifica um projeto para usar no faturamento quando o bucket ativado é acessado. Essa opção é frequentemente necessária ao ativar um bucket ativado com pagamentos do solicitante. Valor da string que representa um ID do projeto. ""

Ativa o cache de arquivos e especifica o diretório para armazenar dados de cache de arquivos.

 Um caminho, por exemplo: /tmp/gcsfuse-cache-path. Um valor vazio indica que a opção está desativada. Essa opção gcsfuse está desativada por padrão. ""
Especifica o protocolo usado para comunicação com o back-end do Cloud Storage. http1

Exporta métricas para o Cloud Monitoring com o intervalo especificado.

 Número inteiro que representa um valor em segundos, por exemplo: 10 (10 segundos). 0 não especifica a exportação. 0
Especifica o caminho para o arquivo de configuração que você quer usar para configurar os comportamentos do Cloud Storage FUSE. Um caminho, por exemplo: /etc/gcsfuse.yaml. ""
Especifica um endpoint personalizado alternativo para buscar dados. O endpoint personalizado precisa ser compatível com os recursos e as operações equivalentes ao endpoint JSON do Cloud Storage, storage.UNIVERSE_DOMAIN_NAME:443. Se um endpoint personalizado não for especificado, o Cloud Storage FUSE usará o endpoint global da API JSON do Cloud Storage, storage.googleapis.com:443. Se a autenticação não tiver suporte no endpoint personalizado que você especificar, defina a opção --anonymous-access gcsfuse como true para ignorar a autenticação. Um endpoint, por exemplo: storage.googleapis.com:443. ""
Ativa a saída de depuração relacionada ao FUSE. Essa opção foi substituída pela --log-severity gcsfuse. Para ativar a saída de depuração, defina a opção --log-severity gcsfuse como trace, que inclui registros de rastreamento, depuração, informações, avisos e erros. Valor booleano: true, false. false
Imprime informações de solicitação e tempo do Cloud Storage. Essa opção gcsfuse foi substituída pela opção --log-severity gcsfuse. Para ativar a saída de depuração, defina a opção --log-severity gcsfuse como trace, que inclui registros de rastreamento, depuração, informações, avisos e erros. Valor booleano: true, false. false
Sai do programa quando violações invariantes internas são detectadas. Valor booleano: true, false. false
Imprime mensagens de depuração quando uma mutex é mantida por muito tempo. Se essa opção gcsfuse for especificada, o nível de gravidade dos registros será definido automaticamente como trace, o que inclui registros de rastreamento, depuração, informações, aviso e erro. Valor booleano: true, false. false
Bits de permissões para diretórios, em octal. Número inteiro entre 000 e 777 (inclusive). 755
Especifica a pré-busca assíncrona de partes de um objeto do Cloud Storage em um buffer na memória, permitindo que as leituras subsequentes sejam atendidas do buffer em vez de exigir chamadas de rede. Valor booleano: true, false false
Cria uma entrada de cache de tipo com o tipo NonexistentType se um arquivo não for encontrado no Cloud Storage. Se o arquivo for criado no Cloud Storage, mas a entrada NonexistentType para o arquivo for armazenada em cache, o Cloud Storage FUSE não poderá solicitar esse arquivo até que a entrada NonexistentType seja removida do tipo cache. Valor booleano: true, false. false
Controla o fluxo do caminho de gravação para que os dados sejam enviados diretamente para o Cloud Storage à medida que são gravados, em vez de fazer o staging completo da gravação localmente e fazer upload dela após close() ou fsync(). Para mais informações sobre gravações de streaming, consulte Semântica do Cloud Storage FUSE na documentação do GitHub do Cloud Storage FUSE. Valor booleano: true, false. true

Especifica o tamanho máximo em MiB que o cache de arquivos pode usar e permite limitar a capacidade total que o cache de arquivos pode usar no diretório ativado.
  • Número inteiro
  • -1: especifica o uso de toda a capacidade disponível do cache no diretório especificado para cache-dir. Esse é o padrão somente se cache-dir for transmitido.
  • 0: desativa o cache de arquivos.
 -1
Determina se o download completo do objeto precisa ser feito de modo assíncrono e armazenado no diretório de cache do Cloud Storage FUSE quando a primeira leitura for feita de um deslocamento diferente de zero. A opção gcsfuse precisa ser definida como true se você planeja executar várias leituras aleatórias ou parciais. Valor booleano: true, false. false
Especifica o tamanho de cada solicitação de leitura em MiB que cada goroutine faz para o Cloud Storage ao fazer o download do objeto no cache de arquivos. Número inteiro 200

Acelera a leitura de arquivos grandes usando o diretório de cache de arquivos como um buffer de pré-busca usando vários workers para fazer o download de várias partes de um arquivo em paralelo.

Os downloads paralelos são ativados automaticamente quando você ativa o armazenamento em cache de arquivos. Para saber mais sobre o armazenamento em cache de arquivos, consulte Usar o armazenamento em cache de arquivos do Cloud Storage FUSE.

Para saber mais sobre downloads paralelos e como configurar propriedades de suporte, Downloads paralelos.

 Valor booleano: true, false. true
O número máximo de goroutines que podem ser gerados a qualquer momento em todos os jobs de download de arquivos.
  • Número inteiro
  • -1: especifica downloads paralelos ilimitados.
  • 0: desativa os downloads paralelos. Só poderá ser usado se --enable-parallel-downloads não for transmitido ou for transmitido como false.
 O dobro do número de núcleos de CPU na máquina ou 16, o que for maior.
O número de solicitações de download simultâneas por arquivo. Número inteiro 16
Especifica bits de permissões para arquivos, em octal. Número inteiro entre 000 e 777 (inclusive). 644
Executa o comando gcsfuse em primeiro plano. Valor booleano: true, false. false
Especifica o proprietário do Identificador de Grupo (GID) de todos os inodes.
  • Número inteiro que representa um GID.
  • -1: o GID do autor da chamada é usado.
 -1
Exibe ajuda sobre o Cloud Storage FUSE. Nenhum Nenhum
Exibe a versão do Cloud Storage FUSE instalada. Nenhum Nenhum
Especifica quanto tempo o cliente HTTP do FUSE do Cloud Storage pode aguardar para receber uma resposta do servidor antes de expirar. Duração, por exemplo: 1h10m10s para 1 hora, 10 minutos e 10 segundos. 0s especifica que não há tempo limite. 0s
Instrui o Cloud Storage FUSE a ignorar sinais de interrupção do sistema, como SIGINT acionado por Control+C. Isso impede indicadores de encerramento de operações em andamento. Valor booleano: true, false. true
Inclui pastas e pastas gerenciadas de maneira implícita. Consulte Arquivos e diretórios na documentação do FUSE do Cloud Storage no GitHub para mais informações. Valor booleano: true, false. false
Ativa a cache da lista e define o time to live (TTL) em segundos de cache na lista de permissões. O cache da lista é mantido na memória do cache da página, que é controlados pelo kernel com base na memória disponível.
  • Número inteiro que representa segundos, por exemplo: 10 (10 segundos).
  • 0: desativa o armazenamento em cache de listas.
  • -1: ignora a expiração da entrada e sempre retorna a resposta da lista do cache quando disponível.
 0
Especifica um caminho absoluto para o arquivo de chave JSON de credencial para autenticar solicitações para o Cloud Storage. Por padrão, o Cloud Storage FUSE usa Application Default Credentials para autenticar solicitações. Um caminho, por exemplo: /home/example_user/gcloud-key.json. Quando essa opção não está definida, as credenciais de aplicativo padrão são usadas.
Especifica o limite de largura de banda em que o Cloud Storage FUSE pode ler dados do Cloud Storage, medidos em uma janela de 30 segundos. Número de ponto flutuante. -1 não especifica um limite. -1
Especifica um limite para operações executadas por segundo, medida em uma janela de 30 segundos. Número de ponto flutuante. -1 não especifica um limite. -1
Especifica o arquivo para armazenar registros que podem ser analisados por Fluentd. Um caminho, por exemplo: /tmp/user-example-bucket-gcsfuse-logs.txt. stdout quando o Cloud Storage FUSE é executado em primeiro plano ou syslog quando o Cloud Storage FUSE é executado em segundo plano
Especifica o formato do arquivo de registros.
  • text
  • json
 json
O número máximo de arquivos de registro rotacionados a serem mantidos, exceto o arquivo ativo em que os registros são gravados.
  • Número inteiro
  • 0: retém todos os arquivos de registro rotacionados.
 10
Especifica se os arquivos de registro rotacionados serão compactados usando gzip. Valor booleano: true, false. true
O tamanho máximo em megabytes (MB) que os arquivos de registro podem alcançar antes de serem rotacionados. Número inteiro. O valor mínimo é 1. 512

O nível de gravidade para o qual você quer que o Cloud Storage FUSE gere registros. Os níveis de gravidade são ordenados do menor para o maior. Por exemplo, quando você especifica warning, o Cloud Storage FUSE gera registros de avisos e erros. Em geral, recomendamos usar o nível de gravidade info.
  • off: desativa toda a geração de registros.
  • error: contém mensagens sobre problemas graves que impedem o Cloud Storage FUSE de concluir uma operação ou indicam uma falha, como falhas de montagem, erros de permissão e erros críticos de entrada/saída (E/S).
  • warning: contém mensagens que indicam possíveis problemas que não são críticos, mas podem causar problemas se não forem resolvidos. Os possíveis problemas incluem questões de conexão não fatais, avisos de descontinuação, disputa de recursos que pode causar uma pequena degradação de desempenho e novas tentativas para falhas temporárias. Esse nível de gravidade também inclui informações fornecidas no nível error.
  • info: contém informações gerais de geração de registros, como mensagens de inicialização e desligamento, ou informações sobre operações de montagem bem-sucedidas, atualizações de progresso e configurações de configuração. Esse nível de gravidade também inclui informações sobre os níveis warning e error.
  • debug: contém informações de registro, como mensagens de inicialização e desligamento, ou informações sobre operações de montagem bem-sucedidas, atualizações de progresso e configurações de configuração. Esse nível de gravidade também inclui as informações fornecidas nos níveis info, warning e error.
  • trace: contém detalhes granulares sobre cada operação e chamada de função do Cloud Storage FUSE, descrevendo a interação gcsfuse com o driver FUSE do kernel e o Cloud Storage. Esse nível de gravidade também inclui os detalhes fornecidos nos níveis debug, info, warning e error.
 info
Especifica o número máximo de conexões TCP permitidas por servidor. Isso entra em vigor quando --client-protocol é definido como http1. Número inteiro entre 0 e 2147483647. 0 especifica que não há limite nas conexões TCP. 0
Especifica o número máximo de conexões inativas permitidas por servidor. Isso entra em vigor quando --client-protocol é definido como http1. Número inteiro entre 0 e 2147483647. 0 não especifica um limite para conexões ociosas. 0
Especifica o número máximo de vezes que uma operação é repetida se ela falhar, evitando loops de repetição sem fim.
  • Número inteiro que representa o número máximo de novas tentativas, por exemplo: 10.
  • 0: permite tentativas ilimitadas.
 0
Especifica a duração máxima que o Cloud Storage FUSE pode ficar suspenso em um loop de nova tentativa com espera exponencial. Quando a duração de espera excede a duração máxima especificada, a nova tentativa continua com a duração máxima especificada. Duração, por exemplo: 1h5m50s (1 hora, 5 minutos e 50 segundos) ou 60s (60 segundos). 30s

Define o time to live (TTL) em segundos das entradas do cache de estatísticas negativas, que armazenam resultados de arquivos não existentes no cache.
  • Número inteiro que representa segundos, por exemplo: 10 (10 segundos).
  • 0: desativa o armazenamento em cache de estatísticas negativas.
  • -1: permite o armazenamento em cache negativo ilimitado de estatísticas e desativa uma expiração de TTL.
 5
Define o time to live (TTL), em segundos, das entradas de metadados armazenadas em cache.
  • Número inteiro que representa segundos, por exemplo: 30 (30 segundos).
  • -1: ignora a expiração de TTL e disponibiliza arquivos do cache sempre que eles estão disponíveis.
  • 0: use o arquivo mais atualizado. O uso desse valor emite uma chamada de metadados Get para garantir que a geração do objeto para o arquivo no cache corresponda ao que está armazenado no Cloud Storage. Para saber mais, consulte Como configurar a invalidação de cache.
 60
Especifica outras opções de ativação específicas do sistema. A maioria das opções de ativação genéricas em FUSE, como suid, é compatível com o Cloud Storage FUSE e pode ser transmitida com a opção -o. Opções de ativação no FUSE, por exemplo:
  • rw: montar como leitura/gravação.
  • ro: montar como somente leitura.
 ""
Ativa apenas um diretório específico em um bucket. Um caminho, por exemplo: /etc/gcsfuse.yaml. ""

Expõe o endpoint de métricas do Prometheus na porta especificada e no caminho /metrics.

 Número inteiro que representa a porta que você quer especificar. 0

Especifica o número máximo de blocos disponíveis para leituras em buffer em todos os identificadores de arquivo.
  • Número inteiro
  • 0: desativa as leituras em buffer.
  • -1: define o valor como blocos ilimitados.
 40
Permite renomear os diretórios que contêm menos descendentes do que o limite especificado. Número inteiro entre 0 e 2147483647. 0
Especifica o multiplicador para a espera exponencial entre tentativas consecutivas. Número de ponto flutuante. 2
Especifica se o token adquirido de --token-url será reutilizado. Valor booleano: true, false. true
Especifica o tamanho do bloco dos dados a serem baixados do Cloud Storage, em megabytes (MB). Número inteiro entre 1 e 1024. 200
Especifica o número de entradas que o cache de estatísticas pode conter. Essa opção gcsfuse foi substituída pela opção --stat-cache-max-size-mb gcsfuse. Número inteiro 4096
A memória de tamanho máximo que o cache de estatísticas pode usar, em MiB. O cache de estatísticas é sempre mantido por completo na memória.
  • Número inteiro. Recomendamos o seguinte:
    • 32 se a carga de trabalho envolver até 20.000 arquivos.
    • Se a carga de trabalho for maior que 20.000 arquivos, aumente o tamanho em valores de 10 para cada 6.000 arquivos adicionais, em que o cache de estatísticas usa uma média de 1.500 MiB por arquivo.
  • -1: não define um limite, e o cache de estatísticas usa a quantidade de memória necessária.
  • 0: desativa o cache de estatísticas.
 32
Especifica por quanto tempo os resultados de StatObject e os atributos de nó são armazenados em cache. Essa opção foi substituída pela --metadata-cache-ttl-secs gcsfuse. Duração, por exemplo: 20s (20 segundos). 60s
Especifica um caminho para o diretório temporário em que as gravações são testadas antes do upload para o Cloud Storage. Um caminho, por exemplo: /mnt/ssd/example-user-gcsfuse-temp-dir. /tmp
Especifica um URL para receber um token de acesso quando --key-file estiver ausente. Um URL. ""
Especifica por quanto tempo o mapeamento em cache entre nomes e arquivos ou diretórios será armazenado em cache em inodes do diretório, em segundos. Essa opção gcsfuse foi substituída pela opção --metadata-cache-ttl-secs gcsfuse. Duração em segundos, por exemplo: 20s (20 segundos). 60s
O tamanho máximo em MiB por diretório que o cache de tipos pode usar. O cache de tipos é sempre totalmente mantido na memória.
  • Número inteiro. Recomendamos o seguinte:
    • 4 se o número máximo de arquivos em um único diretório do bucket que você está ativando contiver 20.000 arquivos ou menos.
    • Se o número máximo de arquivos em um único diretório ativado tiver mais de 20.000 arquivos, aumente o valor por 1 para cada 5.000 arquivos, uma média de aproximadamente 200 bytes por arquivo.
  • -1: não especifica um limite e permite que o cache de tipos use a quantidade de memória necessária.
  • 0: desativa o cache de tipos.
 4
Especifica o proprietário do identificador de usuário (UID, na sigla em inglês) de todos os nós.
  • Número inteiro que representa um UID.
  • -1: o UID do caller é usado.
 -1

Especifica o número máximo de partes de dados disponíveis para gravações de streaming em todos os arquivos. Cada arquivo usa um bloco de dados de 32 MiB por padrão.
  • Número inteiro
  • 0: desativa gravações de streaming.
  • -1: define o valor como blocos ilimitados.
  • Valor padrão para máquinas de baixa especificação com recursos limitados: 4
  • Valor padrão para máquinas de alta especificação com uma grande quantidade de recursos: 1600

Voltar ao início