역사적인 이유로 Workhorse는 다음을 사용합니다:

• 커맨드라인 플래그.

• 구성 파일.

• 환경 변수.

새로운 Workhorse 구성 옵션은 구성 파일에 추가하세요.

CLI 옵션#

  gitlab-workhorse [OPTIONS]

Options:
  -apiCiLongPollingDuration duration
        Long polling duration for job requesting for runners (default 50ns)
  -apiLimit uint
        Number of API requests allowed at single time
  -apiQueueDuration duration
        Maximum queueing duration of requests (default 30s)
  -apiQueueLimit uint
        Number of API requests allowed to be queued
  -authBackend string
        Authentication/authorization backend (default "http://localhost:8080")
  -authSocket string
        Optional: Unix domain socket to dial authBackend at
  -cableBackend string
        ActionCable backend
  -cableSocket string
        Optional: Unix domain socket to dial cableBackend at
  -config string
        TOML file to load config from
  -developmentMode
        Allow the assets to be served from Rails app
  -documentRoot string
        Path to static files content (default "public")
  -listenAddr string
        Listen address for HTTP server (default "localhost:8181")
  -listenNetwork string
        Listen 'network' (tcp, tcp4, tcp6, unix) (default "tcp")
  -listenUmask int
        Umask for Unix socket
  -logFile string
        Log file location
  -logFormat string
        Log format to use defaults to text (text, json, structured, none) (default "text")
  -pprofListenAddr string
        pprof listening address, for example, 'localhost:6060'
  -prometheusListenAddr string
        Prometheus listening address, for example, 'localhost:9229'
  -propagateCorrelationID X-Request-ID
        Reuse existing Correlation-ID from the incoming request header X-Request-ID if present
  -proxyHeadersTimeout duration
        How long to wait for response headers when proxying the request (default 5m0s)
  -secretPath string
        File with secret key to authenticate with authBackend (default "./.gitlab_workhorse_secret")
  -version
        Print version and exit

'auth backend'는 GitLab Rails 애플리케이션을 의미합니다. 이 이름은 GitLab Workhorse가 HTTP를 통한 git push 및 git pull만 처리했던 시절부터 남아 있는 명칭입니다.

GitLab Workhorse는 TCP 또는 Unix 도메인 소켓 중 하나에서 수신 대기할 수 있습니다. 또한 Go net/http/pprof 프로파일러 서버를 사용하여 두 번째 TCP 수신 소켓을 열 수도 있습니다.

GitLab Workhorse는 -config 플래그를 통해 유효한 TOML 구성 파일을 전달하면 Redis 빌드 및 러너 등록 이벤트를 수신할 수 있습니다. 일반적인 설정에서는 다음 내용만 필요합니다 (문자열은 실제 소켓으로 대체).

Redis#

GitLab Workhorse는 CI 빌드 요청에 대한 롱 폴링(long polling)을 수행하기 위해 Redis와 연동합니다. 구성 방법:

• TOML 구성 파일에서 Redis 설정을 구성합니다.

• -apiCiLongPollingDuration 커맨드라인 플래그로 CI 빌드 요청에 대한 폴링 동작을 제어합니다.

구성 파일에서 Redis를 활성화하면서 CI 폴링은 비활성화할 수 있습니다. 이 구성은 유휴 Redis Pub/Sub 연결을 생성합니다. 반대의 경우는 불가능합니다. CI 롱 폴링에는 올바른 Redis 구성이 필요합니다.

예를 들어 구성 파일의 [redis] 섹션은 다음과 같을 수 있습니다:

[redis]
URL = "unix:///var/run/gitlab/redis.sock"
Password = "my_awesome_password"

• URL - unix://path/to/redis.sock 또는 redis://host:port 형식의 문자열.

• Password - Redis 인스턴스가 비밀번호로 보호된 경우에만 필요합니다.

• Sentinel - Sentinel을 사용하는 경우에 필요합니다.

Sentinel과 URL이 모두 지정된 경우 Sentinel만 사용됩니다.

선택적 필드:

[redis]
DB = 0
MaxIdle = 1
MaxActive = 1

