Commit 8b5c118d authored by Marcia Ramos's avatar Marcia Ramos

Merge branch 'docs/lfs-s3-ce' into 'master'

Refactor the LFS S3 docs

See merge request gitlab-org/gitlab-ce!18029
parents 6b5ec93a f7f98faa
...@@ -19,7 +19,7 @@ There are various configuration options to help GitLab server administrators: ...@@ -19,7 +19,7 @@ There are various configuration options to help GitLab server administrators:
* Changing the location of LFS object storage * Changing the location of LFS object storage
* Setting up AWS S3 compatible object storage * Setting up AWS S3 compatible object storage
### Omnibus packages ### Configuration for Omnibus installations
In `/etc/gitlab/gitlab.rb`: In `/etc/gitlab/gitlab.rb`:
...@@ -33,7 +33,7 @@ gitlab_rails['lfs_enabled'] = false ...@@ -33,7 +33,7 @@ gitlab_rails['lfs_enabled'] = false
gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects" gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects"
``` ```
### Installations from source ### Configuration for installations from source
In `config/gitlab.yml`: In `config/gitlab.yml`:
...@@ -44,20 +44,21 @@ In `config/gitlab.yml`: ...@@ -44,20 +44,21 @@ In `config/gitlab.yml`:
storage_path: /mnt/storage/lfs-objects storage_path: /mnt/storage/lfs-objects
``` ```
## Setting up S3 compatible object storage ## Storing the LFS objects in an S3-compatible object storage
> **Note:** [Introduced][ee-2760] in [GitLab Premium][eep] 10.0. > [Introduced][ee-2760] in [GitLab Premium][eep] 10.0. Brought to GitLab Core
> Available in [GitLab CE][ce] 10.7 in 10.7.
It is possible to store LFS objects on remote object storage instead of on a local disk. It is possible to store LFS objects on a remote object storage which allows you
to offload storage to an external AWS S3 compatible service, freeing up disk
space locally. You can also host your own S3 compatible storage decoupled from
GitLab, with with a service such as [Minio](https://www.minio.io/).
This allows you to offload storage to an external AWS S3 compatible service, freeing up disk space locally. You can also host your own S3 compatible storage decoupled from GitLab, with with a service such as [Minio](https://www.minio.io/). Object storage currently transfers files first to GitLab, and then on the
object storage in a second stage. This can be done either by using a rake task
to transfer existing objects, or in a background job after each file is received.
Object storage currently transfers files first to GitLab, and then on the object storage in a second stage. This can be done either by using a rake task to transfer existing objects, or in a background job after each file is received. The following general settings are supported.
### Object Storage Settings
For source installations the following settings are nested under `lfs:` and then `object_store:`. On omnibus installs they are prefixed by `lfs_object_store_`.
| Setting | Description | Default | | Setting | Description | Default |
|---------|-------------|---------| |---------|-------------|---------|
...@@ -68,9 +69,7 @@ For source installations the following settings are nested under `lfs:` and then ...@@ -68,9 +69,7 @@ For source installations the following settings are nested under `lfs:` and then
| `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` | | `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 | | | `connection` | Various connection options described below | |
#### S3 compatible connection settings The `connection` settings match those provided by [Fog](https://github.com/fog).
The connection settings match those provided by [Fog](https://github.com/fog), and are as follows:
| Setting | Description | Default | | Setting | Description | Default |
|---------|-------------|---------| |---------|-------------|---------|
...@@ -82,8 +81,43 @@ The connection settings match those provided by [Fog](https://github.com/fog), a ...@@ -82,8 +81,43 @@ The connection settings match those provided by [Fog](https://github.com/fog), a
| `endpoint` | Can be used when configuring an S3 compatible service such as [Minio](https://www.minio.io), by entering a URL such as `http://127.0.0.1:9000` | (optional) | | `endpoint` | Can be used when configuring an S3 compatible service such as [Minio](https://www.minio.io), by entering a URL such as `http://127.0.0.1:9000` | (optional) |
| `path_style` | Set to true to use `host/bucket_name/object` style paths instead of `bucket_name.host/object`. Leave as false for AWS S3 | false | | `path_style` | Set to true to use `host/bucket_name/object` style paths instead of `bucket_name.host/object`. Leave as false for AWS S3 | false |
### S3 for Omnibus installations
On Omnibus 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:
```ruby
gitlab_rails['lfs_object_store_enabled'] = true
gitlab_rails['lfs_object_store_remote_directory'] = "lfs-objects"
gitlab_rails['lfs_object_store_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'aws_access_key_id' => '1ABCD2EFGHI34JKLM567N',
'aws_secret_access_key' => 'abcdefhijklmnopQRSTUVwxyz0123456789ABCDE',
# The below options configure an S3 compatible host instead of AWS
'host' => 'localhost',
'endpoint' => 'http://127.0.0.1:9000',
'path_style' => true
}
```
1. Save the file and [reconfigure GitLab]s for the changes to take effect.
1. Migrate any existing local LFS objects to the object storage:
```bash
gitlab-rake gitlab:lfs:migrate
```
This will migrate existing LFS objects to object storage. New LFS objects
will be forwarded to object storage unless
`gitlab_rails['lfs_object_store_background_upload']` is set to false.
### From source ### S3 for installations from source
For source installations the settings are nested under `lfs:` and then
`object_store:`:
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
lines: lines:
...@@ -108,44 +142,13 @@ The connection settings match those provided by [Fog](https://github.com/fog), a ...@@ -108,44 +142,13 @@ The connection settings match those provided by [Fog](https://github.com/fog), a
1. Save the file and [restart GitLab][] for the changes to take effect. 1. Save the file and [restart GitLab][] for the changes to take effect.
1. Migrate any existing local LFS objects to the object storage: 1. Migrate any existing local LFS objects to the object storage:
```bash ```bash
sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production 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
`gitlab_rails['lfs_object_store_background_upload']` is set to false.
### In Omnibus
1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with
the values you want:
```ruby
gitlab_rails['lfs_object_store_enabled'] = true
gitlab_rails['lfs_object_store_remote_directory'] = "lfs-objects"
gitlab_rails['lfs_object_store_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'aws_access_key_id' => '1ABCD2EFGHI34JKLM567N',
'aws_secret_access_key' => 'abcdefhijklmnopQRSTUVwxyz0123456789ABCDE',
# The below options configure an S3 compatible host instead of AWS
'host' => 'localhost',
'endpoint' => 'http://127.0.0.1:9000',
'path_style' => true
}
```
1. Save the file and [reconfigure GitLab]s for the changes to take effect.
1. Migrate any existing local LFS objects to the object storage:
```bash
gitlab-rake gitlab:lfs:migrate
```
This will migrate existing LFS objects to object storage. New LFS objects This will migrate existing LFS objects to object storage. New LFS objects
will be forwarded to object storage unless will be forwarded to object storage unless `background_upload` is set to
`gitlab_rails['lfs_object_store_background_upload']` is set to false. false.
## Storage statistics ## Storage statistics
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment