Omnibus GitLab High Availability Roles

Tier: Free, Premium, Ultimate Offering: Self-managed

Omnibus GitLab includes various software components/services to support running GitLab in a high availability configuration. By default, some of these supporting services are disabled, and Omnibus GitLab is configured to run as a single node installation. Each service can be enabled or disabled using configuration settings in /etc/gitlab/gitlab.rb, but the introduction of roles allows you to easily enable a group of services, and provides better default configuration based on the high availability roles you have enabled.

Not specifying any Roles (the default configuration)

When you don’t configure GitLab with any roles, GitLab enables the default services for a single node install. These include things like PostgreSQL, Redis, Puma, Sidekiq, Gitaly, GitLab Workhorse, NGINX, etc.

These can still be individually enable/disabled by the settings in your /etc/gitlab/gitlab.rb.

Specifying Roles

Roles are passed as an array in /etc/gitlab/gitlab.rb

Example specifying multiple roles: 

roles ['redis_sentinel_role', 'redis_master_role']

Example specifying a single role: 

roles ['geo_primary_role']

Roles

The majority of the following roles will only work on a GitLab Enterprise Edition, meaning a gitlab-ee Omnibus package. It will be mentioned next to each role.

GitLab App Role

  • application_role (gitlab-ce/gitlab-ee)

    The GitLab App role is used to configure an instance where only GitLab is running. Redis, PostgreSQL, and Consul services are disabled by default.

Redis Server Roles

Documentation on the use of the Redis Roles can be found in Configuring Redis for Scaling

  • redis_sentinel_role (gitlab-ee)

    Enables the sentinel service on the machine,

    By default, enables no other services.

  • redis_master_role (gitlab-ee)

    Enables the Redis service and monitoring, and allows configuring the master password

    By default, enables no other services.

  • redis_replica_role (gitlab-ee, introduced in GitLab 13.0)

    Enables the Redis service and monitoring

    By default, enables no other services.

GitLab Geo Roles

The GitLab Geo roles are used for configuration of GitLab Geo sites. See the Geo Setup Documentation for configuration steps.

  • geo_primary_role (gitlab-ee)

    This role:

    • Configures a single-node PostgreSQL database as a leader for streaming replication.
    • Prevents automatic upgrade of PostgreSQL since it requires downtime of streaming replication to Geo secondary sites.
    • Enables all single-node GitLab services including NGINX, Puma, Redis, and Sidekiq. If you are segregating services, then you must explicitly disable unwanted services in /etc/gitlab/gitlab.rb. Therefore, this role is only useful on a single-node PostgreSQL in a Geo primary site.
    • Cannot be used to set up a PostgreSQL cluster in a Geo primary site. Instead, see Geo multi-node database replication.

    By default, enables standard single-node GitLab services including NGINX, Puma, Redis, and Sidekiq.

  • geo_secondary_role (gitlab-ee)

    • Configures the secondary read-only replica database for incoming replication.
    • Configures the Rails connection to the Geo tracking database.
    • Enables the Geo tracking database geo-postgresql.
    • Enables the Geo Log Cursor geo-logcursor.
    • Disables automatic database migrations on the read-only replica database during reconfigure.
    • Reduces the number of Puma workers to save memory for other services.
    • Sets gitlab_rails['enable'] = true.

    This role is intended to be used in a Geo secondary site running on a single node. If using this role in a Geo site with multiple nodes, undesired services will need to be explicitly disabled in /etc/gitlab/gitlab.rb. See Geo for multiple nodes.

    This role should not be used to set up a PostgreSQL cluster in a Geo secondary site. Instead, see Geo multi-node database replication.

    By default, enables all of the GitLab default single node services. (NGINX, Puma, Redis, Sidekiq, etc)

Monitoring Roles

History

Monitoring roles are used to set up monitoring of installations. For additional information, see the Monitoring documentation.

  • monitoring_role (gitlab-ce/gitlab-ee)

    Configures a central monitoring server to collect metrics and provide dashboards.

    Enables Prometheus and Alertmanager.

PostgreSQL Roles

Documentation on the usage of the PostgreSQL Roles can be found in Configuring PostgreSQL for Scaling

  • postgres_role (gitlab-ce/gitlab-ee)

    Enables the PostgreSQL service on the machine

    By default, enables no other services.

  • patroni_role (gitlab-ee, introduced in GitLab 13.8)

    Enables the PostgreSQL, patroni, and Consul services on the machine

    By default, enables no other services.

  • pgbouncer_role (gitlab-ee)

    Enables the PgBouncer and Consul services on the machine

    By default, enables no other services.

  • consul_role (gitlab-ee)

    Enables the Consul service on the machine

    By default, enables no other services.

GitLab Pages Roles

History

GitLab Pages roles are used to setup and configure GitLab Pages. For additional information, see the GitLab Pages Administration documentation

  • pages_role (gitlab-ce/gitlab-ee)

    Configures the server with a GitLab Pages instance.

    By default, enables no other services.

Sidekiq Roles

History

Sidekiq roles are used to setup and configure Sidekiq. For additional information, see the Sidekiq Administration documentation

  • sidekiq_role (gitlab-ce/gitlab-ee)

    Configures the server with Sidekiq service.

    By default, enables no other services.

Spamcheck Roles

History

Spamcheck roles are used to setup and configure Spamcheck services. For additional information, see the Spamcheck documentation

  • spamcheck_role (gitlab-ee)

    Configures the server with spamcheck and spam-classifier services.

    By default, enables no other services.