• DB - 연결할 데이터베이스. 기본값은 0입니다.

• MaxIdle - Redis 풀에 한 번에 유지할 수 있는 유휴 연결 수. 기본값은 1입니다.

• MaxActive - 풀이 유지할 수 있는 연결 수. 기본값은 1입니다.

상대 URL 지원#

example.com/gitlab과 같이 상대 URL에 GitLab을 마운트하는 경우, authBackend 설정에서 이 상대 URL을 사용하세요:

gitlab-workhorse -authBackend http://localhost:8080/gitlab

TLS 지원#

수신 요청에 사용할 TLS 리스너를 구성할 수 있습니다. 서버의 인증서와 이에 대응하는 개인 키를 포함하는 파일 경로를 제공해야 합니다:

[[listeners]]
network = "tcp"
addr = "localhost:3443"
[listeners.tls]
  certificate = "/path/to/certificate"
  key = "/path/to/private/key"
  min_version = "tls1.2"
  max_version = "tls1.3"

certificate 파일에는 서버의 인증서, 중간 인증서, 그리고 인증 기관의 인증서를 이어 붙인 내용이 포함되어야 합니다.

메트릭 엔드포인트도 유사하게 구성할 수 있습니다:

[metrics_listener]
network = "tcp"
addr = "localhost:9229"
[metrics_listener.tls]
  certificate = "/path/to/certificate"
  key = "/path/to/private/key"
  min_version = "tls1.2"
  max_version = "tls1.3"

Sentinel 지원#

[redis]
Sentinel = [ "redis://sentinel1:23456", "redis://sentinel2:23456" ]
SentinelMaster = "mymaster"

Sentinel TLS 지원#

[redis]
Sentinel = [ "rediss://sentinel1:23456", "rediss://sentinel2:23456" ]
SentinelMaster = "mymaster"
[Sentinel.tls]
  certificate = "/path/to/certificate"       # optional
  key = "/path/to/private/key"               # optional
  ca_certificate = "/path/to/ca_certificate" # optional
  min_version = "tls1.2"                     # optional
  max_version = "tls1.3"                     # optional

authBackend와 authSocket의 상호작용#

authBackend와 authSocket 간의 상호작용은 혼란스러울 수 있습니다. authSocket이 설정된 경우 authBackend의 호스트 부분은 재정의되지만 상대 경로는 그대로 유지됩니다.

표 형식으로 정리하면:

동일한 규칙이 cableBackend와 cableSocket에도 적용됩니다.

메타데이터 옵션#

[metadata] 섹션에 다음 옵션을 포함하세요:

예를 들어:

[metadata]
zip_reader_limit_bytes = 209715200 # 200 MB

오류 추적#

GitLab-Workhorse는 Sentry를 이용한 원격 오류 추적을 지원합니다. 이 기능을 활성화하려면 GITLAB_WORKHORSE_SENTRY_DSN 환경 변수를 설정하세요. 또한 GITLAB_WORKHORSE_SENTRY_ENVIRONMENT 환경 변수를 설정하여 Sentry의 환경 기능을 사용해 스테이징, 프로덕션, 개발 환경을 분리할 수 있습니다.

Linux package (Omnibus)

gitlab_workhorse['env'] = {
    'GITLAB_WORKHORSE_SENTRY_DSN' => 'https://foobar'
    'GITLAB_WORKHORSE_SENTRY_ENVIRONMENT' => 'production'
}

Self-compiled (source)

export GITLAB_WORKHORSE_SENTRY_DSN='https://foobar'
export GITLAB_WORKHORSE_SENTRY_ENVIRONMENT='production'

분산 추적#

Workhorse는 OpenTracing API를 사용하는 LabKit을 통해 분산 추적을 지원합니다.

기본적으로 바이너리에는 추적 구현이 링크되어 있지 않습니다. BUILD_TAGS make 변수를 설정하여 빌드 태그 또는 빌드 제약 조건으로 다양한 OpenTracing 공급자를 링크할 수 있습니다.

지원되는 공급자에 대한 자세한 내용은 LabKit을 참조하세요. Jaeger 추적 지원 예시로, 다음과 같이 태그를 포함할 수 있습니다: BUILD_TAGS="tracer_static tracer_static_jaeger":

