Skip to content

G
gitlab-ce
Commit ae14c73f authored by Craig Norris's avatar Craig Norris
Browse files
Options

Merge branch '354845-aqualls-config-page' into 'master' 

Revise Workhorse config page for tone and style

See merge request gitlab-org/gitlab!84771
parents 72fe60a0 2252f313
Hide whitespace changes
Inline Side-by-side
Showing with 64 additions and 65 deletions
doc/development/workhorse/configuration.md
View file @ ae14c73f
...@@ -6,9 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w ...@@ -6,9 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Workhorse configuration # Workhorse configuration
For historical reasons Workhorse uses both command line flags, a configuration file and environment variables. For historical reasons, Workhorse uses:
All new configuration options that get added to Workhorse should go into the configuration file. - Command line flags.
- A configuration file.
- Environment variables.
Add any new Workhorse configuration options into the configuration file.
## CLI options ## CLI options
...@@ -61,35 +65,32 @@ Options: ...@@ -61,35 +65,32 @@ Options:
``` ```
The 'auth backend' refers to the GitLab Rails application. The name is The 'auth backend' refers to the GitLab Rails application. The name is
a holdover from when GitLab Workhorse only handled Git push/pull over a holdover from when GitLab Workhorse only handled `git push` and `git pull` over
HTTP. HTTP.
GitLab Workhorse can listen on either a TCP or a Unix domain socket. It GitLab Workhorse can listen on either a TCP or a Unix domain socket. It
can also open a second listening TCP listening socket with the Go can also open a second listening TCP listening socket with the Go
[`net/http/pprof` profiler server](http://golang.org/pkg/net/http/pprof/). [`net/http/pprof` profiler server](http://golang.org/pkg/net/http/pprof/).
GitLab Workhorse can listen on Redis events (currently only builds/register GitLab Workhorse can listen on Redis build and runner registration events if you
for runners). This requires you to pass a valid TOML configuration file via pass a valid TOML configuration file through the `-config` flag.
`-config` flag. A regular setup it only requires the following (replacing the string
For regular setups it only requires the following (replacing the string
with the actual socket) with the actual socket)
## Redis ## Redis
GitLab Workhorse integrates with Redis to do long polling for CI build GitLab Workhorse integrates with Redis to do long polling for CI build
requests. This is configured via two things: requests. To configure it:
- Redis settings in the TOML configuration file - Configure Redis settings in the TOML configuration file.
- The `-apiCiLongPollingDuration` command line flag to control polling - Control polling behavior for CI build requests with the `-apiCiLongPollingDuration`
behavior for CI build requests command-line flag.
It is OK to enable Redis in the configuration file but to leave CI polling You can enable Redis in the configuration file while leaving CI polling
disabled; this just results in an idle Redis pubsub connection. The disabled. This configuration results in an idle Redis Pub/Sub connection. The
opposite is not possible: CI long polling requires a correct Redis opposite is not possible: CI long polling requires a correct Redis configuration.
configuration.
Below we discuss the options for the `[redis]` section in the configuration For example, the `[redis]` section in the configuration file could contain:
file.
```plaintext ```plaintext
[redis] [redis]
...@@ -99,15 +100,13 @@ Sentinel = [ "tcp://sentinel1:23456", "tcp://sentinel2:23456" ] ...@@ -99,15 +100,13 @@ Sentinel = [ "tcp://sentinel1:23456", "tcp://sentinel2:23456" ]
SentinelMaster = "mymaster" SentinelMaster = "mymaster"
``` ```
- `URL` takes a string in the format `unix://path/to/redis.sock` or - `URL` - A string in the format `unix://path/to/redis.sock` or `tcp://host:port`.
`tcp://host:port`. - `Password` - Required only if your Redis instance is password-protected.
- `Password` is only required if your Redis instance is password-protected - `Sentinel` - Required if you use Sentinel.
- `Sentinel` is used if you are using Sentinel.
NOTE: If both `Sentinel` and `URL` are given, only `Sentinel` is used.
If both `Sentinel` and `URL` are given, only `Sentinel` will be used.
Optional fields are as follows: Optional fields:
```plaintext ```plaintext
[redis] [redis]
...@@ -116,15 +115,14 @@ MaxIdle = 1 ...@@ -116,15 +115,14 @@ MaxIdle = 1
MaxActive = 1 MaxActive = 1
``` ```
- `DB` is the Database to connect to. Defaults to `0` - `DB` - The database to connect to. Defaults to `0`.
- `MaxIdle` is how many idle connections can be in the Redis pool at once. Defaults to 1 - `MaxIdle` - How many idle connections can be in the Redis pool at once. Defaults to `1`.
- `MaxActive` is how many connections the pool can keep. Defaults to 1 - `MaxActive` - How many connections the pool can keep. Defaults to `1`.
## Relative URL support ## Relative URL support
If you are mounting GitLab at a relative URL, e.g. If you mount GitLab at a relative URL, like `example.com/gitlab`), use this
`example.com/gitlab`, then you should also use this relative URL in relative URL in the `authBackend` setting:
the `authBackend` setting:
```plaintext ```plaintext
gitlab-workhorse -authBackend http://localhost:8080/gitlab gitlab-workhorse -authBackend http://localhost:8080/gitlab
...@@ -132,33 +130,32 @@ gitlab-workhorse -authBackend http://localhost:8080/gitlab ...@@ -132,33 +130,32 @@ gitlab-workhorse -authBackend http://localhost:8080/gitlab
## Interaction of authBackend and authSocket ## Interaction of authBackend and authSocket
The interaction between `authBackend` and `authSocket` can be a bit The interaction between `authBackend` and `authSocket` can be confusing.
confusing. It comes down to: if `authSocket` is set it overrides the If `authSocket` is set, it overrides the host portion of `authBackend`, but not
_host_ part of `authBackend` but not the relative path. the relative path.
In table form: In table form:
|authBackend|authSocket|Workhorse connects to?|Rails relative URL| | authBackend | authSocket | Workhorse connects to | Rails relative URL |
|---|---|---|---| |--------------------------------|-------------------|-----------------------|--------------------|
|unset|unset|`localhost:8080`|`/`| | unset | unset | `localhost:8080` | `/` |
|`http://localhost:3000`|unset|`localhost:3000`|`/`| | `http://localhost:3000` | unset | `localhost:3000` | `/` |
|`http://localhost:3000/gitlab`|unset|`localhost:3000`|`/gitlab`| | `http://localhost:3000/gitlab` | unset | `localhost:3000` | `/gitlab` |
|unset|`/path/to/socket`|`/path/to/socket`|`/`| | unset | `/path/to/socket` | `/path/to/socket` | `/` |
|`http://localhost:3000`|`/path/to/socket`|`/path/to/socket`|`/`| | `http://localhost:3000` | `/path/to/socket` | `/path/to/socket` | `/` |
|`http://localhost:3000/gitlab`|`/path/to/socket`|`/path/to/socket`|`/gitlab`| | `http://localhost:3000/gitlab` | `/path/to/socket` | `/path/to/socket` | `/gitlab` |
The same applies to `cableBackend` and `cableSocket`. The same applies to `cableBackend` and `cableSocket`.
## Error tracking ## Error tracking
GitLab-Workhorse supports remote error tracking with GitLab-Workhorse supports remote error tracking with [Sentry](https://sentry.io).
[Sentry](https://sentry.io). To enable this feature set the To enable this feature, set the `GITLAB_WORKHORSE_SENTRY_DSN` environment variable.
`GITLAB_WORKHORSE_SENTRY_DSN` environment variable.
You can also set the `GITLAB_WORKHORSE_SENTRY_ENVIRONMENT` environment variable to You can also set the `GITLAB_WORKHORSE_SENTRY_ENVIRONMENT` environment variable to
use the Sentry environment functionality to separate staging, production and use the Sentry environment feature to separate staging, production and
development. development.
Omnibus (`/etc/gitlab/gitlab.rb`): Omnibus GitLab (`/etc/gitlab/gitlab.rb`):
```ruby ```ruby
gitlab_workhorse['env'] = { gitlab_workhorse['env'] = {
...@@ -174,46 +171,48 @@ export GITLAB_WORKHORSE_SENTRY_DSN='https://foobar' ...@@ -174,46 +171,48 @@ export GITLAB_WORKHORSE_SENTRY_DSN='https://foobar'
export GITLAB_WORKHORSE_SENTRY_ENVIRONMENT='production' export GITLAB_WORKHORSE_SENTRY_ENVIRONMENT='production'
``` ```
## Distributed Tracing ## Distributed tracing
Workhorse supports distributed tracing through [LabKit](https://gitlab.com/gitlab-org/labkit/) using [OpenTracing APIs](https://opentracing.io). Workhorse supports distributed tracing through [LabKit](https://gitlab.com/gitlab-org/labkit/)
using [OpenTracing APIs](https://opentracing.io).
By default, no tracing implementation is linked into the binary, but different OpenTracing providers can be linked in using [build tags](https://golang.org/pkg/go/build/#hdr-Build_Constraints) or build constraints. This can be done by setting the `BUILD_TAGS` make variable. By default, no tracing implementation is linked into the binary. You can link in
different OpenTracing providers with [build tags](https://golang.org/pkg/go/build/#hdr-Build_Constraints)
or build constraints by setting the `BUILD_TAGS` make variable.
For more details of the supported providers, see LabKit, but as an example, for Jaeger tracing support, include the tags: `BUILD_TAGS="tracer_static tracer_static_jaeger"`. For more details of the supported providers, refer to LabKit. For an example of
Jaeger tracing support, include the tags: `BUILD_TAGS="tracer_static tracer_static_jaeger"` like this:
```shell ```shell
make BUILD_TAGS="tracer_static tracer_static_jaeger" make BUILD_TAGS="tracer_static tracer_static_jaeger"
``` ```
Once Workhorse is compiled with an opentracing provider, the tracing configuration is configured via the `GITLAB_TRACING` environment variable. After you compile Workhorse with an OpenTracing provider, configure the tracing
configuration with the `GITLAB_TRACING` environment variable, like this:
For example:
```shell ```shell
GITLAB_TRACING=opentracing://jaeger ./gitlab-workhorse GITLAB_TRACING=opentracing://jaeger ./gitlab-workhorse
``` ```
## Continuous Profiling ## Continuous profiling
Workhorse supports continuous profiling through [LabKit](https://gitlab.com/gitlab-org/labkit/) using [Stackdriver Profiler](https://cloud.google.com/profiler).
By default, the Stackdriver Profiler implementation is linked in the binary using [build tags](https://golang.org/pkg/go/build/#hdr-Build_Constraints), though it's not Workhorse supports continuous profiling through [LabKit](https://gitlab.com/gitlab-org/labkit/)
required and can be skipped. using [Stackdriver Profiler](https://cloud.google.com/profiler). By default, the
Stackdriver Profiler implementation is linked in the binary using
For example: [build tags](https://golang.org/pkg/go/build/#hdr-Build_Constraints), though it's not
required and can be skipped. For example:
```shell ```shell
make BUILD_TAGS="" make BUILD_TAGS=""
``` ```
Once Workhorse is compiled with Continuous Profiling, the profiler configuration can be set via `GITLAB_CONTINUOUS_PROFILING` After you compile Workhorse with continuous profiling, set the profiler configuration
environment variable. with the `GITLAB_CONTINUOUS_PROFILING` environment variable. For example:
For example:
```shell ```shell
GITLAB_CONTINUOUS_PROFILING="stackdriver?service=workhorse&service_version=1.0.1&project_id=test-123 ./gitlab-workhorse" GITLAB_CONTINUOUS_PROFILING="stackdriver?service=workhorse&service_version=1.0.1&project_id=test-123 ./gitlab-workhorse"
``` ```
More information about see the [LabKit monitoring documentation](https://gitlab.com/gitlab-org/labkit/-/blob/master/monitoring/doc.go). ## Related topics
- [LabKit monitoring documentation](https://gitlab.com/gitlab-org/labkit/-/blob/master/monitoring/doc.go).
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7