DEBOPS.GITLAB(5)

NAME
debops.gitlab - Install and manage GitLab service

SYNOPSIS

debops service/gitlab [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The debops.gitlab role can be used to install and manage a GitLab instance. It supports automatic update of the currently installed version (when the role is executed), as well as upgrade to a next stable GitLab release. You can deploy the installation either on a single host, or a set of separate hosts, each one with a different service (database, application, webserver).

GETTING STARTED

  Role design

The debops.gitlab role is designed to install the GitLab services using the source installation method <https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md>. This method, instead of GitLab Omnibus packages, was chosen to allow use of other services managed by DebOps, like Redis, nginx, a SQL database, and so on. To support monthly GitLab releases, the role tracks currently installed version of GitLab and can perform an automatic upgrade when an older version is detected. Latest changes to the active GitLab branch are also automatically applied on Ansible runs, to support updates.

The installation or upgrade process is not ideal - role performs installation or an upgrade when new changes are detected in the git repositories, but if there are errors during this process, role cannot recover from that state automatically. It is advisable to keep a separate staging environment to check for any issues with an upgrade of the currently installed production environment before performing the production upgrade.

If a failed install or upgrade occurs, the easiest recovery method is usually to completely reset the affected host (perform a new deployment) after fixing the issue. The more involved method would be to remove the source git repositories and checked out directories and re-run the role again.

  SQL database support

The debops.gitlab role automatically detects the available PostgreSQL database using the Ansible local facts. If the database service should be present on the same host as the GitLab service, adding the corresponding database server group in the Ansible inventory should be enough. If the database server is on a different host, you should use the corresponding database client role to configure the relevant Ansible local facts before running the debops.gitlab role.

Installation of a new GitLab environment with existing database is currently not tested and may result in a broken installation or data corruption.

You can install the PostgreSQL database using its DebOps role. See the debops.postgresql_server role documentation for more details.

  Redis support

Currently the debops.gitlab role expects a Redis Server instance installed on the host, for example by the debops.redis_server Ansible role. Support for distributed Redis Server service managed by Redis Sentinel is planned for a future release.

  Docker Registry support

The debops.docker_registry Ansible role can be used as a backend to the GitLab Container Registry service. The debops.gitlab playbook will import the debops.docker_registry playbook to faciliate configuration synchronization between the two services. The installation process with Docker Registry role enabled will be:

•   Install PostgreSQL server, Redis Server

•   Install Docker Registry service

•   Install GitLab, using facts from Docker Registry role

•   Update Docker Registry service with facts from GitLab role

    This should avoid issue with circular dependencies in the configuration of both services. The Docker Registry requires PKI support, therefore it's good practice to apply the common.yml DebOps playbook, or at least the debops.pki role, before the GitLab installation begins.

  Support for other services

The debops.gitlab role depends on other DebOps roles to configure various services used by GitLab and provide the required environment for installation. The default role playbook is designed to install the services on the same host as the GitLab service, however it should be possible to move them to other, remote hosts if necessary.

The role provides its own set of systemd unit files that allow management of different GitLab services as one "unit" using systemd slice. The new units will be enabled automatically on all new installations on hosts that use the systemd service manager; on other, older hosts the role should fallback to the init script provided by the upstream.

  Example inventory

To enable GitLab service on a host, it needs to be included in the [debops_service_gitlab] Ansible inventory group. You should also enable a suitable PostgreSQL database and Redis Server service.

Example Ansible inventory:

[debops_all_hosts]
hostname
[debops_service_postgresql_server]
hostname
[debops_service_redis_server]
hostname
[debops_service_docker_registry]
hostname
[debops_service_gitlab]
hostname

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.gitlab role:

---
- name: Manage GitLab service
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_gitlab' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  pre_tasks:
    - name: Prepare gitlab environment
      import_role:
        name: 'gitlab'
        tasks_from: 'main_env'
      tags: [ 'role::gitlab', 'role::postgresql' ]
  roles:
    - role: keyring
      tags: [ 'role::keyring', 'skip::keyring',
              'role::nodejs', 'role::postgresql', 'role::nginx' ]
      keyring__dependent_apt_keys:
        - '{{ nodejs__keyring__dependent_apt_keys }}'
        - '{{ postgresql__keyring__dependent_apt_keys }}'
        - '{{ nginx__keyring__dependent_apt_keys }}'
    - role: system_groups
      tags: [ 'role::system_groups', 'skip::system_groups' ]
    - role: apt_preferences
      tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
      apt_preferences__dependent_list:
        - '{{ golang__apt_preferences__dependent_list }}'
        - '{{ nginx__apt_preferences__dependent_list }}'
        - '{{ nodejs__apt_preferences__dependent_list }}'
        - '{{ postgresql__apt_preferences__dependent_list }}'
        - '{{ ruby__apt_preferences__dependent_list }}'
        - '{{ gitlab__apt_preferences__dependent_list }}'
    - role: python
      tags: [ 'role::python', 'skip::python', 'role::mariadb', 'role::postgresql', 'role::ldap' ]
      python__dependent_packages3:
        - '{{ gitlab__python__dependent_packages3 }}'
        - '{{ nginx__python__dependent_packages3 }}'
        - '{{ postgresql__python__dependent_packages3 if gitlab__database == "postgresql" else [] }}'
        - '{{ ldap__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ gitlab__python__dependent_packages2 }}'
        - '{{ nginx__python__dependent_packages2 }}'
        - '{{ postgresql__python__dependent_packages2 if gitlab__database == "postgresql" else [] }}'
        - '{{ ldap__python__dependent_packages2 }}'
    - role: golang
      tags: [ 'role::golang', 'skip::golang' ]
    - role: nodejs
      tags: [ 'role::nodejs', 'skip::nodejs' ]
    - role: etc_services
      tags: [ 'role::etc_services', 'skip::etc_services' ]
      etc_services__dependent_list:
        - '{{ gitlab__etc_services__dependent_list }}'
    - role: cron
      tags: [ 'role::cron', 'skip::cron' ]
    - role: logrotate
      tags: [ 'role::logrotate', 'skip::logrotate' ]
      logrotate__dependent_config:
        - '{{ gitlab__logrotate__dependent_config }}'
    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ nginx__ferm__dependent_rules }}'
    - role: ruby
      tags: [ 'role::ruby', 'skip::ruby' ]
      ruby__dev_support: True
    - role: postgresql
      tags: [ 'role::postgresql', 'skip::postgresql' ]
      postgresql__dependent_roles:
        - '{{ gitlab__postgresql__dependent_roles }}'
      postgresql__dependent_groups:
        - '{{ gitlab__postgresql__dependent_groups }}'
      postgresql__dependent_databases:
        - '{{ gitlab__postgresql__dependent_databases }}'
      postgresql__dependent_extensions:
        - '{{ gitlab__postgresql__dependent_extensions }}'
      postgresql__dependent_pgpass:
        - '{{ gitlab__postgresql__dependent_pgpass }}'
      when: gitlab__database == 'postgresql'
    - role: ldap
      tags: [ 'role::ldap', 'skip::ldap' ]
      ldap__dependent_tasks:
        - '{{ gitlab__ldap__dependent_tasks }}'
    - role: nginx
      tags: [ 'role::nginx', 'skip::nginx' ]
      nginx__dependent_servers:
        - '{{ gitlab__nginx__dependent_servers }}'
      nginx__dependent_upstreams:
        - '{{ gitlab__nginx__dependent_upstreams }}'
    - role: gitlab
      tags: [ 'role::gitlab', 'skip::gitlab' ]
