Optimize GitLab object storage for scale and performance

Managing GitLab at scale requires strategic object storage configuration.

Here's how to configure object storage for maximum performance, security,

and reliability across your GitLab components.

Use consolidated form for GitLab components

For artifacts, LFS, uploads, packages, and other GitLab data, eliminate credential duplication with the consolidated form:

gitlab_rails['object_store']['enabled'] = true

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

gitlab_rails['object_store']['objects']['artifacts']['bucket'] = 'gitlab-artifacts'

gitlab_rails['object_store']['objects']['lfs']['bucket'] = 'gitlab-lfs'

# ... additional buckets for each object type

This reduces complexity while enabling encrypted S3 buckets and proper Content-MD5 headers.

Configure container registry separately

The container registry requires its own configuration since it doesn't support the consolidated form:

registry['storage'] = {
  's3_v2' => {  # Use the new v2 driver
    'bucket' => 'gitlab-registry',
    'region' => 'us-east-1',
    # Omit access keys to use IAM roles
  }
}

Note: The s3_v1 driver is deprecated and will be removed in GitLab 19.0. Migrate to s3_v2 for better performance and reliability.

Disable proxy download for performance

Set proxy_download to false (default) for direct downloads:

# For GitLab objects - can be set globally

gitlab_rails['object_store']['proxy_download'] = false

# Or configure per bucket for granular control

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

gitlab_rails['object_store']['objects']['lfs']['proxy_download'] = false

gitlab_rails['object_store']['objects']['uploads']['proxy_download'] = true  # Example: keep proxy for uploads

# Container registry defaults to redirect mode (direct downloads)

# Only disable if your environment requires it:

registry['storage']['redirect']['disable'] = false  # Keep as false

Important: The proxy_download option can be configured globally at the object-store level or individually per bucket. This gives you flexibility to optimize based on your specific use case — for example, you might want direct downloads for large artifacts and LFS files, but proxy smaller uploads through GitLab for additional security controls.

This dramatically reduces server load and egress costs by letting clients download directly from object storage.

Choose identity-based authentication

AWS: Use IAM roles instead of access keys:

# GitLab objects

gitlab_rails['object_store']['connection'] = {
  'provider' => 'AWS',
  'use_iam_profile' => true
}

# Container registry

registry['storage'] = {
  's3_v2' => {
    'bucket' => 'gitlab-registry',
    'region' => 'us-east-1'
    # No access keys = IAM role authentication
  }
}

Google Cloud Platform: Enable application default credentials:

gitlab_rails['object_store']['connection'] = {
  'provider' => 'Google',
  'google_application_default' => true
}

Azure: Use workload identities by omitting storage access keys.

Add encryption layers

Enable server-side encryption for additional security:

# GitLab objects

gitlab_rails['object_store']['storage_options'] = {
  'server_side_encryption' => 'AES256'
}

# Container registry

registry['storage'] = {
  's3_v2' => {
    'bucket' => 'gitlab-registry',
    'encrypt' => true
  }
}

For AWS KMS encryption, specify the key ARN in server_side_encryption_kms_key_id.

Use separate buckets for organization

Create dedicated buckets for each component:

• gitlab-artifacts - CI/CD job artifacts

• gitlab-lfs - Git LFS objects

• gitlab-uploads - User uploads

• gitlab-packages - Package registry

• gitlab-registry - Container images

This isolation improves security, enables granular access controls, and simplifies cost tracking.

Key configuration differences

Component	Consolidated Form	Identity Auth	Encryption	Direct Downloads
Artifacts, LFS, Packages	✅ Supported	✅ use_iam_profile	✅ storage_options	✅ proxy_download: false
Container Registry	❌ Separate config	✅ Omit access keys	✅ encrypt: true	✅ redirect enabled by default

Migration path

1. Start with GitLab objects: Use the consolidated form for immediate complexity reduction.

2. Configure registry separately: Use s3_v2 driver with IAM authentication.

3. Enable encryption: Add server-side encryption for both components.

4. Optimize performance: Ensure direct downloads are enabled with appropriate proxy_download settings.

5. Set up lifecycle policies: Configure S3 lifecycle rules to clean up incomplete multipart uploads.

Additional resources

For a complete AWS S3 configuration example, see the GitLab documentation on AWS S3 object storage setup.

For more details on configuring proxy_download parameters per bucket, refer to the GitLab object storage configuration documentation.

These configurations will scale with your growth while maintaining security and performance. The separation between GitLab object storage and container registry configurations reflects their different underlying architectures, but both benefit from the same optimization principles.