LGTM Enterprise 1.20.2

lgtm-cluster-config.yml file

Purpose

The cluster configuration file lists the machines used by LGTM and specifies which services are hosted on each. You use this file as input for the lgtm-config-gen.jar utility to generate service configuration files. You can then deploy those generated configurations on the machines that make up the cluster you specify in this file.

  • There is no set name or path for the cluster configuration file, but by convention it is state/lgtm-cluster-config.yml. The state directory is typically held under version control and checked out into the LGTM releases directory. A complete path might therefore be: /home/lgtmadminuser/lgtm-releases/state/lgtm-cluster-config.yml.

  • The cluster configuration file is not used directly by LGTM—it is a description of a configuration. The current configuration is stored internally by LGTM. You can generate a cluster configuration file that describes the current configuration by using the lgtm-config-gen.jar utility's ‑‑output flag.

Usage

For information about editing the file and deploying your changes, see Editing and deploying the cluster configuration.

For topics that involve making changes to the cluster configuration file, see Installing an SSL certificate, Managing the work pool, and Changing the LGTM URL.

File structure

The cluster configuration file follows basic YAML syntax and includes:

  • Two top-level properties (version at the start of the file and data_path at the end of the file) that apply to the whole configuration.
  • A series of blocks containing key: value pairs that specify where each LGTM service should run.

# Required. Specifies the cluster file format. Do not change.

version: <version>

 

# Required. Specifies the location of the main scheduling service and job dealer

coordinator:

  hostname: "<hostname>"

# Required. Specifies the location of the LGTM database

database:

  hostname: "<hostname>"

# Required. Specifies the location of the main file store

file_storage:

  hostname: "<hostname>"

# Required. Specifies the location of the message queue service

queue:

  hostname: "<hostname>"

# Optional. Specifies the location of the search service

search:

  hostname: "<hostname>"

# Required. Specifies the location and properties of machines in the web pool and

# specifies the URL at which users access LGTM

web:

  hosts:

  - hostname: "<hostname>"

  external_url: "<URL-for-LGTM-front-page>"

  ssl:

    certificate_path: "<path/for/certificate.crt>"

    key_path: "<path/for/key.key>"

# Required. Specifies the location and properties of machines in the work pool

workers:

  hosts:

  - hostname: "<hostname>"

    platform: <operating-system>

    general: <integer>

    query: <integer>

    on_demand: <integer>

  temp_path: "<path/for/worker/temp/files>"

 

# Required. Specifies the location for data storage on all control pool machines

data_path: "<path/for/control/pool/data/files>"

Environment variable expansion is not supported in the cluster configuration file.

Top-level properties

The version, and data_path properties are specified at the top level of the file because they apply to multiple services:

  • version—specifies which version of the file format is used. This is set and used by LGTM to upgrade the file to a new format, when necessary.

  • data_path—specifies the location for data storage on all control pool machines.

Blocks

Each block specifies the details for a service used by LGTM. For most services, this is just the location of the service (defined using the hostname property). For the services that support load-balancing, web and workers, you use the hosts property to define one or more hostname properties.

Block Properties Notes
coordinator hostname

Specifies the properties for the main scheduling service.

database hostname

Specifies the properties for the LGTM database.

file_storage hostname

Specifies the properties for the main file store.

queue hostname

Specifies the properties for the message queue service.

search hostname

Optional block. Specifies the properties for the search service.

web hosts
ssl

Specifies the composition and properties of the web pool. Optionally also specifies an SSL certificate and key for the web application.

workers hosts
temp_path

Specifies the composition and properties of the work pool. The hosts property must specify one or more hostname properties. Additional properties are also supported, see below for more information.

Properties

The properties supported by the cluster configuration file are:

Property Supported in Notes
hostname

coordinator
database
file_storage
queue
search
hosts

Specifies the name of the host machine for the enclosing service. The value must be quoted.

Exactly one value for this property must be specified for the following services: coordinator, database, file_storage, queue, and search.

The hosts property supports multiple values of this property.

hosts

web
workers

Specifies one or more hostname properties, each of which defines the location of one host machine.

ssl

web

Optional. Specifies an SSL certificate and key file for the web application to use. If included, the certificate_path and key_path must both be specified. For more information, see Installing an SSL certificate.

certificate_path

ssl

Required if ssl is included. Specifies the location of an SSL certificate for LGTM to use. The file should be stored on the coordinator server. Use an absolute path or define the location relative to the cluster configuration file.

key_path

ssl

