diff options
Diffstat (limited to 'doc/administration/lfs/index.md')
| -rw-r--r-- | doc/administration/lfs/index.md | 88 |
1 files changed, 43 insertions, 45 deletions
diff --git a/doc/administration/lfs/index.md b/doc/administration/lfs/index.md index bc349536a0c..862c26abac8 100644 --- a/doc/administration/lfs/index.md +++ b/doc/administration/lfs/index.md @@ -6,17 +6,17 @@ type: reference, howto disqus_identifier: 'https://docs.gitlab.com/ee/workflow/lfs/lfs_administration.html' --- -# GitLab Git Large File Storage (LFS) Administration **(CORE ONLY)** +# GitLab Git Large File Storage (LFS) Administration **(FREE SELF)** > - Git LFS is supported in GitLab starting with version 8.2. > - Support for object storage, such as AWS S3, was introduced in 10.0. > - LFS is enabled in GitLab self-managed instances by default. -Documentation on how to use Git LFS are under [Managing large binary files with Git LFS doc](../../topics/git/lfs/index.md). +Documentation about how to use Git LFS are under [Managing large binary files with Git LFS doc](../../topics/git/lfs/index.md). ## Requirements -- Users need to install [Git LFS client](https://git-lfs.github.com) version 1.0.1 and up. +- Users need to install [Git LFS client](https://git-lfs.github.com) version 1.0.1 or later. ## Configuration @@ -25,9 +25,9 @@ GitLab is installed on. There are various configuration options to help GitLab server administrators: -- Enabling/disabling Git LFS support -- Changing the location of LFS object storage -- Setting up object storage supported by [Fog](http://fog.io/about/provider_documentation.html) +- Enabling/disabling Git LFS support. +- Changing the location of LFS object storage. +- Setting up object storage supported by [Fog](http://fog.io/about/provider_documentation.html). ### Configuration for Omnibus installations @@ -43,7 +43,7 @@ gitlab_rails['lfs_enabled'] = false gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects" ``` -After you update settings in `/etc/gitlab/gitlab.rb`, make sure to run [Omnibus GitLab reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure). +After you update settings in `/etc/gitlab/gitlab.rb`, run [Omnibus GitLab reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure). ### Configuration for installations from source @@ -58,14 +58,12 @@ In `config/gitlab.yml`: ## Storing LFS objects in remote object storage -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2760) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0. Brought to GitLab Core in 10.7. - -It is possible to store LFS objects in remote object storage which allows you -to offload local hard disk R/W operations, and free up disk space significantly. +You can store LFS objects in remote object storage. This allows you +to offload reads and writes to the local disk, and free up disk space significantly. GitLab is tightly integrated with `Fog`, so you can refer to its [documentation](http://fog.io/about/provider_documentation.html) to check which storage services can be integrated with GitLab. You can also use external object storage in a private local network. For example, -[MinIO](https://min.io/) is a standalone object storage service, is easy to set up, and works well with GitLab instances. +[MinIO](https://min.io/) is a standalone object storage service that works with GitLab instances. GitLab provides two different options for the uploading mechanism: "Direct upload" and "Background upload". @@ -78,26 +76,26 @@ This section describes the earlier configuration format. **Option 1. Direct upload** -1. User pushes an `lfs` file to the GitLab instance -1. GitLab-workhorse uploads the file directly to the external object storage -1. GitLab-workhorse notifies GitLab-rails that the upload process is complete +1. User pushes an `lfs` file to the GitLab instance. +1. GitLab-workhorse uploads the file directly to the external object storage. +1. GitLab-workhorse notifies GitLab-rails that the upload process is complete. **Option 2. Background upload** -1. User pushes an `lfs` file to the GitLab instance -1. GitLab-rails stores the file in the local file storage -1. GitLab-rails then uploads the file to the external object storage asynchronously +1. User pushes an `lfs` file to the GitLab instance. +1. GitLab-rails stores the file in the local file storage. +1. GitLab-rails then uploads the file to the external object storage asynchronously. The following general settings are supported. -| Setting | Description | Default | -|---------|-------------|---------| -| `enabled` | Enable/disable object storage | `false` | -| `remote_directory` | The bucket name where LFS objects will be stored| | -| `direct_upload` | Set to true to enable direct upload of LFS without the need of local shared storage. Option may be removed once we decide to support only single storage for all files. | `false` | -| `background_upload` | Set to false to disable automatic upload. Option may be removed once upload is direct to S3 | `true` | -| `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` | -| `connection` | Various connection options described below | | +| Setting | Description | Default | +|---------------------|-------------|---------| +| `enabled` | Enable/disable object storage. | `false` | +| `remote_directory` | The bucket name where LFS objects are stored. | | +| `direct_upload` | Set to true to enable direct upload of LFS without the need of local shared storage. Option may be removed after we decide to support only single storage for all files. | `false` | +| `background_upload` | Set to false to disable automatic upload. Option may be removed once upload is direct to S3. | `true` | +| `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data. | `false` | +| `connection` | Various connection options described below. | | See [the available connection settings for different providers](../object_storage.md#connection-settings). @@ -131,10 +129,9 @@ end ### S3 for Omnibus installations -On Omnibus installations, the settings are prefixed by `lfs_object_store_`: +On Omnibus GitLab installations, the settings are prefixed by `lfs_object_store_`: -1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with - the values you want: +1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, replacing values based on your needs: ```ruby gitlab_rails['lfs_object_store_enabled'] = true @@ -151,17 +148,17 @@ On Omnibus installations, the settings are prefixed by `lfs_object_store_`: } ``` -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. 1. Migrate any existing local LFS objects to the object storage: ```shell gitlab-rake gitlab:lfs:migrate ``` - This will migrate existing LFS objects to object storage. New LFS objects - will be forwarded to object storage unless + This migrates existing LFS objects to object storage. New LFS objects + are forwarded to object storage unless `gitlab_rails['lfs_object_store_background_upload']` and `gitlab_rails['lfs_object_store_direct_upload']` is set to `false`. -1. Optional: Verify all files migrated properly. +1. (Optional) Verify all files migrated properly. From [PostgreSQL console](https://docs.gitlab.com/omnibus/settings/database.html#connecting-to-the-bundled-postgresql-database) (`sudo gitlab-psql -d gitlabhq_production`) verify `objectstg` below (where `file_store=2`) has count of all artifacts: @@ -204,17 +201,17 @@ For source installations the settings are nested under `lfs:` and then path_style: true ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file, and then [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. 1. Migrate any existing local LFS objects to the object storage: ```shell sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production ``` - This will migrate existing LFS objects to object storage. New LFS objects - will be forwarded to object storage unless `background_upload` and `direct_upload` is set to + This migrates existing LFS objects to object storage. New LFS objects + are forwarded to object storage unless `background_upload` and `direct_upload` is set to `false`. -1. Optional: Verify all files migrated properly. +1. (Optional) Verify all files migrated properly. From PostgreSQL console (`sudo -u git -H psql -d gitlabhq_production`) verify `objectstg` below (where `file_store=2`) has count of all artifacts: ```shell @@ -233,7 +230,7 @@ For source installations the settings are nested under `lfs:` and then ### Migrating back to local storage -In order to migrate back to local storage: +To migrate back to local storage: 1. Set both `direct_upload` and `background_upload` to `false` under the LFS object storage settings. Don't forget to restart GitLab. 1. Run `rake gitlab:lfs:migrate_to_local` on your console. @@ -241,17 +238,18 @@ In order to migrate back to local storage: ## Storage statistics -You can see the total storage used for LFS objects on groups and projects -in the administration area, as well as through the [groups](../../api/groups.md) -and [projects APIs](../../api/projects.md). +You can see the total storage used for LFS objects on groups and projects: + +- In the administration area. +- In the [groups](../../api/groups.md) and [projects APIs](../../api/projects.md). ## Troubleshooting: `Google::Apis::TransmissionError: execution expired` If LFS integration is configured with Google Cloud Storage and background uploads (`background_upload: true` and `direct_upload: false`), Sidekiq workers may encounter this error. This is because the uploading timed out with very large files. -LFS files up to 6Gb can be uploaded without any extra steps, otherwise you need to use the following workaround. +LFS files up to 6 GB can be uploaded without any extra steps, otherwise you need to use the following workaround. -Log into Rails console: +Sign in to Rails console: ```shell sudo gitlab-rails console @@ -282,6 +280,6 @@ See more information in [!19581](https://gitlab.com/gitlab-org/gitlab-foss/-/mer - Support for removing unreferenced LFS objects was added in 8.14 onward. - LFS authentications via SSH was added with GitLab 8.12. -- Only compatible with the Git LFS client versions 1.1.0 and up, or 1.0.2. -- The storage statistics currently count each LFS object multiple times for +- Only compatible with the Git LFS client versions 1.1.0 and later, or 1.0.2. +- The storage statistics count each LFS object multiple times for every project linking to it. |