ℹ️ The GitLab Environment Toolkit is a collection of opinionated Terraform and Ansible scripts to assist with the deployment of a self managed GitLab environment. It's recommended that users review the Before You Start section before use. Users should have a good working knowledge of Infrastructure management, Terraform, Ansible and GitLab administration as well as be aware that ultimately self managed environments are the responsibility of the user. As such, it's strongly recommended that you independently review the Toolkit in full to ensure it meets your requirements, especially around security or data integrity.
If upgrading, it's always recommended to review the release notes in full as well as the relevant documentation and to upgrade the Toolkit first before the environment.
[[TOC]]
New Key Features
Beta GitLab Operator Support
- Merge Request(s): !1475
- Documentation
- Deploying Cloud Native environments with the GitLab Operator is now supported!
ℹ️ Support for this feature in the Toolkit is in Beta.
Thanks @niskhakova!
Expanded Cloud Provider Tagging / Labelling Support
- Merge Request(s): !1465 !1467 !1485
- Documentation
Support for tagging or labelling Cloud Provider resources has been redesigned and expanded. More resources are now taggable with more flexible options available to tag individually as required.
Thanks @nwestbury!
Ansible 11 Support
- Merge Request(s): !1466
The supported version of Ansible has been updated to 11.x (ansible-core version 2.18)!
Note this requires Python 3.11 to be used on the control node and support for older core versions is still in place. Refer to the Upgrade Notes section for more information.
Further Updates and Improvements
- Default Ubuntu version has been updated to
24.04LTS for new environments. Note that this does not impact existing environments. !1472
- Ubuntu
20.04is to enter End of Life in April 2024. Refer to the Deprecation Notes section for more information.
- Ubuntu
- Persistent Volume StorageClass handling has been added for Cloud Native environments with the optional Monitoring stack enabled. Refer to the Upgrade Notes section for more information. !1488
- Gitaly client config has been updated to the new format for GitLab environments running
17.8or higher. Refer to the Upgrade Notes section for more information. !1499 (thanks@nwestbury!)
- Unified URLs are now supported for Cloud Native Geo environments. !1399 (thanks
@nwestbury!)
- Added ability to resume a Zero Downtime Upgrade from a specific component. !1459 (thanks
@yushao.sqpc!)
- Helm install options have been expanded, including offline install support. !1334 (thanks
@nprabakaran@niskhakova!)
- Health Check URLs options have been expanded. Refer to the Documentation for more information. !1507
- The GKE Dataplane V2 networking option can now be enabled. !1437
- GKE node pools will now be recreated correctly if the Cluster is replaced. !1481 (thanks
@nolith!)
- Data Cache option added for GCP Cloud SQL. !1433 (thanks
@james.a.adamo!)
- Update timeout option added for GCP Memorystore. !1461 (thanks
@psingh29!)
- Custom metadata can now be configured for GCP VMs. !1487 (thanks
@bbechtel!)
- GCP Service Account permissions have been fixed for GKE Cloud Native deployments. !1513
- AWS EKS Metrics Server version can now be configured. !1449 (thanks
@ktchernov!)
- EKS Upgrade Policy can now be configured. !1495
- Option added for AWS RDS Monitoring Interval. !1453 (thanks
@KielDevops1!)
- Backup options can now be configured for AWS RDS Replicas. !1474
- Apply method can now be set for AWS RDS parameters. !1500
- RDS Support Lifecycle can now be configured. !1503
- Custom throughput can be configured for OpenSearch Service gp3 volumes. !1462 (thanks
@vmundo!)
- Deletion protection options for AWS RDS and GCP Cloud SQL have been added. !1516 !1517 (thanks
@nwestbury!)
- Old HAProxy and OpenSearch Docker images are now pruned by default. !1434
- Postgres version for Linux package installs can now be configured via environment variable. !1430 (thanks
@nwestbury!)
- Cloud Native pod identification has been switched to a label based approach to accommodate some edge cases. !1457 (thanks
@vmondo!)
- The newly added Linux package
gitaly_roleoption is now used for environments running GitLab 17.6. !1442 (thanks@balasankarc!)
- Multi External Redis setups with separate passwords have been handled to accommodate an upstream issue in the GitLab Charts. !1492 (thanks
@bbechtel!)
- Custom Gitaly Cluster storage paths will now be created automatically if missing. !1502 (thanks
@psingh29!)
- Documentation has been added for alternative AWS SSM connection configuration. !1445
- Option added to disable Rails SSH key handling between nodes. !1523 (thanks
@nicola.beirer!)
- AWS S3 Policies have been adjusted to be more lean and fix support for backups. !1520
- Fixed an issue for Debian 12 targets with HAProxy and Let's Encrypt SSL generation. !1484
- Several improvements and fixes have been made for Geo deployments. !1471 !1475 !1477 !1494 !1501 !1506 !1508 !1512
- Various other small updates, improvements and fixes.
Upgrade Notes
Ansible 11 version upgrade
- The target supported version of Ansible has been increased to
11.0(community) /2.18(core). Users will need to upgrade their version if it's lower before running Ansible.
- ℹ️ This version of Ansible requires Python 3.11 to be used on the control node running Ansible.
- ℹ️ This version of Ansible requires Python 3.11 to be used on the control node running Ansible.
ℹ️ Older versions of Ansible Core will continue to be supported until they hit EOL. This is to accommodate users who are running against RHEL 8 and Amazon Linux 2 targets. As a reminder Ansible has deprecated support for these Operating System targets, with support ending in May 2025.
Cloud Native Monitoring stack - Persistent Volume StorageClass handling
The Toolkit will now create StorageClass config on AWS EKS and GCP GKE for it's deployments that make a Persistent Volume Claim. This is to handle the upstream change on AWS EKS, where a default is no longer set from 1.30 upwards.
This applies only for the optional Monitoring stack and only for new deployments. Existing deployments with this stack will see no changes occur and the same StorageClass will be used.
Refer to the documentation for the full details.
Gitaly client config update (git_data_dirs)
Gitaly client config has a new format in GitLab 17.8 onwards and it will become required in 18.0 where the old format (git_data_dirs) will be removed.
In preparation for this the Toolkit will switch environments running 17.8 or higher to the new format. Users should see no impact to this internal change.
Expected Terraform Changes
- Several additional outputs have been added for Kubernetes in GCP and AWS deployments
- GCP Service Account permissions have been updated with correct Service Account User Member roles for Cloud Native deployments
- AWS S3 permissions have been updated to include the
listpermission, following latest guidance
- If using the previous
additional_tagsoradditional_labelsfeature several additional resources will now be tagged with the one you have set such as Data Disks.
Deprecation Notices
Support for Ubuntu 20.04
ℹ️ For awareness the same notice from 3.4.0 is being repeated in this release.
Ubuntu 20.04 maintenance support is expected to reach End of Life in April 2025. To give as much notice as possible, support in the Toolkit will be deprecated after this date.
Users who are targeting this OS version are recommended to upgrade at the earliest opportunity to a newer OS version for continued support and compatibility with the GitLab Environment Toolkit.
Terraform variable name changes
The following Ansible variables have been renamed. The old names are now deprecated but will continue to work until the next major release (4.x):
additional_tags>custom_tags(AWS/Azure),additional_labels>custom_labels(GCP)
object_storage_tags>object_storage_custom_labels(AWS/Azure),object_storage_labels>object_storage_custom_labels(GCP)
rds_postgres_tags>rds_postgres_custom_tags,rds_praefect_postgres_tags>rds_praefect_postgres_custom_tags,rds_geo_tracking_postgres_tags>rds_geo_tracking_postgres_custom_tags.
elasticache_redis_tags>elasticache_redis_custom_tags,elasticache_redis_cache_tags>elasticache_redis_custom_cache_tags,elasticache_redis_persistent_tags>elasticache_redis_persistent_custom_tags(AWS)
opensearch_service_tags>opensearch_service_custom_tags(AWS)
gitlab_rails_readiness_url>gitlab_rails_local_health_check_url
Feedback
Got any feedback or found an issue? Please feel free to create an issue on our tracker.