Deploy GitLab to enable CI/CD pipelines on OCI

Architecture

This reference architecture has two deployment options: A standalone deployment and a distributed deployment.

Standalone (<1,000 users)
The standalone architecture is the simplest option for GitLab. It deploys all GitLab components into a single Compute instance within your OCI tenancy. If you need to serve up to 1,000 users and you don’t have strict availability requirements, a standalone solution with frequent backups is appropriate for many organizations. A single tenancy can host more than one GitLab server. The following diagram illustrates this reference architecture:

Description of the illustration deploy_gitlab_sa.png
Distributed (1000–2000 users)
The distributed solution is a multitier architecture that separates the various components of a dedicated GitLab server into separate instances, each assigned to perform a specific task. Specifically, the distributed architecture has a dedicated PostgreSQL server, Redis Server, Gitaly servers, and Prometheus monitoring instance, which are all required for a fully functional GitLab deployment. Per GitLab recommendation, this distributed deployment supports approximately 2,000 users. It has higher performance than the standalone deployment and higher fault tolerance because of some built-in redundancies. However, the distributed deployment is not highly available.

Description of the illustration deploy_gitlab_dist.png

These architectures have the following components:

Region
An Oracle Cloud Infrastructure region is a localized geographic area that contains one or more data centers, called availability domains. Regions are independent of other regions, and vast distances can separate them (across countries or even continents).
Availability domains
Availability domains are standalone, independent data centers within a region. The physical resources in each availability domain are isolated from the resources in the other availability domains, which provides fault tolerance. Availability domains don’t share infrastructure such as power or cooling, or the internal availability domain network. So, a failure at one availability domain is unlikely to affect the other availability domains in the region. The instances deployed as part of these GitLab reference architectures all go into a single availability domain.
Virtual cloud network (VCN) and subnets
A VCN is a software-defined network that you set up in an OCI region. VCNs can be segmented into subnets, which can be specific to a region or to an availability domain. Both region-specific and availability domain-specific subnets can coexist in the same VCN. A subnet can be public or private. You can deploy this GitLab architecture into an existing VCN containing a public and private subnet or configure it to create a VCN with the required subnets.
- Bastion host subnet
  The bastion host subnet is a dedicated public subnet that contains the bastion host instance. The bastion host is an optional component of this architecture and is not required if GitLab is directly connected to the internet or public subnet.
- Load balancer subnet
  The load balancer subnet is a dedicated public subnet that contains the load balancer.
- GitLab private subnet
  The GitLab private subnet contains the two GitLab servers, the Gitaly servers, Redis server, Postgres server, the Prometheus-Grafana (monitoring) server, and any optional GitLab runners.
Load balancer
The load balancer contains the public-facing IP used to connect to the GitLab instances. If you want a custom domain name for your GitLab instance, register the IP address of the load balancer with the DNS provider. The load balancer uses a round robin health check policy for monitoring the GitLab servers.
Compute
For the GitLab, only a single GitLab server Compute instance is created. For the distributed architecture, a total of eight Compute instances are created. Each of these instances provides the following services:
- GitLab servers
  The primary GitLab web-based application is installed on the two GitLab servers. Administration of GitLab is performed on these instances and the load balancer acts as the frontend.
- PostgreSQL server
  Stores persistent database information for the GitLab application. For example, users, permissions, issues, or other metadata are stored in the PostgreSQL database.
- Redis Server
  The GitLab application uses Redis as a non-persistent database backend for job information, metadata, and incoming jobs.
- Gitaly Servers
  The Gitaly service provides file storage for Git repositories. All files that are part of a repository in GitLab are stored on the Gitaly servers. Two Gitaly instances are created to prove a level of extra capacity. You can customize which server stores the data for a particular project on a per-repository basis.
- PostgreSQL server
  GitLab stores persistent database information on the PostgreSQL server. Examples of persistent data include users, permissions, issues, and other project metadata.
- Redis server
  The GitLab application uses Redis as a non-persistent database backend for job information, certain types of metadata, and incoming jobs.
- Prometheus + Grafana (monitoring) server
  The Prometheus + Grafana server is a systems and service monitoring server. It collects metrics from configured targets at given intervals, evaluates rule expressions, displays the results, and can trigger alerts when specified conditions are observed.
- Runners
  GitLab runners are dedicated machines that work with GitLab CI/CD to run jobs in a pipeline. They're typically deployed into your GitLab environment after GitLab instances are up and running and tested. They're not created as part of the deployment.
Object Storage
The distributed deployment creates a series of Objects Storage buckets within your OCI tenancy, designed to store various types of data associated with your GitLab projects, including backups.

Recommendations

Use the following recommendations as a starting point when deploying GitLab to enable CI/CD pipelines on Oracle Cloud Infrastructure. Your requirements might differ from the architecture described here.

Compute shapes

This architecture uses an Oracle Linux OS image and support all families of Compute shapes, standard or flexible. GitLab recommends the following configuration parameters for the standalone and distributed deployment:

Standalone

Service

Configuration

GitLab server

4 OCPU, 8-GB RAM

GitLab runners (N optional)

1 OCPU, 4-GB RAM

Distributed

Service

Configuration

Bastion server (optional)

1 OCPU, 2-GB RAM

GitLab servers (2)

4 OCPU, 8-GB RAM