Required if ssl is included. Specifies the location of an SSL key for LGTM to use. The file should be stored on the coordinator server. Use an absolute path or define the location relative to the cluster configuration file.

client_ca_path ssl

Optional. Specifies the path to a CA certificate PEM file. Setting this option means that all clients connecting to the LGTM web application must present a client certificate signed by the specified certificate authority. The file should be stored on the coordinator server. Use an absolute path or define the location relative to the cluster configuration file.

hsts

ssl

Optional. Specifies whether or not HTTP strict transport security (HSTS) headers are used. By default, this option is disabled. Set to true to enable HSTS headers.

We recommend that you only enable this option if you have processes in place to ensure that SSL certificates are always updated before they expire.

external_url

web

Required. Specifies the URL at which users access the LGTM web application. For information on editing this, see Changing the LGTM URL.

redirect_to_external_url

web

Optional. Set true if you want to automatically redirect requests made to the IP address, or to the non-qualified domain name, to the value of external_url.

general

hostname
(within workers)

Optional. Specifies the number of workers that perform general tasks. For more information, see Worker types.

query

hostname
(within workers)

Optional. Specifies the number of workers that are reserved to process only queries submitted by users in the query console. For more information, see Worker types.

on_demand

hostname
(within workers)

Optional. Specifies the number of workers that are reserved to process jobs where a user is likely to be waiting for results (excluding query jobs). For more information, see Worker types.

platform hostname
(within workers)

Required for all hosts running a Windows operating system. This is optional for Linux hosts.

Specifies the operating system of the host: windows or linux. The operating system is assumed to be Linux if this property is not specified.

labels

hostname
(within workers)

Optional. Specifies a list of one or more labels that are assigned to worker daemons running on this host.

Define each label as a separate list item, on a separate line, preceded by a hyphen and a space. Label text can contain lowercase letters, numbers, underscores, and hyphens, and cannot contain the automatically assigned labels unix and windows.

For more information, see Defining which workers can build and analyze a project.

environment

hostname
(within workers)

workers

Optional. Can be defined under:

  • the workers section, where it defines an environment variable for workers on all machines.
  • the hostname for a single worker machine, where it defines an environment variable for workers running on that machine. This may override a variable defined at the workers level.

For more information, see Setting environment variables for worker hosts and also Environment variables.

temp_path

hostname
(within workers)

workers

Optional. Can be defined under:

  • the workers section, where it defines the default temporary directory for all workers.
  • the hostname for a single worker machine, where it overrides the default temporary directory.

This directory is created if it doesn't already exist.

On Windows machines, backslashes in the path are escaped with an additional backslash: \\, see example below.

Example

The following lgtm-cluster-config.yml file creates a minimal deployment where the control pool and web pool run on the same machine, and the worker pool is split between the main "lgtm" server and two separate host machines. The web application is configured to use an SSL certificate that is trusted within the developer environment and by the Bitbucket server, ensuring that users can view LGTM securely and that Bitbucket code review integration is supported. Certificate-based client connections are also mandated, meaning that browsers requesting access to the web application must present a client certificate signed by a specified certificate authority.

This configuration runs eight workers: one query worker and seven general workers. The query worker runs queries entered in the query console. The general workers perform the build and analysis work on individual revisions of your projects.

The "windows-host" machine includes properties to specify the correct platform and an appropriate location for temporary files (slashes the path are escaped as \\).

The "linux-host" machine is assigned a highmemory label, to ensure that projects whose analysis requires a large amount of available memory are processed by workers on this machine, rather than on the "lgtm" server. Linux host machines don't require a platform property, because the operating system is assumed to be Linux by default.

version: 5

coordinator:

  hostname: "lgtm"

database:

  hostname: "lgtm"

file_storage:

  hostname: "lgtm"

queue:

  hostname: "lgtm"

search:

  hostname: "lgtm"

web:

  hosts:

  - hostname: "lgtm"

  external_url: "https://lgtm/"

  ssl:

    certificate_path: "/etc/ssl/server.crt"

    key_path: "/etc/ssl/server.key"

    client_ca_path: "client_ca.pem"

workers:

  hosts:

  - hostname: "lgtm"

    general: 1

    query: 1

  - hostname: "windows-host"

    general: 3

    platform: "windows"

    temp_path: "C:\\lgtm-workers-temp\\"

  - hostname: "linux-host"

    general: 3

    labels:

    - highmemory

  temp_path: "/var/cache/lgtm/workers/"

data_path: "/var/lib/lgtm/"

Related topicsRelated topics