Fichier de configuration boto

Cette page explique comment gsutil utilise un fichier de configuration boto et fournit un exemple de collaboration qui utilise ce fichier. Le fichier de configuration boto est également utilisé par boto, qui est le SDK Amazon S3 pour Python.

Présentation du fichier de configuration

Le fichier de configuration boto contient des valeurs qui contrôlent le comportement de gsutil. Par exemple, la variable prefer_api détermine quelle API gsutil privilégie. Vous pouvez modifier les variables du fichier de configuration boto en modifiant directement le fichier de configuration. Même si la plupart des utilisateurs n'ont pas besoin de modifier ces variables, ils le font généralement pour l'une des raisons suivantes :

Emplacement

L'emplacement par défaut du fichier de configuration boto se trouve dans le répertoire d'accueil de l'utilisateur, ~/.boto, pour Linux et macOS, et dans %HOMEDRIVE%%HOMEPATH% pour Windows. La commande gsutil version -l permet d'obtenir l'emplacement du fichier de configuration.

Vous pouvez remplacer l'emplacement où gsutil s'attend à trouver le fichier de configuration en définissant la variable d'environnement BOTO_CONFIG. Vous pouvez également définir un chemin de chargement des fichiers de configuration boto en définissant la variable d'environnement BOTO_PATH à l'aide d'un chemin d'accès délimité par : (ou ; pour Windows). Par exemple, définissez la variable d'environnement BOTO_PATH sur :

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

gsutil charge alors chaque fichier de configuration trouvé dans le chemin d'accès dans l'ordre. Cette fonctionnalité est utile si vous souhaitez configurer un état de configuration partagé entre de nombreux utilisateurs. Consultez l'exemple d'utilisation du fichier de configuration pour découvrir un tel scénario de partage de données et de collaboration.

Structure

Le fichier de configuration contient plusieurs sections : [Credentials], [Boto], [GSUtil] et [OAuth2]. Les paramètres de configuration actuellement définis, répartis par section, sont les suivants : Leur utilisation est documentée dans le fichier de configuration boto, dans les commentaires précédant chaque paramètre :

[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

Lorsque vous modifiez le fichier, veillez à ne pas modifier les noms de paramètres, tels que gs_access_key_id, et à ne pas supprimer les délimiteurs de section, tels que [Credentials].

Mise à jour vers le dernier fichier de configuration

De nouvelles fonctionnalités contrôlables sont ajoutées au fichier de configuration boto au fil du temps. Néanmoins, la plupart des utilisateurs de gsutil ne créent un fichier de configuration qu'une seule fois, et le conservent pendant une longue période. Dans ce cas, les nouvelles fonctionnalités n'apparaissent pas lorsque vous passez à une version plus récente de gsutil. Si vous souhaitez obtenir le fichier de configuration le plus récent, qui inclut les paramètres et la documentation les plus récents, renommez votre fichier actuel (par exemple, .boto_old), exécutez gsutil config ou gcloud init, puis transférez les paramètres de configuration que vous souhaitez conserver de votre ancien fichier vers le nouveau fichier. Notez cependant que si vous utilisez des identifiants OAuth2 et que vous suivez à nouveau le processus de configuration OAuth2, vos identifiants OAuth2 précédents ne seront plus valides.

Exemple d'utilisation du fichier de configuration

Dans cet exemple, une PME souhaite utiliser Cloud Storage comme système de stockage pour ses employés. En tant qu'administrateur informatique, vous créez un projet dans Google Cloud Console, puis créez des buckets pour chaque employé. Pour faciliter l'utilisation de Cloud Storage par les employés, vous souhaitez créer et stocker des paramètres à l'échelle de l'entreprise, tels qu'une configuration du proxy et des seuils d'importation composite parallèle, dans un fichier central que les employés peuvent indiquer dans leur chemin de configuration BOTO. Cela évite à chaque employé de définir manuellement les parties partagées de la configuration et vous permet, en tant qu'administrateur, de modifier facilement ces configurations partagées si nécessaire.

Pour ce faire, procédez comme suit :

  1. Créez un fichier central de configuration boto lisible par tous les employés.

    Pour ce faire, utilisez gcloud init lorsque gsutil est installé dans le cadre du SDK Google Cloud.

    Le fichier de configuration boto peut par exemple contenir les données suivantes :

    [Boto]
    proxy = yourproxy.com
    proxy_port = 8080
    proxy_type = http
     
    [GSUtil]
    parallel_composite_upload_threshold = 150M
    
  2. Demandez aux employés d'installer le SDK Google Cloud.

    Lors de l'installation, les employés doivent spécifier l'ID de projet utilisé par l'entreprise. Ils doivent également générer des identifiants d'authentification individuels, car vous ne devez pas partager ces identifiants de manière centralisée.

  3. Demandez aux employés d'ajouter une variable d'environnement BOTO_PATH.

    La variable d'environnement BOTO_PATH répertorie le chemin d'accès du fichier central de configuration, suivi du fichier local de configuration de l'employé. Par exemple, si le fichier central de configuration se trouve dans le répertoire centralhub/, pour l'utilisateur jane, la variable d'environnement BOTO_PATH peut être :

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

Lorsque les employés exécutent gsutil, ils utilisent automatiquement la configuration spécifiée dans le fichier boto central. Si nécessaire, l'administrateur peut modifier les paramètres de proxy, le seuil d'importation composite parallèle et d'autres paramètres dans le fichier central de configuration, et faire en sorte que les modifications soient appliquées pour tous les employés à l'aide de ce fichier.