PostgreSQL

1 OCPU, 8-GB RAM

Redis

1 OCPU, 4-GB RAM

Gitaly (1 required, 2 optional)

2 OCPU, 16-GB RAM

Monitoring node

1 OCPU, 2-GB RAM

GitLab runners (N optional)

1 OCPU, 4-GB RAM

GitLab recommends these configurations, but you can customize at deployment time.

VCN
When you create VCN and subnets, use CIDR blocks that don't overlap with any other network (in OCI, your on-premises data center, or another cloud provider) to which you intend to set up private connections. VCN CIDR blocks are editable post creation.

When you design the subnets, consider your traffic flow and security requirements. Attach all the resources within a specific tier or role to the same subnet, which can serve as a security boundary.
Security
Use Oracle Cloud Guard to monitor and maintain the security of your resources in OCI proactively. Cloud Guard uses detector recipes that you can define to examine your resources for security weaknesses and to monitor operators and users for risky activities. When any misconfiguration or insecure activity is detected, Cloud Guard recommends corrective actions and assists with those actions, based on responder recipes that you can define.

For resources that require maximum security, Oracle recommends that you use security zones. A security zone is a compartment associated with an Oracle-defined recipe of security policies that are based on best practices. For example, the resources in a security zone must not be accessible from the public internet and they must be encrypted using customer-managed keys. When you create and update resources in a security zone, OCI validates the operations against the policies in the security-zone recipe, and denies operations that violate any of the policies.
Runners
You can deploy GitLab runners into the same private subnet as the existing GitLab instances or into a dedicated VCN or subnet.

Considerations

Consider the following points when deploying this reference architecture.

Performance
All default Compute shapes launched as part of this architecture follow the recommendations provided in the GitLab documentation. However, if a particle node needs more resources, you can scale the Compute shapes. The distributed architecture has higher performance than a standalone deployment. The architectures have the following expected performance metrics options.
Security
Except for the load balancer and bastion host, if present, all the components of the GitLab architecture are in private subnet. The Compute instances in the distributed architecture all have firewall enabled, with iptables on and only the necessary ports open to enable communication between the nodes.
Availability
The GitLab servers are deployed as a pair and balanced by the load balancer. All instances are deployed in a single availability domain. This reference architecture also creates several Object Storage buckets for storing various types of data. Object Storage is a regional service and is not tied to any specific Compute instance or availability domain. You can access data from anywhere inside or outside the context of OCI, as long you have internet connectivity and can access one of the Object Storage endpoints. This deployment uses a service gateway to connect to the object storage buckets. A service gateway allows connectivity to the Object Storage public endpoints from private IP addresses in private subnets
Backups and restore
The distributed deployment creates an Object Storage bucket for storing backups and sets all the configuration settings required for upload data to that bucket. It also creates a cron job on the primary GitLab server instance, which creates daily backups of the GitLab data, uploads to the bucket, and stores a copy on the machine. The gitlab-secrets.json file contains sensitive data and is not included in this backup. We recommend that you keep a copy of the /etc/gitlab directory or the /etc/gitlab/gitlab-secrets.json file in a safe place that exists outside of this deployment by an administrator. Consider if you want more frequent backups and set appropriate retention policies on the Object Storage bucket.
```
## Run a backup everyday at 1am.
0 1 * * * sudo gitlab-backup create
 
## Run a separate backup for configuration settings (creates a tar archive in /etc/gitlab/config_backup)
0 2 * * * sudo gitlab-ctl backup-etc
```
You can back up not just GitLab data but the entire GitLab server. The OCI Block Volume service allows you to perform block volume backups automatically on a schedule and retain them based on the selected backup policy. For more details, see Policy-Based Backups documentation.
Cost
The cost of this architecture is related to any OCI deployed infrastructure, such as Compute instances, network load balancer, and data storage, plus any licensing purchases from GitLab. For more information regarding cost of OCI services, see Oracles's Cloud Proce List page.
Public URL
Consider using you DNS provider to associate the public IP address of the GitLab instance to a custom domain name. In the distributed architecture, the custom URL should be associated with the public IP address of the load balancer. You can set the external URL domain name at deployment time and then associate the URL with the IP address in the GitLab deployment after. You can always change the custom URL after the fact.

Deploy

The Terraform code for this reference architecture is available as a sample stack in Oracle Cloud Infrastructure Resource Manager. You can also download the code from GitLab, and customize it to suit your specific requirements.

Deploy using the sample stack in Oracle Cloud Infrastructure Resource Manager:
1. Click .
  If you aren't already signed in, enter the tenancy and user credentials.
2. Select the region where you want to deploy the stack.
3. Follow the on-screen prompts and instructions to create the stack.
4. After creating the stack, click Terraform Actions, and select Plan.
5. Wait for the job to be completed, and review the plan.
  To make any changes, return to the Stack Details page, click Edit Stack, and make the required changes. Then, run the Plan action again.
6. If no further changes are necessary, return to the Stack Details page, click Terraform Actions, and select Apply.
Deploy using the Terraform code in GitLab:
1. Go to GitLab.
2. Clone or download the repository to your local computer.
3. Follow the instructions in the README document.

Explore More

Learn more about deploying GitLab to enable CI/CD pipelines on Oracle Cloud Infrastructure.

Review these additional resources: