Stockage d'objets

{{< details >}}

• Édition : Gratuite, GitLab Premium, GitLab Ultimate
• Offre : GitLab Self-Managed

{{< /details >}}

GitLab prend en charge l'utilisation d'un service de stockage d'objets pour héberger de nombreux types de données. Il est recommandé par rapport à NFS et, en général, il est préférable dans les configurations plus importantes, car le stockage d'objets est généralement beaucoup plus performant, fiable et évolutif.

Pour configurer le stockage d'objets, vous disposez de deux options :

• Recommandé. Configurer une connexion de stockage unique pour tous les types d'objets : Un seul identifiant est partagé par tous les types d'objets pris en charge. C'est ce qu'on appelle le formulaire consolidé.

• Configurer chaque type d'objet pour définir sa propre connexion de stockage : Chaque objet définit sa propre connexion et configuration de stockage d'objets. C'est ce qu'on appelle le formulaire spécifique au stockage.

  Si vous utilisez déjà le formulaire spécifique au stockage, découvrez comment passer au formulaire consolidé.

Si vous stockez des données localement, découvrez comment migrer vers le stockage d'objets.

Prise en charge des fournisseurs de stockage d'objets {#object-storage-provider-support}

GitLab utilise la bibliothèque Fog pour le stockage d'objets et prend en charge les trois types de connexion suivants. Les autres fournisseurs Fog ne sont pas pris en charge.

Si votre service de stockage d'objets est compatible avec l'un de ces types de connexion, configurez-le en utilisant les paramètres de connexion correspondants ci-dessous. Le choix du fournisseur vous appartient.