# Import the 'debops.docker_registry' playbook to apply configuration of the
# Docker Registry that is defined by the 'debops.gitlab' role. This has an
# effect only when the 'debops.docker_registry' role is enabled on the host via
# its corresponding Ansible inventory group.
- import_playbook: 'docker_registry.yml'

HOW TO USE REMOTE SQL DATABASE

  PostgreSQL

If you would like to use the remote PostgreSQL database, on the server side you need to allow remote connections from the GitLab host. This can be done using the Ansible inventory variables:

postgresql_server__listen_addresses: [ '*' ]
postgresql_server__allow: [ '192.0.2.0/24' ]

On the GitLab host, you need to enable the debops.postgresql role by adding the host to its respective Ansible inventory group:

[debops_service_postgresql]
hostname

The PostgreSQL client role also needs to be pointed to the remote database server, it can be done using the Ansible inventory variables:

postgresql__server: 'sqldb.example.org'

The debops.gitlab role should detect the PostgreSQL configuration automatically. If not, you can force the use of the PostgreSQL server through the Ansible inventory:

gitlab__database: 'postgresql'

  MariaDB/MySQL

MariaDB / MySQL databases are not supported anymore. GitLab's developers themselves discourage their use: https://docs.gitlab.com/ce/install/requirements.html#database.

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others