Forge Home

Modules

Resources

PuppetEcosystemPuppet CommunityUpdates

simp_gitlab

SIMP profiles for GitLab
Project URLRSS FeedReport issues

10,934 downloads

92 latest version

4.3 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.12.0 (latest)
  • 0.10.0
  • 0.8.1
  • 0.8.0
  • 0.7.1
  • 0.7.0
  • 0.6.1
  • 0.6.0
  • 0.5.1
  • 0.5.0
  • 0.4.0
  • 0.3.4
  • 0.3.3
  • 0.3.2
  • 0.3.1
  • 0.3.0
released Mar 28th 2018
This version is compatible with:
  • Puppet Enterprise 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >= 4.6.0 < 5.0.0
  • ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'simp-simp_gitlab', '0.3.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add simp-simp_gitlab
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install simp-simp_gitlab --version 0.3.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: ci, gitlab, simp, gitlab-ce, gitlab-omnibus

Documentation

simp/simp_gitlab — version 0.3.0 Mar 28th 2018

License Build Status SIMP compatibility

Table of Contents

Description

This module provides profiles for integrating GitLab Omnibus with SIMP.

This is a SIMP module

This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.

It is designed to be used within a larger SIMP ecosystem, but it can be used independently:

  • When included within the SIMP ecosystem, security compliance settings will be managed from the Puppet server.
  • If used as an independent module, all SIMP-managed security subsystems are disabled by default and must be explicitly opted into by administrators. Please review the parameters in simp/simp_options for details.

If you run into problems, please let us know by filing an issue at https://simp-project.atlassian.net/.

Setup

What simp_gitlab affects

This module is a profile that integrates Gitlab with SIMP. It makes extensive use of the component module vshn/gitlab. It is important to note that vshn-gitlab configures the GitLab Omnibus's /etc/gitlab/gitlab.rb and runs gitlab-ctl reconfigure.

Relationships between components

As a profile module, simp_gitlab has a few functions:

  • Integrate SIMP and SIMP's global catalysts with GitLab Omnibus
    • Supported SIMP Options (global catalysts):
      • simp_options::trusted_nets
      • simp_options::firewall
      • simp_options::pki
      • simp_options::ldap::*
    • Intentionally unimplemented:
      • simp_options::selinux ― The GitLab Omnibus installer appears to handle SELinux correctly
      • simp_options::tcpwrappers ― nothing in Omnibus is linked to TCP Wrapper
      • simp_options::auditing ― nothing in Omnibus needs special auditd logic
    • Deferred:
      • simp_options::fips ― GitLab Omnibus ships with a version of OpenSSL that does not support FIPS mode
      • simp_options::syslog (not clear that we want to support this outside of ee)
    • SIMP integrations:
      • Open access for a local git SSH user
        • set up a SIMP pam::access::rule to permit GitLab's local git user
        • configures sshd such that the GitLab's local git user's SSH authorized keys file path is managed only by the GitLab Omnibus installer.
      • The postfix service that comes with GitLab Omnibus is disabled in favor of the SIMP postfix module.
  • Ensure that GitLab Omnibus can be installed without internet access
    • This requires a local mirror of the Gitlab repositories
  • Simplify GitLab configuration for common scenarios
    • GitLab
    • GitLab + Omnibus version of NGINX
    • Mattermost
    • GitLab CI runner
    • Intentionally unimplemented:
      • Prometheus
      • GitLab CI Runner (docker)
  • Permit customization of GitLab Omnibus
  • Satisfy as many compliance-relevant criteria as possible

FIXME: Ensure the What simp_gitlab affects section is correct and complete, then remove this message!

mention:

  • A list of files, packages, services, or operations that the module will alter, impact, or execute.
  • Dependencies that your module automatically installs.
  • Warnings or other important notices.

Setup Requirements

If using this module from an isolated network, ensure that package and repo management are disabled from the module, and that the gitlab-ce or gitlab-ee package is installed. Be sure that the $::simp_gitlab::edition parameter is set to the correct edition.

Beginning with simp_gitlab

The most basic GitLab usage within a SIMP-managed infrastructure where all simp_options:: are present:

include 'simp_gitlab'

Usage

A basic GitLab setup using PKI

class { 'simp_gitlab':
  trusted_nets => [
                    '10.0.0.0/8',
                    '192.168.21.21',
                    '192.168.21.22',
                    '127.0.0.1/32',
                  ],
  pki          => 'simp',
  firewall     => true,
}

Passing custom parameters to vshn-gitlab

Parameters for vshn/gitlab can be passed in directly using the (Hash) $simp_gitlab::gitlab_options parameter.

Warning: $simp_gitlab::gitlab_options parameters that conflict with the rest of simp_gitlab may lead to undefined behavior / broken systems.

Hint: Many of the data structures used by vshn/gitlab's parameters are documented at https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template


# Name the local git user account `gitlab` (instead of the default `git`)
class { 'simp_gitlab':
  trusted_nets   => $simp_options::trusted_nets
  pki            => 'simp',
  firewall       => true,
  gitlab_options => {
    'user' => {
      'username' => 'gitlab',
      'group'    => 'gitlab',
    }
  },
}

