Arquivo de configuração do boto

Esta página descreve como a gsutil usa um arquivo de configuração do boto e fornece um exemplo de colaboração que usa o arquivo. O arquivo de configuração do boto também é usado pelo boto, que é o SDK do Amazon S3 para Python.

Visão geral do arquivo de configuração

O arquivo de configuração boto contém valores que controlam o comportamento da gsutil. Por exemplo, a variável prefer_api determina qual API a gsutil usa preferencialmente. As variáveis do arquivo de configuração boto podem ser alteradas editando o arquivo de configuração diretamente. Embora a maioria dos usuários não precise editar essas variáveis, elas geralmente fazem isso por um dos seguintes motivos:

Local

O local padrão do arquivo de configuração boto é o diretório inicial do usuário, ~/.boto, para Linux e macOS, e %HOMEDRIVE%%HOMEPATH%, para Windows. Para ver o local do arquivo de configuração, execute o comando gsutil version -l.

Você pode modificar onde a gsutil espera encontrar o arquivo de configuração definindo a variável de ambiente BOTO_CONFIG. Também é possível configurar um caminho de arquivos de configuração boto para carregar definindo a variável de ambiente BOTO_PATH usando um caminho delimitado por : (ou ; para Windows). Por exemplo, definindo a variável de ambiente BOTO_PATH como:

/etc/projects/my_group_project.boto.cfg:/home/mylogin/.boto

faz com que a gsutil carregue cada arquivo de configuração encontrado no caminho em ordem. Isso é útil se você quiser definir algum estado de configuração compartilhado entre muitos usuários. Veja o exemplo de uso do arquivo de configuração para esse cenário de compartilhamento e colaboração de dados.

Estrutura

O arquivo de configuração contém várias seções: [Credentials], [Boto], [GSUtil] e [OAuth2]. Veja a seguir as definições de configuração definidas atualmente, divididas por seção. O uso deles é documentado no próprio arquivo de configuração boto, nos comentários anteriores a cada configuração:

[Credentials]
  aws_access_key_id
  aws_secret_access_key
  gs_access_key_id
  gs_host
  gs_host_header
  gs_json_host
  gs_json_host_header
  gs_json_port
  gs_oauth2_refresh_token
  gs_port
  gs_secret_access_key
  gs_service_client_id
  gs_service_key_file
  gs_service_key_file_password
  s3_host
  s3_host_header
  s3_port

[Boto]
  proxy
  proxy_type
  proxy_port
  proxy_user
  proxy_pass
  proxy_rdns
  http_socket_timeout
  ca_certificates_file
  https_validate_certificates
  debug
  max_retry_delay
  num_retries

[GoogleCompute]
  service_account

[GSUtil]
  check_hashes
  content_language
  decryption_key1 ... 100
  default_api_version
  default_project_id
  disable_analytics_prompt
  encryption_key
  json_api_version
  max_upload_compression_buffer_size
  parallel_composite_upload_component_size
  parallel_composite_upload_threshold
  sliced_object_download_component_size
  sliced_object_download_max_components
  sliced_object_download_threshold
  parallel_process_count
  parallel_thread_count
  gzip_compression_level
  prefer_api
  resumable_threshold
  resumable_tracker_dir (deprecated in 4.6, use state_dir)
  rsync_buffer_lines
  software_update_check_period
  state_dir
  tab_completion_time_logs
  tab_completion_timeout
  task_estimation_threshold
  test_cmd_regional_bucket_location
  test_notification_url
  use_magicfile
  test_hmac_service_account
  test_hmac_alt_service_account
  test_hmac_list_service_account

[OAuth2]
  client_id
  client_secret
  oauth2_refresh_retries
  provider_authorization_uri
  provider_label
  provider_token_uri
  token_cache

Ao editar o arquivo, tenha cuidado para não editar os nomes de configuração, como gs_access_key_id, e não remova os delimitadores de seção, como [Credentials].

Como atualizar para o arquivo de configuração mais recente

Novos recursos controláveis de configuração são adicionados ao arquivo de configuração boto ao longo do tempo, mas a maioria dos usuários da gsutil cria um arquivo de configuração uma vez e o mantém por muito tempo. Isso significa que os novos recursos não são aparentes, quando você atualiza para uma versão mais recente da gsutil. Se você quiser receber o arquivo de configuração mais recente, que inclui as configurações e a documentação mais recentes, renomeie o arquivo atual (por exemplo, para .boto_old), execute gsutil config ou gcloud init e transfira as definições de configuração que quiser manter do seu arquivo antigo para o arquivo recém-criado. No entanto, se você estiver usando credenciais do OAuth2 e voltar ao processo de configuração do OAuth2, isso invalidará suas credenciais anteriores do OAuth2.

Exemplo usando o arquivo de configuração

Neste exemplo, uma pequena empresa quer usar o Cloud Storage como sistema de armazenamento para os funcionários. Como administrador de TI, você cria um projeto no Console do Google Cloud e cria buckets para cada funcionário. Para facilitar o uso do Cloud Storage pelos funcionários, o administrador quer criar e armazenar as configurações para toda a empresa (como uma configuração de proxy e limites de upload composto paralelo) em um arquivo central que os funcionários possam apontar como caminho de configuração BOTO. Isso elimina a necessidade de cada funcionário definir manualmente as partes compartilhadas da configuração e permite que o administrador altere com facilidade essas configurações compartilhadas, se necessário.

Para isso, é necessário realizar as seguintes etapas:

  1. Criar um arquivo central de configuração boto que seja legível para todos os funcionários.

    Isso pode ser feito usando gcloud init quando a gsutil é instalada como parte do SDK do Google Cloud.

    O arquivo de configuração boto pode conter, por exemplo:

    [Boto]
    proxy = yourproxy.com
    proxy_port = 8080
    proxy_type = http
     
    [GSUtil]
    parallel_composite_upload_threshold = 150M
    
  2. Instruir os funcionários a instalar o SDK do Google Cloud.

    Durante a instalação, os funcionários precisam especificar o ID do projeto que a empresa está usando. Eles também precisam gerar credenciais de autenticação individuais porque você nunca pode compartilhar credenciais de autenticação centralmente.

  3. Instruir os funcionários a adicionar uma variável de ambiente BOTO_PATH.

    A variável de ambiente BOTO_PATH indica o caminho do arquivo de configuração localizado centralmente, seguido pelo arquivo de configuração local do funcionário. Por exemplo, se o arquivo de configuração central estiver localizado no diretório centralhub/, para o usuário jane, a variável de ambiente BOTO_PATH poderá ser:

    BOTO_PATH =/centralhub/boto.cfg:home/jane/.boto

Quando os funcionários executam o gsutil, usam automaticamente a configuração especificada no arquivo boto central. Se necessário, o administrador pode alterar as configurações de proxy, o limite de upload composto paralelo e outras definições no arquivo de configuração central e refletir essas alterações para todos os funcionários usando esse arquivo.