Fournisseurs avec couverture de test active {#providers-with-active-test-coverage}

GitLab teste activement les fournisseurs suivants :

• Amazon S3 - type de connexion AWS. Object Lock n'est pas pris en charge. Pour plus d'informations, consultez le ticket 335775.
• Google Cloud Storage - type de connexion Google.
• Azure Blob Storage - type de connexion AzureRM.

Fournisseurs documentés par la communauté {#community-documented-providers}

Les fournisseurs suivants ont été documentés par la communauté. GitLab ne teste pas ces fournisseurs. Des exemples de configuration sont fournis à titre de commodité. Si vous utilisez l'un de ces fournisseurs et rencontrez des problèmes, le support GitLab pourrait ne pas être en mesure de vous aider.

• Digital Ocean Spaces. Compatible S3, consultez les exemples de configuration spécifiques aux fournisseurs.
• Oracle Cloud Infrastructure. Compatible S3, consultez les exemples de configuration spécifiques aux fournisseurs.
• OpenStack Swift (mode compatible S3).
• Storj Gateway. Compatible S3, consultez les exemples de configuration spécifiques aux fournisseurs.
• Ceph RGW. Compatible S3, consultez les exemples de configuration spécifiques aux fournisseurs
• Hitachi Vantara HCP. Compatible S3, consultez les exemples de configuration spécifiques aux fournisseurs.
• Matériel et appliances sur site qui exposent une API compatible S3.

Configurer une connexion de stockage unique pour tous les types d'objets (formulaire consolidé) {#configure-a-single-storage-connection-for-all-object-types-consolidated-form}

La plupart des types d'objets, tels que les artefacts CI, les fichiers LFS et les pièces jointes importées, peuvent être enregistrés dans le stockage d'objets en spécifiant un seul identifiant pour le stockage d'objets avec plusieurs buckets.

[!note] Pour les charts Helm GitLab, découvrez comment configurer le formulaire consolidé.

La configuration du stockage d'objets à l'aide du formulaire consolidé présente plusieurs avantages :

• Cela peut simplifier votre configuration GitLab, car les détails de connexion sont partagés entre les types d'objets.
• Cela permet l'utilisation de buckets S3 chiffrés.
• Il importe les fichiers vers S3 avec les en-têtes Content-MD5 appropriés.

Lorsque le formulaire consolidé est utilisé, l'importation directe est activée automatiquement. Ainsi, seuls les fournisseurs suivants peuvent être utilisés :

• Fournisseurs compatibles S3
• Google Cloud Storage
• Azure Blob storage

La configuration du formulaire consolidé ne peut pas être utilisée pour les sauvegardes ou Mattermost. Les sauvegardes peuvent être configurées séparément avec le chiffrement côté serveur. Consultez le tableau pour la liste complète des types de stockage d'objets pris en charge.

L'activation du formulaire consolidé active le stockage d'objets pour tous les types d'objets. Si tous les buckets ne sont pas spécifiés, vous pourriez voir une erreur telle que :

Object storage for <object type> must have a bucket specified

Si vous souhaitez utiliser le stockage local pour des types d'objets spécifiques, vous pouvez désactiver le stockage d'objets pour des fonctionnalités spécifiques.

Configurer les paramètres communs {#configure-the-common-parameters}

Dans le formulaire consolidé, la section object_store définit un ensemble commun de paramètres.

Pour un exemple, découvrez comment utiliser le formulaire consolidé et Amazon S3.

Configurer les paramètres de chaque objet {#configure-the-parameters-of-each-object}

Chaque type d'objet doit au moins définir le nom du bucket dans lequel il sera stocké.

Le tableau suivant répertorie les objects valides qui peuvent être utilisés :

Au sein de chaque type d'objet, trois paramètres peuvent être définis :

Pour un exemple, découvrez comment utiliser le formulaire consolidé et Amazon S3.

Désactiver le stockage d'objets pour des fonctionnalités spécifiques {#disable-object-storage-for-specific-features}

Comme vu précédemment, le stockage d'objets peut être désactivé pour des types spécifiques en définissant le flag enabled sur false. Par exemple, pour désactiver le stockage d'objets pour les artefacts CI :

gitlab_rails['object_store']['objects']['artifacts']['enabled'] = false

Un bucket n'est pas nécessaire si la fonctionnalité est entièrement désactivée. Par exemple, aucun bucket n'est nécessaire si les artefacts CI sont désactivés avec ce paramètre :

gitlab_rails['artifacts_enabled'] = false

Configurer chaque type d'objet pour définir sa propre connexion de stockage (formulaire spécifique au stockage) {#configure-each-object-type-to-define-its-own-storage-connection-storage-specific-form}

Avec le formulaire spécifique au stockage, chaque objet définit sa propre connexion et configuration de stockage d'objets. Vous devriez utiliser le formulaire consolidé à la place, sauf pour les types de stockage non pris en charge par le formulaire consolidé. Lorsque vous utilisez les charts Helm GitLab, référez-vous à la façon dont les charts gèrent le formulaire consolidé pour le stockage d'objets.

L'utilisation des buckets S3 chiffrés avec le formulaire non consolidé n'est pas prise en charge. Vous pouvez obtenir des erreurs de non-correspondance ETag si vous l'utilisez.

[!note] Pour le formulaire spécifique au stockage, l'importation directe peut devenir la valeur par défaut car elle ne nécessite pas de dossier partagé.

Pour les types de stockage non pris en charge par le formulaire consolidé, reportez-vous aux guides suivants :

Configurer les paramètres de connexion {#configure-the-connection-settings}

Les formulaires consolidé et spécifique au stockage doivent tous deux configurer une connexion. Les sections suivantes décrivent les paramètres pouvant être utilisés dans le paramètre connection.

Fournisseurs compatibles S3 {#s3-compatible-providers}

Ces paramètres s'appliquent à Amazon S3 et à tout service compatible S3 utilisant le type de connexion AWS. Lorsque vous n'utilisez pas AWS directement, définissez endpoint sur l'URL de votre fournisseur.

Les services compatibles S3 varient dans la façon dont ils implémentent l'API AWS S3. GitLab utilise des comportements S3 spécifiques, notamment les URL pré-signées, les importations en plusieurs parties et, en option, la diffusion de signatures fragmentées, que toutes les implémentations compatibles S3 ne prennent pas en charge de manière identique. Si un fournisseur fonctionne avec d'autres outils mais pas avec GitLab, les paramètres qui nécessitent le plus probablement un ajustement sont :

• aws_signature_version.
• enable_signature_v4_streaming.

Les paramètres de connexion correspondent à ceux fournis par fog-aws :

Compatibilité S3 et modes d'échec connus {#s3-compatibility-and-known-failure-modes}

Revendiquer la compatibilité S3 ne garantit pas qu'un fournisseur fonctionne correctement avec GitLab. Si vous rencontrez des erreurs avec un fournisseur compatible S3, essayez les ajustements suivants avant de soumettre une demande de support :

• Signature streaming : Certains fournisseurs rejettent l'encodage de transfert fragmenté utilisé par la diffusion AWS Signature Version 4. Définir enable_signature_v4_streaming: false.
• Signature version : Certains fournisseurs ne prennent pas entièrement en charge Signature Version 4. Définir aws_signature_version: 2.
• Path-style URLs : Certains fournisseurs nécessitent un adressage de bucket par chemin. Définir path_style: true.
• ETag validation : Certains fournisseurs renvoient des ETags qui ne correspondent pas au MD5 de l'objet importé, que GitLab valide. Consultez Non-correspondance ETag.

Le support GitLab peut vous aider à résoudre les problèmes de configuration, mais ne peut pas garantir la résolution des problèmes spécifiques aux fournisseurs qui ne font pas partie de l'ensemble testé.

Utiliser des profils d'instance Amazon {#use-amazon-instance-profiles}

Au lieu de fournir des clés d'accès et secrètes AWS dans la configuration du stockage d'objets, vous pouvez configurer GitLab pour utiliser les rôles Amazon Identity Access and Management (IAM) afin de configurer un profil d'instance Amazon. Lorsque cette option est utilisée, GitLab récupère des identifiants temporaires chaque fois qu'un bucket S3 est accédé, de sorte qu'aucune valeur codée en dur n'est nécessaire dans la configuration.

Prérequis :

• GitLab doit être en mesure de se connecter au point de terminaison des métadonnées d'instance.
• Si GitLab est configuré pour utiliser un proxy Internet, l'adresse IP du point de terminaison doit être ajoutée à la liste no_proxy.
• Pour l'accès IMDS v2, assurez-vous que la limite de sauts est suffisante. Si GitLab s'exécute dans un conteneur, vous devrez peut-être augmenter la limite de 1 à 2.

Pour configurer un profil d'instance :

1. Créez un rôle IAM avec les autorisations nécessaires. L'exemple suivant est un rôle pour un bucket S3 nommé test-bucket :

   jsonCopy

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "s3:PutObject",
                   "s3:GetObject",
                   "s3:DeleteObject"
               ],
               "Resource": "arn:aws:s3:::test-bucket/*"
           },
           {
               "Effect": "Allow",
               "Action": [
                   "s3:ListBucket"
               ],
               "Resource": "arn:aws:s3:::test-bucket"
           }
       ]
   }
   

2. Associez ce rôle à l'instance EC2 hébergeant votre instance GitLab.

3. Définissez l'option de configuration GitLab use_iam_profile sur true.

Buckets S3 chiffrés {#encrypted-s3-buckets}

Lorsqu'il est configuré avec un profil d'instance ou avec le formulaire consolidé, GitLab Workhorse importe correctement les fichiers vers des buckets S3 dont le chiffrement SSE-S3 ou SSE-KMS est activé par défaut. Les clés AWS KMS et le chiffrement SSE-C ne sont pas pris en charge car cela nécessite l'envoi des clés de chiffrement dans chaque requête.

En-têtes de chiffrement côté serveur {#server-side-encryption-headers}

Définir un chiffrement par défaut sur un bucket S3 est le moyen le plus simple d'activer le chiffrement, mais vous pouvez définir une politique de bucket pour garantir que seuls les objets chiffrés sont importés. Pour ce faire, vous devez configurer GitLab pour envoyer les en-têtes de chiffrement appropriés dans la section de configuration storage_options :

Comme dans le cas du chiffrement par défaut, ces options ne fonctionnent que lorsque le client S3 Workhorse est activé. L'une des deux conditions suivantes doit être remplie :

• use_iam_profile est true dans les paramètres de connexion.
• Le formulaire consolidé est utilisé.

Des erreurs de non-correspondance ETag se produisent si des en-têtes de chiffrement côté serveur sont utilisés sans activer le client S3 Workhorse.

Google Cloud Storage (GCS) {#google-cloud-storage-gcs}

{{< history >}}

• Le paramètre universe_domain introduit dans GitLab 18.9.

{{< /history >}}

Voici les paramètres de connexion valides pour GCS :

GitLab lit la valeur de google_json_key_location, puis google_json_key_string, et enfin google_application_default. Il utilise le premier de ces paramètres qui a une valeur.

Le compte de service doit avoir l'autorisation d'accéder au bucket. Pour plus d'informations, consultez la documentation sur l'authentification Cloud Storage.

Identifiants par défaut des applications Google Cloud {#google-cloud-application-default-credentials}

Les identifiants par défaut des applications Google Cloud (ADC) sont généralement utilisés avec GitLab pour utiliser le compte de service par défaut ou la fédération d'identité de charge de travail. Définissez google_application_default sur true et omettez google_json_key_location et google_json_key_string.

Si vous utilisez ADC, assurez-vous que :

• Le compte de service que vous utilisez dispose de l'autorisation iam.serviceAccounts.signBlob. Cela se fait généralement en accordant le rôle Service Account Token Creator au compte de service.

• Si vous utilisez des machines virtuelles Google Compute, assurez-vous qu'elles disposent des portées d'accès correctes pour accéder aux API Google Cloud. Si les machines ne disposent pas de la bonne portée, les journaux d'erreurs peuvent afficher :

  shellCopy

  Google::Apis::ClientError (insufficientPermissions: Request had insufficient authentication scopes.)
  

[!note] Pour utiliser le chiffrement de bucket avec des clés de chiffrement gérées par le client, utilisez le formulaire consolidé.

{{< tabs >}}

{{< tab title="Linux package (Omnibus)" >}}

1. Modifiez /etc/gitlab/gitlab.rb et ajoutez les lignes suivantes, en remplaçant les valeurs souhaitées :

   rubyCopy

   gitlab_rails['object_store']['connection'] = {
    'provider' => 'Google',
    'google_project' => '<GOOGLE PROJECT>',
    'google_json_key_location' => '<FILENAME>'
   }
   

   Pour utiliser ADC, utilisez plutôt google_application_default :

   rubyCopy

   gitlab_rails['object_store']['connection'] = {
    'provider' => 'Google',
    'google_project' => '<GOOGLE PROJECT>',
    'google_application_default' => true
   }
   

   Pour utiliser un domaine universe non défini par défaut (par exemple, Google Cloud Dedicated) :

   rubyCopy

   gitlab_rails['object_store']['connection'] = {
    'provider' => 'Google',
    'google_project' => '<GOOGLE PROJECT>',
    'google_application_default' => true,
    'universe_domain' => '<UNIVERSE DOMAIN>'
   }
   

2. Enregistrez le fichier et reconfigurez GitLab :

   shellCopy

   sudo gitlab-ctl reconfigure
   

{{< /tab >}}

{{< tab title="Helm chart (Kubernetes)" >}}

1. Placez le contenu suivant dans un fichier nommé object_storage.yaml à utiliser comme Secret Kubernetes :

   yamlCopy

   provider: Google
   google_project: <GOOGLE PROJECT>
   google_json_key_location: '<FILENAME>'
   

   Pour utiliser ADC, utilisez plutôt google_application_default :

   yamlCopy

   provider: Google
   google_project: <GOOGLE PROJECT>
   google_application_default: true
   

   Pour utiliser un domaine universe non défini par défaut (par exemple, Google Cloud Dedicated) :

   yamlCopy

   provider: Google
   google_project: <GOOGLE PROJECT>
   google_application_default: true
   universe_domain: <UNIVERSE DOMAIN>
   

2. Créez le Secret Kubernetes :

   shellCopy

   kubectl create secret generic -n <namespace> gitlab-object-storage --from-file=connection=object_storage.yaml
   

3. Exportez les valeurs Helm :

   shellCopy

   helm get values gitlab > gitlab_values.yaml
   

4. Modifiez gitlab_values.yaml :

   yamlCopy

   global:
     appConfig:
        artifacts:
          bucket: gitlab-artifacts
        ciSecureFiles:
          bucket: gitlab-ci-secure-files
          enabled: true
        dependencyProxy:
          bucket: gitlab-dependency-proxy
          enabled: true
        externalDiffs:
          bucket: gitlab-mr-diffs
          enabled: true
        lfs:
          bucket: gitlab-lfs
        object_store:
          connection:
            secret: gitlab-object-storage
          enabled: true
          proxy_download: false
        packages:
          bucket: gitlab-packages
        terraformState:
          bucket: gitlab-terraform-state
          enabled: true
        uploads:
          bucket: gitlab-uploads
   

5. Enregistrez le fichier et appliquez les nouvelles valeurs :

   shellCopy

   helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
   

{{< /tab >}}

{{< tab title="Docker" >}}

1. Modifiez docker-compose.yml :

   yamlCopy

   version: "3.6"
   services:
     gitlab:
       environment:
         GITLAB_OMNIBUS_CONFIG: |
           # Consolidated object storage configuration
           gitlab_rails['object_store']['enabled'] = true
           gitlab_rails['object_store']['proxy_download'] = false
           gitlab_rails['object_store']['connection'] = {
             'provider' => 'Google',
             'google_project' => '<GOOGLE PROJECT>',
             'google_json_key_location' => '<FILENAME>'
           }
           gitlab_rails['object_store']['objects']['artifacts']['bucket'] = 'gitlab-artifacts'
           gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = 'gitlab-mr-diffs'
           gitlab_rails['object_store']['objects']['lfs']['bucket'] = 'gitlab-lfs'
           gitlab_rails['object_store']['objects']['uploads']['bucket'] = 'gitlab-uploads'
           gitlab_rails['object_store']['objects']['packages']['bucket'] = 'gitlab-packages'
           gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = 'gitlab-dependency-proxy'
           gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = 'gitlab-terraform-state'
           gitlab_rails['object_store']['objects']['ci_secure_files']['bucket'] = 'gitlab-ci-secure-files'
           gitlab_rails['object_store']['objects']['pages']['bucket'] = 'gitlab-pages'
   

   Pour utiliser ADC, utilisez plutôt google_application_default :

   rubyCopy

   gitlab_rails['object_store']['connection'] = {
     'provider' => 'Google',
     'google_project' => '<GOOGLE PROJECT>',
     'google_application_default' => true
   }
   

   Pour utiliser un domaine universe non défini par défaut (par exemple, Google Cloud Dedicated) :

   rubyCopy

   gitlab_rails['object_store']['connection'] = {
     'provider' => 'Google',
     'google_project' => '<GOOGLE PROJECT>',
     'google_application_default' => true,
     'universe_domain' => '<UNIVERSE DOMAIN>'
   }
   

2. Enregistrez le fichier et redémarrez GitLab :

   shellCopy

   docker compose up -d
   

{{< /tab >}}

{{< /tabs >}}

Azure Blob storage {#azure-blob-storage}

Bien qu'Azure utilise le terme container pour désigner une collection de blobs, GitLab standardise le terme bucket. Assurez-vous de configurer les noms de conteneurs Azure dans les paramètres bucket.

Azure Blob storage ne peut être utilisé qu'avec le formulaire consolidé, car un seul ensemble d'identifiants est utilisé pour accéder à plusieurs conteneurs. Le formulaire spécifique au stockage n'est pas pris en charge. Pour plus de détails, consultez comment passer au formulaire consolidé.

Les paramètres de connexion valides pour Azure sont les suivants. Pour plus d'informations, consultez la documentation Azure Blob Storage.

{{< tabs >}}

{{< tab title="Linux package (Omnibus)" >}}

1. Modifiez /etc/gitlab/gitlab.rb et ajoutez les lignes suivantes, en remplaçant les valeurs souhaitées :

   rubyCopy

   gitlab_rails['object_store']['connection'] = {
     'provider' => 'AzureRM',
     'azure_storage_account_name' => '<AZURE STORAGE ACCOUNT NAME>',
     'azure_storage_access_key' => '<AZURE STORAGE ACCESS KEY>',
     'azure_storage_domain' => '<AZURE STORAGE DOMAIN>'
   }
   gitlab_rails['object_store']['objects']['artifacts']['bucket'] = 'gitlab-artifacts'
   gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = 'gitlab-mr-diffs'
   gitlab_rails['object_store']['objects']['lfs']['bucket'] = 'gitlab-lfs'
   gitlab_rails['object_store']['objects']['uploads']['bucket'] = 'gitlab-uploads'
   gitlab_rails['object_store']['objects']['packages']['bucket'] = 'gitlab-packages'
   gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = 'gitlab-dependency-proxy'
   gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = 'gitlab-terraform-state'
   gitlab_rails['object_store']['objects']['ci_secure_files']['bucket'] = 'gitlab-ci-secure-files'
   gitlab_rails['object_store']['objects']['pages']['bucket'] = 'gitlab-pages'
   

   Si vous utilisez une identité de charge de travail, omettez azure_storage_access_key :

   rubyCopy

   gitlab_rails['object_store']['connection'] = {
     'provider' => 'AzureRM',
     'azure_storage_account_name' => '<AZURE STORAGE ACCOUNT NAME>',
     'azure_storage_domain' => '<AZURE STORAGE DOMAIN>'
   }
   

2. Enregistrez le fichier et reconfigurez GitLab :

   shellCopy

   sudo gitlab-ctl reconfigure
   

{{< /tab >}}

{{< tab title="Helm chart (Kubernetes)" >}}

1. Placez le contenu suivant dans un fichier nommé object_storage.yaml à utiliser comme Secret Kubernetes :

   yamlCopy

   provider: AzureRM
   azure_storage_account_name: <YOUR_AZURE_STORAGE_ACCOUNT_NAME>
   azure_storage_access_key: <YOUR_AZURE_STORAGE_ACCOUNT_KEY>
   azure_storage_domain: blob.core.windows.net
   

   Si vous utilisez une identité de charge de travail ou une identité managée, omettez azure_storage_access_key :

   yamlCopy

   provider: AzureRM
   azure_storage_account_name: <YOUR_AZURE_STORAGE_ACCOUNT_NAME>
   azure_storage_domain: blob.core.windows.net
   

2. Créez le Secret Kubernetes :

   shellCopy

   kubectl create secret generic -n <namespace> gitlab-object-storage --from-file=connection=object_storage.yaml
   

3. Exportez les valeurs Helm :

   shellCopy

   helm get values gitlab > gitlab_values.yaml
   

4. Modifiez gitlab_values.yaml :

   yamlCopy

   global:
     appConfig:
        artifacts:
          bucket: gitlab-artifacts
        ciSecureFiles:
          bucket: gitlab-ci-secure-files
          enabled: true
        dependencyProxy:
          bucket: gitlab-dependency-proxy
          enabled: true
        externalDiffs:
          bucket: gitlab-mr-diffs
          enabled: true
        lfs:
          bucket: gitlab-lfs
        object_store:
          connection:
            secret: gitlab-object-storage
          enabled: true
          proxy_download: false
        packages:
          bucket: gitlab-packages
        terraformState:
          bucket: gitlab-terraform-state
          enabled: true
        uploads:
          bucket: gitlab-uploads
   

5. Enregistrez le fichier et appliquez les nouvelles valeurs :

   shellCopy

   helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
   

{{< /tab >}}

{{< tab title="Docker" >}}

1. Modifiez docker-compose.yml :

   yamlCopy

   version: "3.6"
   services:
     gitlab:
       environment:
         GITLAB_OMNIBUS_CONFIG: |
           # Consolidated object storage configuration
           gitlab_rails['object_store']['enabled'] = true
           gitlab_rails['object_store']['proxy_download'] = false
           gitlab_rails['object_store']['connection'] = {
             'provider' => 'AzureRM',
             'azure_storage_account_name' => '<AZURE STORAGE ACCOUNT NAME>',
             'azure_storage_access_key' => '<AZURE STORAGE ACCESS KEY>',
             'azure_storage_domain' => '<AZURE STORAGE DOMAIN>'
           }
           gitlab_rails['object_store']['objects']['artifacts']['bucket'] = 'gitlab-artifacts'
           gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = 'gitlab-mr-diffs'
           gitlab_rails['object_store']['objects']['lfs']['bucket'] = 'gitlab-lfs'
           gitlab_rails['object_store']['objects']['uploads']['bucket'] = 'gitlab-uploads'
           gitlab_rails['object_store']['objects']['packages']['bucket'] = 'gitlab-packages'
           gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = 'gitlab-dependency-proxy'
           gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = 'gitlab-terraform-state'
           gitlab_rails['object_store']['objects']['ci_secure_files']['bucket'] = 'gitlab-ci-secure-files'
           gitlab_rails['object_store']['objects']['pages']['bucket'] = 'gitlab-pages'
   

   Si vous utilisez une identité managée, omettez azure_storage_access_key.

   rubyCopy

   gitlab_rails['object_store']['connection'] = {
     'provider' => 'AzureRM',
     'azure_storage_account_name' => '<AZURE STORAGE ACCOUNT NAME>',
     'azure_storage_domain' => '<AZURE STORAGE DOMAIN>'
   }
   

2. Enregistrez le fichier et redémarrez GitLab :

   shellCopy

   docker compose up -d
   

{{< /tab >}}

{{< tab title="Self-compiled (source)" >}}

Pour les installations compilées manuellement, Workhorse doit également être configuré avec les identifiants Azure. Cela n'est pas nécessaire dans les installations du package Linux car les paramètres Workhorse sont renseignés à partir des paramètres précédents.

1. Modifiez /home/git/gitlab/config/gitlab.yml et ajoutez ou modifiez les lignes suivantes :

   yamlCopy

   production: &base
     object_store:
       enabled: true
       proxy_download: false
       connection:
         provider: AzureRM
         azure_storage_account_name: '<AZURE STORAGE ACCOUNT NAME>'
         azure_storage_access_key: '<AZURE STORAGE ACCESS KEY>'
       objects:
         artifacts:
           bucket: gitlab-artifacts
         external_diffs:
           bucket: gitlab-mr-diffs
         lfs:
           bucket: gitlab-lfs
         uploads:
           bucket: gitlab-uploads
         packages:
           bucket: gitlab-packages
         dependency_proxy:
           bucket: gitlab-dependency-proxy
         terraform_state:
           bucket: gitlab-terraform-state
         ci_secure_files:
           bucket: gitlab-ci-secure-files
         pages:
           bucket: gitlab-pages
   

2. Modifiez /home/git/gitlab-workhorse/config.toml et ajoutez ou modifiez les lignes suivantes :

   tomlCopy

   [object_storage]
     provider = "AzureRM"
   
   [object_storage.azurerm]
     azure_storage_account_name = "<AZURE STORAGE ACCOUNT NAME>"
     azure_storage_access_key = "<AZURE STORAGE ACCESS KEY>"
   

   Si vous utilisez un domaine de stockage Azure personnalisé, azure_storage_domain ne doit pas être défini dans la configuration Workhorse. Ces informations sont échangées dans un appel API entre GitLab Rails et Workhorse.

3. Enregistrez le fichier et redémarrez GitLab :

   shellCopy

   # For systems running systemd
   sudo systemctl restart gitlab.target
   
   # For systems running SysV init
   sudo service gitlab restart
   

{{< /tab >}}

{{< /tabs >}}

Identités de charge de travail et identités managées Azure {#azure-workload-and-managed-identities}

{{< history >}}

• Introduit dans GitLab 17.9

{{< /history >}}

Pour utiliser les identités de charge de travail Azure ou les identités managées, omettez azure_storage_access_key de la configuration. Lorsque azure_storage_access_key est vide, GitLab tente de :

1. Obtenir des identifiants temporaires avec une identité de charge de travail. AZURE_TENANT_ID, AZURE_CLIENT_ID et AZURE_FEDERATED_TOKEN_FILE doivent être dans l'environnement.
2. Si une identité de charge de travail n'est pas disponible, demandez des identifiants auprès du service de métadonnées d'instance Azure.
3. Obtenez une clé de délégation d'utilisateur.
4. Générez un jeton SAS avec cette clé pour accéder à un blob de compte de stockage.

Assurez-vous que l'identité a le rôle Storage Blob Data Contributor qui lui est attribué.

Exemples de configuration spécifiques aux fournisseurs {#provider-specific-configuration-examples}

Les exemples suivants montrent la configuration pour des fournisseurs compatibles S3 spécifiques qui nécessitent des paramètres non définis par défaut. Pour tout fournisseur compatible S3 non répertorié ici, utilisez la configuration de base compatible S3 avec le endpoint approprié pour votre fournisseur.

Oracle Cloud Infrastructure {#oracle-cloud-infrastructure}

Oracle Cloud Infrastructure S3 nécessite les paramètres suivants :

Si enable_signature_v4_streaming est défini sur true, vous pouvez voir l'erreur suivante dans production.log :

STREAMING-AWS4-HMAC-SHA256-PAYLOAD is not supported

Storj Gateway (SJ) {#storj-gateway-sj}

[!note] Le Storj Gateway ne prend pas en charge la copie multi-threads (voir UploadPartCopy dans le tableau). Bien qu'une implémentation soit prévue, vous devez désactiver la copie multi-threads jusqu'à sa réalisation.

Le réseau Storj fournit une passerelle API compatible S3. Utilisez l'exemple de configuration suivant :

gitlab_rails['object_store']['connection'] = {
  'provider' => 'AWS',
  'endpoint' => 'https://gateway.storjshare.io',
  'path_style' => true,
  'region' => 'eu1',
  'aws_access_key_id' => 'ACCESS_KEY',
  'aws_secret_access_key' => 'SECRET_KEY',
  'aws_signature_version' => 2,
  'enable_signature_v4_streaming' => false
}

La version de signature doit être 2. L'utilisation de v4 entraîne une erreur HTTP 411 Length Required. Pour plus d'informations, consultez le ticket #4419.

Hitachi Vantara HCP {#hitachi-vantara-hcp}

[!note] Les connexions à HCP peuvent renvoyer une erreur indiquant SignatureDoesNotMatch - The request signature we calculated does not match the signature you provided. Check your HCP Secret Access key and signing method. Dans ces cas, définissez endpoint sur l'URL du locataire au lieu du namespace, et assurez-vous que les chemins de bucket sont configurés comme <namespace_name>/<bucket_name>.

HCP fournit une API compatible S3. Utilisez l'exemple de configuration suivant :

gitlab_rails['object_store']['connection'] = {
  'provider' => 'AWS',
  'endpoint' => 'https://<tenant_endpoint>',
  'path_style' => true,
  'region' => 'eu1',
  'aws_access_key_id' => 'ACCESS_KEY',
  'aws_secret_access_key' => 'SECRET_KEY',
  'aws_signature_version' => 4,
  'enable_signature_v4_streaming' => false
}

# Example of <namespace_name/bucket_name> formatting
gitlab_rails['object_store']['objects']['artifacts']['bucket'] = '<namespace_name>/<bucket_name>'

Ceph RGW {#ceph-rgw}

Ceph RGW est une API compatible S3 pour Ceph. Utilisez l'exemple de configuration suivant :

gitlab_rails['object_store']['connection'] = {
  'provider' => 'AWS',
  'endpoint' => 'https://rgw-ceph.example.com',
  'region' => 'us-west-1',
  'aws_access_key_id' => 'ACCESS_KEY',
  'aws_secret_access_key' => 'SECRET_KEY',
  'path_style': true
}

Pour activer le chiffrement côté serveur avec Ceph RGW, vous devez vous connecter via HTTPS. Ceph rejette les requêtes de chiffrement sur les connexions non sécurisées.

Exemple complet utilisant le formulaire consolidé et Amazon S3 {#full-example-using-the-consolidated-form-and-amazon-s3}

L'exemple suivant utilise AWS S3 pour activer le stockage d'objets pour tous les services pris en charge :

{{< tabs >}}

{{< tab title="Linux package (Omnibus)" >}}

1. Modifiez /etc/gitlab/gitlab.rb et ajoutez les lignes suivantes, en remplaçant les valeurs souhaitées :

   rubyCopy

   # Consolidated object storage configuration
   gitlab_rails['object_store']['enabled'] = true
   gitlab_rails['object_store']['proxy_download'] = false
   gitlab_rails['object_store']['connection'] = {
     'provider' => 'AWS',
     'region' => 'eu-central-1',
     'aws_access_key_id' => '<AWS_ACCESS_KEY_ID>',
     'aws_secret_access_key' => '<AWS_SECRET_ACCESS_KEY>'
   }
   # OPTIONAL: The following lines are only needed if server side encryption is required
   gitlab_rails['object_store']['storage_options'] = {
     'server_side_encryption' => '<AES256 or aws:kms>',
     'server_side_encryption_kms_key_id' => '<arn:aws:kms:xxx>'
   }
   gitlab_rails['object_store']['objects']['artifacts']['bucket'] = 'gitlab-artifacts'
   gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = 'gitlab-mr-diffs'
   gitlab_rails['object_store']['objects']['lfs']['bucket'] = 'gitlab-lfs'
   gitlab_rails['object_store']['objects']['uploads']['bucket'] = 'gitlab-uploads'
   gitlab_rails['object_store']['objects']['packages']['bucket'] = 'gitlab-packages'
   gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = 'gitlab-dependency-proxy'
   gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = 'gitlab-terraform-state'
   gitlab_rails['object_store']['objects']['ci_secure_files']['bucket'] = 'gitlab-ci-secure-files'
   gitlab_rails['object_store']['objects']['pages']['bucket'] = 'gitlab-pages'
   

   Si vous utilisez des profils IAM AWS, omettez la paire clé/valeur de la clé d'accès AWS et de la clé d'accès secrète. Par exemple :

   rubyCopy

   gitlab_rails['object_store']['connection'] = {
     'provider' => 'AWS',
     'region' => 'eu-central-1',
     'use_iam_profile' => true
   }
   

2. Enregistrez le fichier et reconfigurez GitLab :

   shellCopy

   sudo gitlab-ctl reconfigure
   

{{< /tab >}}

{{< tab title="Helm chart (Kubernetes)" >}}

1. Placez le contenu suivant dans un fichier nommé object_storage.yaml à utiliser comme Secret Kubernetes :

   yamlCopy

   provider: AWS
   region: us-east-1
   aws_access_key_id: <AWS_ACCESS_KEY_ID>
   aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>
   

   Si vous utilisez des profils IAM AWS, omettez la paire clé/valeur de la clé d'accès AWS et de la clé d'accès secrète. Par exemple :

   yamlCopy

   provider: AWS
   region: us-east-1
   use_iam_profile: true
   

2. Créez le Secret Kubernetes :

   shellCopy

   kubectl create secret generic -n <namespace> gitlab-object-storage --from-file=connection=object_storage.yaml
   

3. Exportez les valeurs Helm :

   shellCopy

   helm get values gitlab > gitlab_values.yaml
   

4. Modifiez gitlab_values.yaml :

   yamlCopy

   global:
     appConfig:
        artifacts:
          bucket: gitlab-artifacts
        ciSecureFiles:
          bucket: gitlab-ci-secure-files
          enabled: true
        dependencyProxy:
          bucket: gitlab-dependency-proxy
          enabled: true
        externalDiffs:
          bucket: gitlab-mr-diffs
          enabled: true
        lfs:
          bucket: gitlab-lfs
        object_store:
          connection:
            secret: gitlab-object-storage
          enabled: true
          proxy_download: false
        packages:
          bucket: gitlab-packages
        terraformState:
          bucket: gitlab-terraform-state
          enabled: true
        uploads:
          bucket: gitlab-uploads
   

5. Enregistrez le fichier et appliquez les nouvelles valeurs :

   shellCopy

   helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
   

{{< /tab >}}

{{< tab title="Docker" >}}

1. Modifiez docker-compose.yml :

   yamlCopy

   version: "3.6"
   services:
     gitlab:
       environment:
         GITLAB_OMNIBUS_CONFIG: |
           # Consolidated object storage configuration
           gitlab_rails['object_store']['enabled'] = true
           gitlab_rails['object_store']['proxy_download'] = false
           gitlab_rails['object_store']['connection'] = {
             'provider' => 'AWS',
             'region' => 'eu-central-1',
             'aws_access_key_id' => '<AWS_ACCESS_KEY_ID>',
             'aws_secret_access_key' => '<AWS_SECRET_ACCESS_KEY>'
           }
           # OPTIONAL: The following lines are only needed if server side encryption is required
           gitlab_rails['object_store']['storage_options'] = {
             'server_side_encryption' => '<AES256 or aws:kms>',
             'server_side_encryption_kms_key_id' => '<arn:aws:kms:xxx>'
           }
           gitlab_rails['object_store']['objects']['artifacts']['bucket'] = 'gitlab-artifacts'
           gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = 'gitlab-mr-diffs'
           gitlab_rails['object_store']['objects']['lfs']['bucket'] = 'gitlab-lfs'
           gitlab_rails['object_store']['objects']['uploads']['bucket'] = 'gitlab-uploads'
           gitlab_rails['object_store']['objects']['packages']['bucket'] = 'gitlab-packages'
           gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = 'gitlab-dependency-proxy'
           gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = 'gitlab-terraform-state'
           gitlab_rails['object_store']['objects']['ci_secure_files']['bucket'] = 'gitlab-ci-secure-files'
           gitlab_rails['object_store']['objects']['pages']['bucket'] = 'gitlab-pages'
   

   Si vous utilisez des profils IAM AWS, omettez la paire clé/valeur de la clé d'accès AWS et de la clé d'accès secrète. Par exemple :

   rubyCopy

   gitlab_rails['object_store']['connection'] = {
     'provider' => 'AWS',
     'region' => 'eu-central-1',
     'use_iam_profile' => true
   }
   

2. Enregistrez le fichier et redémarrez GitLab :

   shellCopy

   docker compose up -d
   

{{< /tab >}}

{{< tab title="Self-compiled (source)" >}}

1. Modifiez /home/git/gitlab/config/gitlab.yml et ajoutez ou modifiez les lignes suivantes :

   yamlCopy

   production: &base
     object_store:
       enabled: true
       proxy_download: false
       connection:
         provider: AWS
         aws_access_key_id: <AWS_ACCESS_KEY_ID>
         aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>
         region: eu-central-1
       storage_options:
         server_side_encryption: <AES256 or aws:kms>
         server_side_encryption_key_kms_id: <arn:aws:kms:xxx>
       objects:
         artifacts:
           bucket: gitlab-artifacts
         external_diffs:
           bucket: gitlab-mr-diffs
         lfs:
           bucket: gitlab-lfs
         uploads:
           bucket: gitlab-uploads
         packages:
           bucket: gitlab-packages
         dependency_proxy:
           bucket: gitlab-dependency-proxy
         terraform_state:
           bucket: gitlab-terraform-state
         ci_secure_files:
           bucket: gitlab-ci-secure-files
         pages:
           bucket: gitlab-pages
   

   Si vous utilisez des profils IAM AWS, omettez la paire clé/valeur de la clé d'accès AWS et de la clé d'accès secrète. Par exemple :

   yamlCopy

   connection:
     provider: AWS
     region: eu-central-1
     use_iam_profile: true
   

2. Modifiez /home/git/gitlab-workhorse/config.toml et ajoutez ou modifiez les lignes suivantes :

   tomlCopy

   [object_storage]
     provider = "AWS"
   
   [object_storage.s3]
     aws_access_key_id = "<AWS_ACCESS_KEY_ID>"
     aws_secret_access_key = "<AWS_SECRET_ACCESS_KEY>"
   

   Si vous utilisez des profils IAM AWS, omettez la paire clé/valeur de la clé d'accès AWS et de la clé d'accès secrète. Par exemple :

   yamlCopy

   [object_storage.s3]
     use_iam_profile = true
   

3. Enregistrez le fichier et redémarrez GitLab :

   shellCopy

   # For systems running systemd
   sudo systemctl restart gitlab.target
   
   # For systems running SysV init
   sudo service gitlab restart
   

{{< /tab >}}

{{< /tabs >}}

Migrer vers le stockage d'objets {#migrate-to-object-storage}

Pour migrer les données locales existantes vers le stockage d'objets, consultez les guides suivants :

• Artefacts de job incluant les job logs archivés
• Objets LFS
• Importations
• Diffs de merge request
• Packages (fonctionnalité optionnelle)
• Proxy de dépendances
• Fichiers d'état Terraform
• Contenu Pages
• Fichiers sécurisés au niveau du projet

Passer au formulaire consolidé {#transition-to-consolidated-form}

Dans la configuration spécifique au stockage :

• La configuration du stockage d'objets pour tous les types d'objets tels que les artefacts CI/CD, les fichiers LFS et les pièces jointes importées est configurée indépendamment.
• Les paramètres de connexion au stockage d'objets tels que les mots de passe et les URL de point de terminaison sont dupliqués pour chaque type.

Par exemple, une installation de package Linux pourrait avoir la configuration suivante :

# Original object storage configuration
gitlab_rails['artifacts_object_store_enabled'] = true
gitlab_rails['artifacts_object_store_direct_upload'] = true
gitlab_rails['artifacts_object_store_proxy_download'] = false
gitlab_rails['artifacts_object_store_remote_directory'] = 'artifacts'
gitlab_rails['artifacts_object_store_connection'] = { 'provider' => 'AWS', 'aws_access_key_id' => 'access_key', 'aws_secret_access_key' => 'secret' }
gitlab_rails['uploads_object_store_enabled'] = true
gitlab_rails['uploads_object_store_direct_upload'] = true
gitlab_rails['uploads_object_store_proxy_download'] = false
gitlab_rails['uploads_object_store_remote_directory'] = 'uploads'
gitlab_rails['uploads_object_store_connection'] = { 'provider' => 'AWS', 'aws_access_key_id' => 'access_key', 'aws_secret_access_key' => 'secret' }

Bien que cela offre une flexibilité en permettant à GitLab de stocker des objets chez différents fournisseurs de cloud, cela crée également une complexité supplémentaire et une redondance inutile. Étant donné que les composants GitLab Rails et Workhorse ont tous deux besoin d'accéder au stockage d'objets, le formulaire consolidé évite la duplication excessive des identifiants.

Le formulaire consolidé n'est utilisé que si toutes les lignes du formulaire d'origine sont omises. Pour passer au formulaire consolidé, supprimez la configuration d'origine (par exemple, artifacts_object_store_enabled, ou uploads_object_store_connection)

Migrer des objets vers un autre fournisseur de stockage d'objets {#migrate-objects-to-a-different-object-storage-provider}

Vous devrez peut-être migrer les données GitLab dans le stockage d'objets vers un autre fournisseur de stockage d'objets. Les étapes suivantes vous montrent comment procéder en utilisant Rclone.

Les étapes supposent que vous déplacez le bucket uploads, mais le même processus fonctionne pour d'autres buckets.

Prérequis :

• Choisissez l'ordinateur sur lequel exécuter Rclone. Selon la quantité de données que vous migrez, Rclone peut devoir s'exécuter pendant une longue période, vous devriez donc éviter d'utiliser un ordinateur portable ou de bureau susceptible de passer en mode économie d'énergie. Vous pouvez utiliser votre serveur GitLab pour exécuter Rclone.

1. Installez Rclone.

2. Configurez Rclone en exécutant la commande suivante :

   shellCopy

   rclone config
   

   Le processus de configuration est interactif. Ajoutez au moins deux « remotes » : un pour le fournisseur de stockage d'objets sur lequel se trouvent actuellement vos données (old), et un pour le fournisseur vers lequel vous migrez (new).

3. Vérifiez que vous pouvez lire les anciennes données. L'exemple suivant fait référence au bucket uploads, mais votre bucket peut avoir un nom différent :

   shellCopy

   rclone ls old:uploads | head
   

   Cela devrait afficher une liste partielle des objets actuellement stockés dans votre bucket uploads. Si vous obtenez une erreur, ou si la liste est vide, revenez en arrière et mettez à jour votre configuration Rclone en utilisant rclone config.

4. Effectuez une copie initiale. Vous n'avez pas besoin de mettre votre serveur GitLab hors ligne pour cette étape.

   shellCopy

   rclone sync -P old:uploads new:uploads
   

5. Une fois la première synchronisation terminée, utilisez l'interface web ou l'interface en ligne de commande de votre nouveau fournisseur de stockage d'objets pour vérifier qu'il y a des objets dans le nouveau bucket. S'il n'y en a aucun, ou si vous rencontrez une erreur lors de l'exécution de rclone sync, vérifiez votre configuration Rclone et réessayez.

Après avoir effectué au moins une copie Rclone réussie de l'ancien emplacement vers le nouvel emplacement, planifiez une maintenance et mettez votre serveur GitLab hors ligne. Pendant votre fenêtre de maintenance, vous devez effectuer deux choses :

1. Effectuez une dernière exécution de rclone sync, sachant que vos utilisateurs ne peuvent pas ajouter de nouveaux objets, de sorte que vous ne laissez aucun objet dans l'ancien bucket.
2. Mettez à jour la configuration du stockage d'objets de votre serveur GitLab pour utiliser le nouveau fournisseur pour uploads.

Alternatives au stockage sur système de fichiers {#alternatives-to-file-system-storage}

Si vous travaillez à la mise à l'échelle de votre implémentation GitLab, ou à l'ajout de tolérance aux pannes et de redondance, vous envisagez peut-être de supprimer les dépendances envers les systèmes de fichiers en bloc ou réseau. Consultez les guides supplémentaires suivants :

1. Assurez-vous que le répertoire personnel de l'utilisateur git se trouve sur le disque local.
2. Configurez la recherche des clés SSH dans la base de données pour éliminer le besoin d'un fichier authorized_keys partagé.
3. Empêcher l'utilisation du disque local pour les job logs.
4. Désactiver le stockage local de Pages.

Dépannage {#troubleshooting}

Les objets ne sont pas inclus dans les sauvegardes GitLab {#objects-are-not-included-in-gitlab-backups}

Comme indiqué dans la documentation sur les sauvegardes, les objets ne sont pas inclus dans les sauvegardes GitLab. Vous pouvez activer les sauvegardes avec votre fournisseur de stockage d'objets à la place.

Utiliser des buckets séparés {#use-separate-buckets}

L'utilisation de buckets séparés pour chaque type de données est l'approche recommandée pour GitLab. Cela garantit qu'il n'y a pas de collisions entre les différents types de données que GitLab stocke. Le ticket 292958 propose d'activer l'utilisation d'un seul bucket.

Avec les installations de packages Linux et les installations compilées manuellement, il est possible de diviser un seul bucket réel en plusieurs buckets virtuels. Si votre bucket de stockage d'objets s'appelle my-gitlab-objects, vous pouvez configurer les importations pour aller dans my-gitlab-objects/uploads, les artefacts dans my-gitlab-objects/artifacts, etc. L'application se comporte comme si ce sont des buckets séparés. L'utilisation de préfixes de bucket peut ne pas fonctionner correctement avec les sauvegardes Helm.

Les installations basées sur Helm nécessitent des buckets séparés pour gérer les restaurations de sauvegardes.

Problèmes de compatibilité avec l'API S3 {#s3-api-compatibility-issues}

Si vous rencontrez des erreurs avec un fournisseur compatible S3, consultez la compatibilité S3 et les modes d'échec connus pour les causes courantes et les ajustements de configuration. Une erreur 411 Length Required dans production.log est généralement causée par la diffusion de signature. Définissez enable_signature_v4_streaming: false pour résoudre le problème.

Artefacts toujours téléchargés avec le nom de fichier download {#artifacts-always-downloaded-with-filename-download}

Les noms de fichiers des artefacts téléchargés sont définis avec l'en-tête response-content-disposition dans la requête GetObject. Si le fournisseur S3 ne prend pas en charge cet en-tête, le fichier téléchargé est toujours enregistré sous download.

Proxy Download {#proxy-download}

Les clients peuvent télécharger des fichiers dans le stockage d'objets en recevant une URL pré-signée à durée limitée, ou en faisant en sorte que GitLab proxy les données du stockage d'objets vers le client. Le téléchargement de fichiers directement depuis le stockage d'objets permet de réduire la quantité de trafic sortant que GitLab doit traiter.

Lorsque les fichiers sont stockés sur un stockage en bloc local ou NFS, GitLab doit agir comme un proxy. Ce n'est pas le comportement par défaut avec le stockage d'objets.

Le paramètre proxy_download contrôle ce comportement : la valeur par défaut est false. Vérifiez cela dans la documentation pour chaque cas d'utilisation.

Définissez proxy_download sur true si vous souhaitez que GitLab proxy les fichiers. La performance du serveur GitLab peut être fortement impactée si proxy_download est défini sur true. Les déploiements serveur de GitLab ont proxy_download défini sur false.

Lorsque proxy_download est défini sur false, GitLab renvoie une redirection HTTP 302 avec une URL de stockage d'objets pré-signée à durée limitée. Cela peut entraîner certains des problèmes suivants :

• Si GitLab utilise HTTP non sécurisé pour accéder au stockage d'objets, les clients peuvent générer des erreurs de déclassement https->http et refuser de traiter la redirection. La solution est que GitLab utilise HTTPS. LFS, par exemple, génère cette erreur :

  plaintextCopy

  LFS: lfsapi/client: refusing insecure redirect, https->http
  

• Les clients doivent faire confiance à l'autorité de certification qui a émis le certificat de stockage d'objets, ou peuvent renvoyer des erreurs TLS courantes telles que :

  plaintextCopy

  x509: certificate signed by unknown authority
  

• Les clients ont besoin d'un accès réseau au stockage d'objets. Les pare-feux réseau pourraient bloquer l'accès. Les erreurs qui pourraient résulter de l'absence de cet accès incluent :

  plaintextCopy

  Received status code 403 from server: Forbidden
  

• Les buckets de stockage d'objets doivent autoriser l'accès Cross-Origin Resource Sharing (CORS) depuis l'URL de l'instance GitLab. Tenter de charger un PDF dans la page du dépôt peut afficher l'erreur suivante :

  plaintextCopy

  An error occurred while loading the file. Please try again later.
  

  Consultez la documentation LFS pour plus de détails.

[!warning] Les URL pré-signées sont limitées dans le temps mais ne sont pas liées à un utilisateur spécifique. Tout utilisateur qui obtient une URL pré-signée peut accéder à l'objet sans authentification pendant la durée de validité de l'URL. Les téléchargements directs peuvent également entraîner des frais de bande passante entre votre fournisseur de stockage d'objets et le client.

Non-correspondance ETag {#etag-mismatch}

En utilisant les paramètres GitLab par défaut, certains systèmes de stockage d'objets compatibles S3 tels qu'Alibaba peuvent générer des erreurs ETag mismatch.

Chiffrement Amazon S3 {#amazon-s3-encryption}

Si vous observez cette erreur de non-correspondance ETag avec Amazon Web Services S3, c'est probablement dû aux paramètres de chiffrement de votre bucket. Pour résoudre ce problème, vous avez deux options :

• Utiliser le formulaire consolidé.
• Utiliser des profils d'instance Amazon.

Le formulaire consolidé est recommandé pour les services compatibles S3. Certains services peuvent également nécessiter une configuration côté serveur supplémentaire, comme l'activation d'un mode de compatibilité, pour résoudre les erreurs de non-correspondance ETag.

Sans le formulaire consolidé ou les profils d'instance activés, GitLab Workhorse importe des fichiers vers S3 en utilisant des URL pré-signées qui n'ont pas d'en-tête HTTP Content-MD5 calculé pour elles. Pour s'assurer que les données ne sont pas corrompues, Workhorse vérifie que le hachage MD5 des données envoyées est égal à l'en-tête ETag renvoyé par le serveur S3. Lorsque le chiffrement est activé, ce n'est pas le cas, ce qui amène Workhorse à signaler une erreur ETag mismatch lors d'une importation.

Lorsque le formulaire consolidé est :

• Utilisé avec un stockage d'objets compatible S3 ou un profil d'instance, Workhorse utilise son client S3 interne qui dispose des identifiants S3 afin de pouvoir calculer l'en-tête Content-MD5. Cela élimine le besoin de comparer les en-têtes ETag renvoyés par le serveur S3.
• Non utilisé avec un stockage d'objets compatible S3, Workhorse revient à l'utilisation des URL pré-signées.

Chiffrement Google Cloud Storage {#google-cloud-storage-encryption}

{{< history >}}

• Introduit dans GitLab 16.11.

{{< /history >}}

Des erreurs de non-correspondance ETag se produisent également dans Google Cloud Storage (GCS) lors de l'activation du chiffrement des données avec des clés de chiffrement gérées par le client (CMEK).

Pour utiliser CMEK, utilisez le formulaire consolidé.

Copie multi-threads {#multi-threaded-copying}

GitLab utilise l'API S3 Upload Part Copy pour accélérer la copie de fichiers dans un bucket. Cette fonctionnalité n'est pas prise en charge par certains fournisseurs compatibles S3 et ils renvoient une erreur 404 lors de l'importation.

Pour désactiver la copie multi-threads, demandez à un administrateur GitLab avec un accès à la console Rails d'exécuter la commande suivante :

Feature.disable(:s3_multithreaded_uploads)

Tests manuels via la console Rails {#manual-testing-through-rails-console}

Utilisez cette approche pour vérifier la connectivité du stockage d'objets lorsque vous suspectez une mauvaise configuration. L'exemple suivant teste une connexion, écrit un objet de test et le relit.

1. Démarrez une console Rails.

2. Configurez la connexion au stockage d'objets, en utilisant les mêmes paramètres que vous avez configurés dans /etc/gitlab/gitlab.rb, au format d'exemple suivant :

   Exemple de connexion utilisant la configuration d'importation existante :

   rubyCopy

   settings = Gitlab.config.uploads.object_store.connection.deep_symbolize_keys
   connection = Fog::Storage.new(settings)
   

   Exemple de connexion utilisant des clés d'accès :

   rubyCopy

   connection = Fog::Storage.new(
     {
       provider: 'AWS',
       region: 'eu-central-1',
       aws_access_key_id: '<AWS_ACCESS_KEY_ID>',
       aws_secret_access_key: '<AWS_SECRET_ACCESS_KEY>'
     }
   )
   

   Exemple de connexion utilisant des profils IAM AWS :

   rubyCopy

   connection = Fog::Storage.new(
     {
       provider: 'AWS',
       use_iam_profile: true,
       region: 'us-east-1'
     }
   )
   

3. Spécifiez le nom du bucket à tester, écrivez, puis lisez un fichier de test.

   rubyCopy

   dir = connection.directories.new(key: '<bucket-name-here>')
   f = dir.files.create(key: 'test.txt', body: 'test')
   pp f
   pp dir.files.head('test.txt')
   

Activer le débogage supplémentaire {#enable-additional-debugging}

{{< history >}}

• Prise en charge de la variable d'environnement AWS_DEBUG introduite dans GitLab 18.3.

{{< /history >}}

Vous pouvez également activer un débogage supplémentaire pour voir les requêtes HTTP. Vous devriez le faire dans la console Rails pour éviter de divulguer des identifiants dans les fichiers journaux. Ce qui suit montre comment activer le débogage des requêtes pour différents fournisseurs :

{{< tabs >}}

{{< tab title="Amazon S3" >}}

Définissez la variable d'environnement EXCON_DEBUG :

ENV['EXCON_DEBUG'] = "1"

Vous pouvez également activer la journalisation des en-têtes de requête et de réponse HTTP S3 dans les journaux GitLab Workhorse en définissant la variable d'environnement AWS_DEBUG sur 1. Pour le package Linux (Omnibus) :

1. Modifiez /etc/gitlab/gitlab.rb et ajoutez les lignes suivantes :

   rubyCopy

   gitlab_workhorse['env'] = {
     'AWS_DEBUG' => '1'
   }
   

2. Enregistrez le fichier et reconfigurez GitLab :

   shellCopy

   sudo gitlab-ctl reconfigure
   

   Les en-têtes de requête et de réponse du stockage compatible S3 sont consignés dans /var/log/gitlab/gitlab-workhorse/current.

{{< /tab >}}

{{< tab title="Google Cloud Storage" >}}

Configurez le logger pour qu'il enregistre dans STDOUT :

Google::Apis.logger = Logger::new(STDOUT)

{{< /tab >}}

{{< tab title="Azure Blob Storage" >}}

Définissez la variable d'environnement DEBUG :

ENV['DEBUG'] = "1"

{{< /tab >}}

{{< /tabs >}}

Réinitialiser la base de données de suivi Geo pour garantir la cohérence complète des objets {#reset-the-geo-tracking-database-to-ensure-full-objects-consistency}

Supposons le scénario Geo suivant :

• Un environnement est composé d'un nœud Geo principal et d'un nœud secondaire.
• Vous avez migré vers le stockage d'objets sur le principal.
  • Le secondaire utilise des compartiments de stockage d'objets distincts.
  • L'option « Allow this secondary site to replicate content on Object Storage » est activée.

De telles migrations peuvent amener les objets à être marqués comme synchronisés dans la base de données de suivi alors qu'ils sont physiquement absents du stockage d'objets. Dans ce cas, réinitialisez la réplication de votre site Geo secondaire pour garantir que l'état des objets reste cohérent après la migration.

Incohérences après la migration vers le stockage d'objets {#inconsistencies-after-migrating-to-object-storage}

Des incohérences de données peuvent se produire lors de la migration du stockage local vers le stockage d'objets. En particulier en combinaison avec Geo, lorsque des fichiers ont été supprimés manuellement avant la migration.

Par exemple, un administrateur d'instance supprime manuellement plusieurs artefacts sur le système de fichiers local. Ces modifications ne sont pas correctement propagées à la base de données et entraînent des incohérences. Après la migration vers le stockage d'objets, ces incohérences persistent et peuvent provoquer des frictions. Les secondaires Geo peuvent continuer à essayer de répliquer ces fichiers car ils sont toujours référencés dans la base de données mais n'existent plus.

Identifier les incohérences lors de l'utilisation de Geo {#identify-inconsistencies-when-using-geo}

Supposons le scénario Geo suivant :

• Un environnement est composé d'un nœud Geo principal et d'un nœud secondaire
• Les deux systèmes ont été migrés vers le stockage d'objets
  • Le secondaire utilise le même stockage d'objets que le principal
  • L'option Allow this secondary site to replicate content on Object Storage est désactivée
• Plusieurs téléversements ont été supprimés manuellement avant la migration vers le stockage d'objets
  • Pour cet exemple, deux images qui ont été téléversées vers un ticket

Dans un tel scénario, le secondaire n'a plus besoin de répliquer des données puisqu'il utilise le même stockage d'objets que le principal. En raison des incohérences, les administrateurs peuvent observer que le secondaire essaie toujours de répliquer des données :

Sur le site principal :

1. Dans le coin supérieur droit, sélectionnez Admin.
2. Dans la barre latérale gauche, sélectionnez Geo > Sites.
3. Examinez le site principal et vérifiez les informations de vérification. Tous les téléversements ont été vérifiés :
4. Examinez le site secondaire et vérifiez les informations de vérification. Notez que deux téléversements sont toujours en cours de synchronisation, même si le secondaire devrait utiliser le même stockage d'objets. Cela signifie qu'il ne devrait pas avoir à synchroniser les téléversements :

Nettoyer les incohérences {#clean-up-inconsistencies}

[!warning] Assurez-vous de disposer d'une sauvegarde récente et fonctionnelle avant d'exécuter toute commande de suppression.

Sur la base du scénario précédent, plusieurs téléversements causent des incohérences, utilisées comme exemple ci-dessous.

Procédez comme suit pour supprimer correctement les éventuels résidus :

1. Associez les incohérences identifiées à leurs noms de modèle respectifs. Le nom du modèle est nécessaire dans les étapes suivantes.

   Type de stockage d'objets	Nom du modèle
   Sauvegardes	non applicable
   Registre de conteneurs	non applicable
   Mattermost	non applicable
   Cache de runner à mise à l'échelle automatique	non applicable
   Fichiers sécurisés	Ci::SecureFile
   Artefacts de job	Ci::JobArtifact et Ci::PipelineArtifact
   Objets LFS	LfsObject
   Importations	Upload
   Diffs de merge request	MergeRequestDiff
   Packages	Packages::PackageFile
   Proxy de dépendances	DependencyProxy::Blob et DependencyProxy::Manifest
   Fichiers d'état Terraform	Terraform::StateVersion
   Contenu Pages	PagesDeployment

2. Démarrez une console Rails.

3. Interrogez tous les « fichiers » qui sont encore stockés localement (au lieu du stockage d'objets) sur la base du nom de modèle de l'étape précédente. Dans ce cas, comme les téléversements sont concernés, le nom de modèle Upload est utilisé. Observez comment openbao.png est toujours stocké localement :

   rubyCopy

   Upload.with_files_stored_locally
   

   rubyCopy

   #<Upload:0x00007d35b69def68
     id: 108,
     size: 13346,
     path: "c95c1c9bf91a34f7d97346fd3fa6a7be/openbao.png",
     checksum: "db29d233de49b25d2085dcd8610bac787070e721baa8dcedba528a292b6e816b",
     model_id: 2,
     model_type: "Project",
     uploader: "FileUploader",
     created_at: Wed, 02 Apr 2025 05:56:47.941319000 UTC +00:00,
     store: 1,
     mount_point: nil,
     secret: "[FILTERED]",
     version: 2,
     uploaded_by_user_id: 1,
     organization_id: nil,
     namespace_id: nil,
     project_id: 2,
     verification_checksum: nil>]
   

4. Utilisez l'id des ressources identifiées pour les supprimer correctement. Tout d'abord, vérifiez qu'il s'agit de la bonne ressource en utilisant find, puis exécutez destroy :

   rubyCopy

   Upload.find(108)
   Upload.find(108).destroy
   

5. En option, vérifiez que la ressource a été supprimée correctement en exécutant à nouveau find, qui ne devrait plus la trouver :

   rubyCopy

   Upload.find(108)
   

   rubyCopy

   ActiveRecord::RecordNotFound: Couldn't find Upload with 'id'=108
   

Répétez les étapes pour tous les types de stockage d'objets concernés.

Les job logs sont manquants dans une instance GitLab multi-nœuds {#job-logs-are-missing-in-a-multi-node-gitlab-instance}

Sur les instances GitLab comportant plus d'un nœud Rails (serveurs exécutant les services web ou Sidekiq), un mécanisme doit être mis en place pour rendre les job logs disponibles sur tous les nœuds après leur envoi depuis le runner. Les job logs peuvent être stockés sur le disque local ou dans le stockage d'objets.

Si NFS n'est pas utilisé et que la fonctionnalité de journalisation incrémentale n'a pas été activée, les job logs peuvent être perdus :

1. Le nœud qui reçoit le log du runner écrit le log sur le disque local.
2. Lorsque GitLab tente d'archiver le log, le job s'exécute souvent sur un serveur différent qui ne peut pas accéder au log.
3. Le téléversement vers le stockage d'objets échoue.

L'erreur suivante peut également être consignée dans /var/log/gitlab/gitlab-rails/exceptions_json.log :

{
  "severity": "ERROR",
  "exception.class": "Ci::AppendBuildTraceService::TraceRangeError",
  "extra.build_id": 425187,
  "extra.body_end": 12955,
  "extra.stream_size": 720,
  "extra.stream_class": {},
  "extra.stream_range": "0-12954"
}

Si les artefacts CI sont écrits dans le stockage d'objets dans un environnement multi-nœuds, vous devez activer la fonctionnalité de journalisation incrémentale.