DEBOPS.GITLAB(5)

NAME
debops.gitlab - Install and manage GitLab Omnibus

SYNOPSIS

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

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

DESCRIPTION

GitLab <https://about.gitlab.com/> is a complete suite of tools and services needed for application development, testing and deployment, including a software forge based on git, issue tracking, Continuous Integration and support for Kubernetes and other popular services. GitLab is developed using an "open core" model, with essential parts of the project licensed under Open Source licenses and ability to upgrade the service with commercial licenses.

The project can be deployed in several different ways, one of which is an "omnibus" installation which consists of all of the needed services (web server, database, various other tools) bundled together in a package and managed as a whole using Chef. The debops.gitlab Ansible role provides an integration layer between various services managed by DebOps (firewall, PKI infrastructure, LDAP environment) and GitLab Omnibus, and allows the system administrator to deploy and manage GitLab Omnibus using Ansible.

GETTING STARTED

  Default configuration

The debops.gitlab role supports installation of GitLab Omnibus Community Edition as well as the Enterprise Edition, which can be selected using the gitlab__edition variable. Manual installation of the GitLab Omnibus package is also supported, in which case the role can be used to configure such installation and provide integration with the rest of the environment.

By default, the installation will be configured to publish GitLab on the code.{{ gitlab__domain }} DNS domain, to aid configuration of GitLab Runner instances. This can be changed by overriding the gitlab__fqdn variable via the Ansible inventory.

The initial root password is randomly generated and stored in the ansible/secret/gitlab/credentials/ directory on the Ansible Controller, managed by the debops.secret Ansible role.

GitLab Omnibus deployed by DebOps will be configured with GitLab Container Registry available by default on a separate TCP port. This ensures that only one DNS domain and X.509 certificate is needed by default. Container Registry can be deployed on a separate DNS domain if needed.

The role integrates GitLab Omnibus with the ferm service through the debops.ferm Ansible role. By default, the main GitLab service and Container Registry are accessible to any hosts and networks once deployed, this can be configured using role variables.

PKI environment managed by the debops.pki role is also integrated with GitLab Omnibus, via the use of symlinks in /etc/gitlab/ssl/ directory that provide access to private keys and X.509 certificates in the /etc/pki/realms/ directories.

If the LDAP environment managed by the debops.ldap Ansible role is detected, a suitable user account for GitLab instance will be created by default. GitLab will be configured with a single LDAP server in that case.

Daily backups of GitLab Omnibus environment will be enabled by default using the cron service.

  Example inventory

To install GitLab Omnibus service on a host, it needs to be included in the [debops_service_gitlab] Ansible inventory group.

Example Ansible inventory:

[debops_all_hosts]
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 Omnibus 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({})) }}'
  roles:
    - role: keyring
      tags: [ 'role::keyring', 'skip::keyring' ]
      keyring__dependent_apt_keys:
        - '{{ gitlab__keyring__dependent_apt_keys }}'
    - role: extrepo
      tags: [ 'role::extrepo', 'skip::extrepo' ]
      extrepo__dependent_sources:
        - '{{ gitlab__extrepo__dependent_sources }}'
    - role: etc_services
      tags: [ 'role::etc_services', 'skip::etc_services' ]
      etc_services__dependent_list:
        - '{{ gitlab__etc_services__dependent_list }}'
    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ gitlab__ferm__dependent_rules }}'
    - role: python
      tags: [ 'role::python', 'skip::python', 'role::ldap' ]
      python__dependent_packages3:
        - '{{ ldap__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ ldap__python__dependent_packages2 }}'
    - role: ldap
      tags: [ 'role::ldap', 'skip::ldap' ]
      ldap__dependent_tasks:
        - '{{ gitlab__ldap__dependent_tasks }}'
    - role: gitlab
      tags: [ 'role::gitlab', 'skip::gitlab' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::gitlab
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

  Other resources

List of other useful resources related to the debops.gitlab Ansible role:

•   Official documentation of GitLab Omnibus <https://docs.gitlab.com/omnibus/>

•   GitLab package repository <https://packages.gitlab.com/gitlab/gitlab-ce/> which contains APT packages for older releases, not accessible through the official APT configuration

DEFAULT VARIABLE DETAILS

Some of debops.gitlab default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  gitlab__ssl_symlinks

GitLab Omnibus uses private keys and X.509 certificates provided in the /etc/gitlab/ssl/ directory to configure encrypted connection support inside of its environment. The gitlab__ssl_*_symlinks variables can be used to create symlinks to the private keys and certificates stored elsewhere in the filesystem; this is used to integrate GitLab Omnibus with the PKI infrastructure managed by the debops.pki Ansible role.

  Examples

You can see the default set of private key and X.509 certificate symlinks defined in the gitlab__ssl_default_symlinks variable.

  Syntax

The variables are defined as a list of YAML dictionaries, with specific parameters:

link
    Required. Name of the symlink in the /etc/gitlab/ssl/ directory which will point to a specific resource. GitLab Omnibus expects the *.key and *.crt files respectively, with names based on the DNS names used for different resources, for example the service addresses.

src Required. Absolute path to a file which will be symlinked to in the /etc/gitlab/ssl/ directory.

state
    Optional. If not specified or link, a given symlink will be created or updated if necessary. If absent, a given symlink will be removed.

  gitlab__configuration

The gitlab__*_configuration variables define the contents of the /etc/gitlab/gitlab.rb configuration file, used to configure GitLab Omnibus installation. You can find an example configuration file with complete contents in the /opt/gitlab/etc/gitlab.rb.template file, which might be useful as a reference. You can also use online GitLab Omnibus documentation <https://docs.gitlab.com/omnibus/settings/> to find more details about configuring GitLab Omnibus.

The role uses Universal Configuration system to integrate the default and inventory variables during configuration file generation.

  Examples

You can see the default configuration defined in the role in gitlab__default_configuration variable to see examples of various configuration options.

  Syntax

The variables are defined as lists of YAML dictionaries, each entry can configure either a simple variable, a list or a "section" of configuration options. Entries are defined using specific parameters:

name
    Required. Name of the variable to define in the configuration file, or a configuration section (for example gitlab_rails) if the options parameter is also included. Configuration entries with the same name parameter are merged together and can affect each other.

title
    Optional. String or YAML text block with a short "title" comment which describes a given option.

comment
    Optional. String or YAML text block with a longer "description" comment.

value
    The value of a given configuration option. It can be a string, a number, a boolean variable or a YAML list (usually with strings).

raw If the raw parameter is specified, the name and value parameters are not included in the generated configuration file. The contents of the raw parameter (string or YAML text block) will be included in the generated configuration file as-is. You can use Jinja inside of the raw parameter to augment generated configuration as needed. This is useful with more complex configuration options such as dictionaries or Ruby code.

state
    Optional. If not specified or present, a given configuration option will be included in the generated file. If absent, a given configuration option will not be included in the finished file. If comment, the option will be included but commented out. If ignore, a given configuration entry will not be evaluated during role execution.

separator
    Optional. Add an empty line before a given configuration option, for aesthetic purposes.

options
    Optional. A list of configuration options which belong to a given "section" (in Ruby terms, keys and values of a given dictionary). Each element of the list is a YAML dictionary with the same paraneters as the main configuration; the name parameter specifies the dictionary key and value or raw parameters can be used to define it.

AUTHOR
Maciej Delmanowski

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