Configuring Nginx

simp_gitlab configures the GitLab's internal Nginx server to look for additional .conf files under /etc/gitlab/nginx/conf.d/.

If you need to configure the main Nginx server, use a file resource from your own profiles to establish a new .conf file.

Reference

Please refer to the inline documentation within each source file, or to the module's generated YARD documentation for reference material.

Further Reference for munging GitLab Omnibus

Limitations

Gitlab's LDAP TLS is configured to re-use Omnibus' trusted-certs/ instead of ca_file

simp_gitlab configures the GitLab Rails server LDAP TLS settings to use the Omnibus trusted_certs (built from /etc/gitlab/trusted-certs) instead of its own ca_file option.

The LDAP ca_file setting is known to cause problems elsewhere in GitLab SSL. There is a (currently undocumented) workaround to these issues: GitLab's LDAP TLS will re-use the GitLab Omnibus trusted-certificates/ directory―but only when the LDAP ca_file option has not been set

The drawback to this solution is that GitLab's LDAP client must share the same TLS settings as GitLab's web server―which is something that we try to keep distinct, as there could be situations in which their configurations legitimately vary.

GitLab

Puppet runs can fail if GitLab Omnibus's internal services don't start in time

Note: These are limitations of upstream components

  • The Exec that runs gitlab-ctl reconfigure may take a long time start its internal services, particularly during the first run that installs GitLab. These services are internal to the GitLab Omnibus installation and are not registered with the host OS or the Puppet providers for service. It is possible for the services to take so long to start in the background that dependencies within vshn-gitlab will fail.

    In these cases, it should be sufficient to simply run Puppet again after the services finish starting (status with gitlab-ctl status).

  • If the GitLab Omnibus package is already installed but the gitlab-runsvdir service is stopped, the service will not start and catalog compilation will fail.

Nessus scans may incorrectly report CRIME vulnerability in GitLab

This is almost certainly a false positive―GitLab configures compression to 0 when HTTPS is enabled.

Redis log warnings

Right now, redis logs these warnings (running in beaker/vagrant VMs):

# WARNING overcommit_memory is set to 0! Background save may fail under low
memory condition. To fix this issue add 'vm.overcommit_memory = 1' to
/etc/sysctl.conf and then reboot or run the command 'sysctl
vm.overcommit_memory=1' for this to take effect.

# WARNING you have Transparent Huge Pages (THP) support enabled in your kernel.
This will create latency and memory usage issues with Redis. To fix this issue
run the command 'echo never > /sys/kernel/mm/transparent_hugepage/enabled' as
root, and add it to your /etc/rc.local in order to retain the setting after
a reboot. Redis must be restarted after THP is disabled.

Development

Please read our Contribution Guide.

Acceptance tests

This module includes Beaker acceptance tests using the SIMP Beaker Helpers. By default the tests use Vagrant with VirtualBox as a back-end; Vagrant and VirtualBox must both be installed to run these tests without modification. To execute the tests run the following:

bundle install
bundle exec rake beaker:suites

Please refer to the SIMP Beaker Helpers documentation for more information.

Environment variable TEST_GITLAB_CE_VERSION

TEST_GITLAB_CE_VERSION is an environment variable that can be used to specify the version of gitlab-ce to use in the acceptance tests. When set, it must either a version string for a specific gitlab-ce package version or 'latest' to indicate the latest available version.

TEST_GITLAB_CE_VERSION=latest bundle exec rake beaker:suites

Environment variable TRUSTED_NETS

TRUSTED_NETS is an environment variable that may contain a comma-delimited list of trusted networks to add to the gitlab SUT's firewall.

TRUSTED_NETS=192.168.11.0/24,10.0.2.2 bundle exec rake beaker:suites

Note: if the TRUSTED_NETS configuration is too broad, it may cause some acceptance tests (for denied clients) to fail.

Manually inspecting the SUT GitLab server with a web browser

Each nodeset in spec/acceptance/nodesets/ contains a commented-out forwarded_ports: section. If you want to use a web browser to manually inspect the SUT GitLab server during any of the tests, uncomment this section and add the NAT network router's IP address to the TRUSTED_NETS variable.

For example:

TRUSTED_NETS=10.0.2.2 BEAKER_destroy=no bundle exec rake beaker:suites

Then, in a browser on the host machine, navigate to https://127.0.0.1:<port>, where <port> is the forwarded port for the test being executed, i.e., 8080, 8443, or 8777.

Note: If you need to login as the administrator to the GitLab instance, use the login of root and the password found on the GitLab server host at /opt/puppetlabs/puppet/cache/simp/environments/production/simp_autofiles/gen_passwd/simp_gitlab_server.<your domain>.

Interactive debugging using pry

Setting the environment variable PRY=yes will cause the acceptance tests to drop into a pry console under certain circumstances (usually just before failures in examples with complex or hard-to-debug state). This will effectively pause the test, to allow you to debug.

TRUSTED_NETS=10.0.2.2 BEAKER_destroy=no PRY=yes bundle exec rake beaker:suites