GitLab Environment Toolkit

The GitLab Environment Toolkit (GET) is a set of opinionated Terraform and Ansible scripts to assist with deploying scaled GitLab environments following the Reference Architectures.

The Toolkit supports the following features:

• Support for deploying all Reference Architectures sizes dynamically from 1k to 50k.
• Support for deploying Cloud Native Hybrid variants of the Reference Architectures (AWS & GCP only at this time).
• GCP, AWS and Azure (Linux package (Omnibus)) cloud provider support
• Upgrades
• Release and nightly Linux package (Omnibus) builds support
• Advanced search with OpenSearch
• Geo support
• Container Registry support
• Zero Downtime Upgrades support
• Built-in optional Load Balancing and Monitoring (Prometheus) setup
• SSL / TLS support (either direct or via hooks)
• Alternative sources (Cloud Services, Custom Servers) for select components (Load Balancers, PostgreSQL, Redis)
• On Prem Support (Ansible)
• Custom Config / Tasks / Files support

Before You Start

The Toolkit can help you with the deployment and maintenance of a scaled GitLab environment. But please note it does not remove any of the underlying challenges that comes with running large production applications and that ultimately environments are the responsibility of the user. As such, users are recommended to have a good working knowledge of Terraform, Ansible, GitLab administration and Infrastructure management as well be aware of what running such an environment entails. For users who aren't in this position, our Professional Services team offers implementation services, but for those who want a more managed solution long term, it's recommended to instead explore our other offerings such as GitLab SaaS or GitLab Dedicated.

The Toolkit is designed to be flexible, and to follow best practices for GitLab. However, the scripts are opinionated, presented as-is, and may not be compatible with your specific environment build needs. There may be cases where you will need to extend or customize the Toolkit for your unique needs.

Review the Toolkit in full before any use, as it offers no guarantees on topics such as security or data integrity.

Further manual setup after deployment may also be required.

Requirements

The requirements for the Toolkit are as follows:

Host machine:

• Terraform 1.9.0 and upwards
• Ansible 11.0 and upwards (Ansible core 2.18, Python 3.11+)

Target machine(s):

• GitLab version: 15.0.0 and upwards.
• OS: Ubuntu 20.04 / 22.04 / 24.04, Debian 11 / 12, RHEL 9, Amazon Linux 2023
  • ℹ️  RHEL 8 and Amazon Linux 2 support is deprecated due to Ansible support removal. See this section for more information.
  • The Toolkit has been designed to target clean OS installations. It may work with existing installations, but this is not currently being tested.
  • Admin access to the OS is also required by GET to install various dependencies.
  • ARM based hardware is supported for Linux package (Omnibus) environments.
• Kubernetes (Cloud Native): Supported versions as denoted by Kubernetes or the hosting service.

Documentation

• GitLab Environment Toolkit - Quick Start Guide
• GitLab Environment Toolkit - Preparing the environment
• GitLab Environment Toolkit - Provisioning the environment with Terraform
• GitLab Environment Toolkit - Configuring the environment with Ansible
• GitLab Environment Toolkit - Advanced - Custom Config / Tasks / Files, Data Disks, Advanced Search, Container Registry and more
• GitLab Environment Toolkit - Advanced - Cloud Native Hybrid
• GitLab Environment Toolkit - Advanced - Component Cloud Services / Custom (Load Balancers, PostgreSQL, Redis)
• GitLab Environment Toolkit - Advanced - SSL
• GitLab Environment Toolkit - Advanced - Network Setup
• GitLab Environment Toolkit - Advanced - Monitoring
• GitLab Environment Toolkit - Upgrades (Toolkit, Environment)
• GitLab Environment Toolkit - Considerations After Deployment - Backups, Security
• GitLab Environment Toolkit - Geo
  • GitLab Environment Toolkit - Geo - Provisioning the environment with Terraform
  • GitLab Environment Toolkit - Geo - Configuring the environment with Ansible
  • GitLab Environment Toolkit - Geo - Advanced
• GitLab Environment Toolkit - Troubleshooting

Config Examples

Full config examples are available for select Reference Architectures.

How To Use

The Toolkit's Terraform and Ansible scripts can be used in various ways depending on your requirements:

• Terraform - Source (git checkout), Docker, Module Registry
• Ansible - Source (git checkout), Docker, Collection

Refer to the docs above for full instructions on each.

How It Works

At a high level the Toolkit is designed to be as straightforward as possible. A high level overview of how it works is as follows:

• Machines and associated infrastructure are provisioned as per the Reference Architectures with Terraform. Part of this provisioning includes adding specific labels / tags to each machine for Ansible to then use to identify.
• Machines are configured with Ansible. Through identifying each machine by its labels / tags, Ansible will go through them in the correct installation order. On each it will install and configure the Linux package (Omnibus) to set up the intended component as required. The Ansible scripts have been designed to handle certain dynamic setups depending on what machines have been provisioned (e.g. an environment without OpenSearch, or a 2k environment with a smaller amount of nodes). Additional tasks are also performed as required such as setting GitLab config through Rails or Load Balancer / Monitoring setup.

Troubleshooting

Please refer to our Troubleshooting guide if you are having issues deploying an environment with the Toolkit.

Support

Technical support is only available for the current Toolkit major version and requests should be raised via the Support team.

Issues specific to the Toolkit code can also be raised in our tracker.

Feature Requests

The Toolkit is opinionated by necessity, as there is a vast amount of options and permutations available when deploying infrastructure across various Cloud Providers or on-prem.

Consequently, during our independent review of feature requests, we might determine that some are not feasible to implement according to Toolkit's opinionated approach. In some cases, it could be more straightforward and quicker for you to tackle it separately.

However, we do welcome Feature Requests that could be valuable to add for other users. If you have such a request please raise it in our tracker, but we do ask that you check beforehand to see if it's already been raised.

Features that won't be covered

Due to complexities, permutations or areas best left to be configured directly we do not plan to include the following:

• Cloud accounts management
• Observability stack beyond Prometheus
• Direct OmniAuth and Email support
• DNS server management
• Full GitLab agent server for Kubernetes (KAS) setup
• On Prem HA Load Balancers
• Downgrades

Some of the above areas are better tackled via Custom Config.

Contributions

This project accepts contributions to existing features. Refer to the Contributing guide for more information.

Testing

If you wish to test the GitLab Environment Toolkit or use it for testing a scaled GitLab deployment it must be noted this can incur notable costs.

Refer to the Testing document for more information.

Licensing

Requires GitLab Premium or above.

Released under the GitLab EE license.