make BUILD_TAGS="tracer_static tracer_static_jaeger"

OpenTracing 공급자로 Workhorse를 컴파일한 후 GITLAB_TRACING 환경 변수로 추적 구성을 설정하세요:

GITLAB_TRACING=opentracing://jaeger ./gitlab-workhorse

상관 관계 ID 전파#

사용자가 새 프로젝트 생성과 같은 HTTP 요청을 하면, 초기 요청은 Workhorse를 통해 다른 서비스로 라우팅되며, 해당 서비스는 다시 다른 요청을 할 수 있습니다. 서비스 전반에 걸쳐 요청을 추적하기 위해 Workhorse는 상관 관계 ID라고 하는 랜덤 값을 생성합니다. Workhorse는 X-Request-Id HTTP 헤더로 이 상관 관계 ID를 전송합니다.

GitLab Shell과 같은 일부 GitLab 서비스는 자체 상관 관계 ID를 생성합니다. 또한 Gitaly 같은 서비스는 원본 요청의 상관 관계 ID를 함께 전달하는 내부 API 호출을 수행합니다. 두 경우 모두 상관 관계 ID는 X-Request-Id HTTP 헤더로 전달됩니다.

기본적으로 Workhorse는 이 헤더를 무시하고 항상 새로운 상관 관계 ID를 생성합니다. 새 상관 관계 ID는 원본과 완전히 무관하기 때문에 디버깅이 더 어려워지고 분산 추적이 제대로 작동하지 않습니다.

Workhorse는 -propagateCorrelationID 커맨드라인 플래그로 수신된 상관 관계 ID를 전파하도록 구성할 수 있습니다. 신뢰할 수 없는 클라이언트가 임의의 값을 생성할 수 없도록 IP 허용 목록과 함께 이 옵션을 사용하는 것을 강력히 권장합니다.

IP 허용 목록은 Workhorse 구성 파일의 trusted_cidrs_for_propagation 옵션으로 지정합니다. 신뢰할 수 있는 CIDR 블록 목록을 지정하세요. 예를 들어:

trusted_cidrs_for_propagation = ["10.0.0.0/8", "127.0.0.1/32"]

X-Request-Id 헤더 외에도, Cloudflare의 수신 Cf-Ray 헤더를 채택하고 해당 헤더가 없을 경우 X-Request-Id로 폴백할 수 있습니다. 이 동작은 다음을 통해 활성화할 수 있습니다:

adopt_cf_ray_header = true

신뢰된 CIDR 구성도 동일하게 적용됩니다.

trusted_cidrs_for_propagation 및 adopt_cf_ray_header 옵션이 작동하려면 -propagateCorrelationID 플래그를 함께 사용해야 합니다.

신뢰된 프록시#

Workhorse가 NGINX와 같은 리버스 프록시 뒤에 있는 경우, trusted_cidrs_for_x_forwarded_for 옵션으로 X-Forwarded-For HTTP 헤더를 통해 원본 IP 주소를 제공하는 데 신뢰할 수 있는 CIDR 블록을 지정해야 합니다. 예를 들어:

trusted_cidrs_for_x_forwarded_for = ["10.0.0.0/8", "127.0.0.1/32"]

연속 프로파일링#

Workhorse는 Stackdriver Profiler를 사용하는 LabKit을 통해 연속 프로파일링을 지원합니다. 기본적으로 Stackdriver Profiler 구현은 빌드 태그를 사용하여 바이너리에 링크되어 있지만, 필수는 아니며 건너뛸 수 있습니다. 예를 들어:

make BUILD_TAGS=""

연속 프로파일링이 포함된 Workhorse를 컴파일한 후 GITLAB_CONTINUOUS_PROFILING 환경 변수로 프로파일러 구성을 설정하세요. 예를 들어:

GITLAB_CONTINUOUS_PROFILING="stackdriver?service=workhorse&service_version=1.0.1&project_id=test-123 ./gitlab-workhorse"

관련 주제#

• LabKit 모니터링 문서