빌드 중 소프트웨어 가져오고 컴파일하기
서비스를 위한 최상위 구성 객체 추가하기
서비스 목록에 서비스 포함
서비스용 활성화 및 비활성화 레시피 작성
- 활성화 레시피
  - 로그 디렉토리
- 레시피 비활성화
로그 로테이션 처리 방법 확인 및 문서화
서비스에 대한 추가 구성 파싱

Omnibus GitLab에 새로운 서비스 추가하기

GitLab에 새로운 서비스를 추가하려면 다음 단계를 따라야 합니다:

빌드 중 소프트웨어 가져오고 컴파일하기
서비스를 위한 최상위 구성 객체 추가하기
서비스를 서비스 목록에 포함시키기
서비스를 위한 활성화 및 비활성화 레시피 생성하기
로그 회전을 처리하는 방법 결정 및 문서화하기

옵션으로 서비스를 위한 추가 구성 구문 분석을 하는 것이 일반적 작업입니다.

빌드 중 소프트웨어 가져오고 컴파일하기

프로젝트에 이미 포함되어 있지 않다면 서비스를 위한 새로운 소프트웨어 정의를 추가해야 합니다.

서비스를 위한 최상위 구성 객체 추가하기

files/gitlab-cookbooks에 있는 쿡북과 레시피들은 Omnibus GitLab 패키지가 설치된 인스턴스에서 gitlab-ctl reconfigure 중에 실행됩니다. 여기에 새로운 서비스의 설정을 추가해야 합니다.

기본 속성 정의

서비스를 구성하기 위해 기존 쿡북 중 하나를 선택하거나 서비스가 자체적으로 필요한 경우 새로운 쿡북을 생성하세요.

쿡북 안에는 attributes/default.rb 파일이 있어야 합니다. 여기에는 서비스의 기본 속성을 정의해야 합니다. 서비스에 대해 기본적으로 enable 옵션을 정의해야 합니다.

default['gitlab']['best_service']['enable'] = false
default['gitlab']['best_service']['dir'] = '/var/opt/gitlab/best-service'
default['gitlab']['best_service']['log_directory'] = '/var/log/gitlab/best-service'

default는 기본적인 쿡북 속성을 정의하는 방법입니다.
['gitlab']는 쿡북의 이름을 포함합니다.
['best_service']는 서비스의 이름입니다.
enable, dir, log_directory는 우리의 구성 설정입니다.
/var/opt/gitlab는 서비스의 작업 디렉토리 및 구성 파일이 위치하는 곳입니다.
/var/log/gitlab는 GitLab 패키지의 로그가 작성되는 위치입니다.

여기에 패키지에서 구성 가능한 모든 설정을 정의하세요. 현재 다른 설정을 기반으로 기본값을 계산해야 하는 경우에는 임시로 nil로 설정하세요.

명명 규칙

서비스는 주로 다음 세 가지 시나리오에서 참조됩니다:

서비스에 해당하는 Chef 속성에 액세스하기
사용자, 그룹, 서비스에 해당하는 항목 참조하기
서비스 이름을 해당 서비스 속성 조회 메서드에 전달하기
- “서비스가 활성화되었습니까?”
- “이 서비스에 해당하는 로그 소유권 세부 정보 가져오기”
- “이 서비스에 대한 runit 구성 생성하기”

위에서 언급한 첫 번째 경우에는 서비스 이름의 단어를 구분하기 위해 언더스코어를 사용합니다. 다른 두 경우에는 서비스 이름의 단어를 구분하기 위해 하이픈을 사용합니다. 구성이 주로 Ruby 객체로 사용되므로 언더스코어 대신 하이픈을 사용하는 것이 더 유연합니다(예: 언더스코어를 사용하면 구성 해시에서 심볼을 더 깔끔하게 사용할 수 있습니다).

예를 들어, GitLab Pages를 보면 속성은 Gitlab['gitlab_pages']와 node['gitlab_pages']로 사용 가능하며, 기본 디렉토리와 경로는 /var/log/gitlab/gitlab-pages 및 /var/opt/gitlab/gitlab-pages 와 같습니다. 비슷하게 메서드 호출은 service_enabled?("gitlab-pages")와 같이 보일 것입니다.

서비스를 위한 구성 Mash 생성하기

사용자가 /etc/gitlab/gitlab.rb에서 서비스를 구성할 수 있도록 하려면 서비스를 위한 최상위 Mash를 추가해야 합니다.

files/gitlab-cookbooks/package/libraries/config/gitlab.rb에는 attribute 메서드 목록이 있습니다.

만약 서비스가 GitLab 쿡북의 속성 안에 존재하는 경우, 그 속성을 attribute_block('gitlab') 블록 내에 추가해야 합니다. 그렇지 않은 경우, 서비스가 자체 쿡북을 가지고 있다면 해당 위에 추가하세요.

attribute('best_service')

EE 전용 속성의 경우 ee_attribute을 사용하세요.

ee_attribute('best_service')

서비스 구성을 설정 템플릿에 추가하기

우리는 전역 구성 템플릿을 유지하고 있으며, 서비스를 구성하는 방법에 대한 예시들이 주석 처리되어 있습니다.

이 파일은 패키지의 새로운 설치에서 /etc/gitlab/gitlab.rb가 됩니다.

서비스의 구성을 사용자가 변경할 수 있도록 노출시키려면 이 파일에 추가하세요. files/gitlab-config-template/gitlab.rb.template

최상의 서비스 구성

best_service['enable'] = true
best_service['dir'] = '/var/opt/gitlab/best-service'
best_service['log_directory'] = '/var/log/gitlab/best-service'

제공된 값은 기본값을 나타내는 것이 아니며, 서비스를 사용하기 쉽게 주석 처리하려는 것입니다. 가능한 경우 YOURSECRET과 같이 교체할 값이나 가장 합리적인 경우 기본값을 사용할 수 있습니다.

서비스 목록에 서비스 포함

레시피 내에서 서비스를 쉽게 활성화/비활성화할 수 있도록 하기 위해 서비스 목록에 서비스를 추가하고 적절한 그룹을 할당해야 합니다.

files/gitlab-cookbooks/package/libraries/config/services.rb 파일에서, 서비스를 GitLab EE 전용인지에 따라 Base 또는 EE Config 클래스에 서비스를 추가하세요.

service 'best_service', groups: ['bestest']

그룹을 지정하면 한꺼번에 여러 관련 서비스를 쉽게 비활성화/활성화할 수 있습니다.

기존 그룹 중 어느 것도 서비스의 기능과 일치하지 않거나 현재 그룹을 사용하여 서비스를 활성화/비활성화할 필요가 없는 경우, 일단 추가하지 않아도 됩니다.

사용할 수 있는 일부 예시 그룹:

옴니버스에서 기본적으로 활성화된 서비스인 경우 DEFAULT_GROUP 그룹을 추가해야 합니다.
대부분의 시나리오에서 서비스를 실제로 비활성화하지 말아야 하는 경우 SYSTEM_GROUP을 추가하세요.
GitLab Rails 구성에 의존하는 경우 rails 그룹을 추가하세요.
새로운 Prometheus 익스포터인 경우 prometheus 그룹을 추가하세요.

서비스용 활성화 및 비활성화 레시피 작성

활성화 레시피

기존 쿡북에 추가되는 경우 files/gitlab-cookbooks/<cookbook-name>/recipes/<service-name>.rb로 활성화 레시피를 작성해야 합니다. 서비스가 자체 쿡북을 가지고 있는 경우, 활성화 레시피는 files/gitlab-cookbooks/<cookbook-name>/recipes/enable.rb로 작성할 수 있습니다.

레시피에서는 서비스를 위한 작업 디렉토리를 /var/opt/gitlab에 생성해야 합니다. 서비스를 실행하는 시스템 사용자가 생성되도록 해야 합니다. 서비스에 필요한 구성 파일을 작업 디렉토리로 렌더링하도록 해야 합니다.

레시피의 마지막 부분에서는 runit 서비스 정의를 호출하여 레시피를 정의해야 합니다. 이 작업을 수행하려면, 쿡북의 templates/default 디렉토리에 sv-서비스이름-액션이름으로 시작하는 run 파일을 만들어야 합니다.

서비스에는 일반적으로 run, log-run, log-config가 필요합니다.

sv-best-service-log-config.erb:

<%= "s#@svlogd_size" if @svlogd_size %>
<%= "n#@svlogd_num" if @svlogd_num %>
<%= "t#@svlogd_timeout" if @svlogd_timeout %>
<%= "!#@svlogd_filter" if @svlogd_filter %>
<%= "u#@svlogd_udp" if @svlogd_udp %>
<%= "p#@svlogd_prefix" if @svlogd_prefix %>

sv-best-service-log-run.erb:

#!/bin/sh
exec chpst -P \
  -U root:<%= @options[:log_group] || 'root' %> \
  -u root:<%= @options[:log_group] || 'root' %> \
  svlogd -tt <%= @options[:log_directory] %>

sv-best-service-run.erb:

#!/bin/sh
exec 2>&1
<%= render("mount_point_check.erb") %>
cd <%= node['gitlab']['best-service']['dir'] %>
exec chpst -P /opt/gitlab/embedded/bin/best-service -config-flags -etc

실행하는 내용과 실행하는 사용자에 따라 run 파일을 다르게 구성해야 합니다. 다른 -run.erb를 참고하세요.

레시피 내에서 runit 서비스를 호출하고 시작해야 합니다:

runit_service "best-service" do
  options({
    configItem: 'value',
    [...]
    log_directory: logging_settings[:log_directory],
    log_user: logging_settings[:runit_owner],
    log_group: logging_settings[:runit_group],
  }.merge(params))
  log_options logging_settings[:options]
end

if node['gitlab']['bootstrap']['enable']
  execute "/opt/gitlab/bin/gitlab-ctl start best-service" do
    retries 20
  end
end

로그 디렉토리

위에서 언급된 예시 설정에는 logging_settings가 포함되어 있으며, 이는 서비스 로그 디렉토리 및 해당 로그 디렉토리에 할당된 로그 그룹, svlogd 실행에 사용되는 그룹에 대한 구성 설정에 일관성 있는 참조를 제공하기 위해 LogfilesHelper 클래스를 사용합니다.

이러한 설정을 사용하려면, 서비스의 enable.rb에 LogfilesHelper 클래스를 포함시켜야 합니다. 예:

[...]
logfiles_helper = LogfilesHelper.new(node)
logging_settings = logfiles_helper.logging_settings('best-service')
[...]

이 설정을 사용하려면, 기본 사용자/그룹과 함께 default_logdir_ownership 클래스 메소드 내에 best-service를 서비스 목록에 추가하세요. 구체적인 사용자/그룹이 필요하지 않은 경우에는 기본적으로 { username: gitlab_user, group: gitlab_group }를 사용하세요.

레시피 비활성화

레시피를 비활성화하려면 기존 Cookbook에 추가되는 경우 files/gitlab-cookbooks/<cookbook-name>/recipes/<service-name>_disable.rb에 생성되어야 합니다. 서비스가 자체적인 Cookbook을 갖고 있는 경우, 비활성화 레시피는 files/gitlab-cookbooks/<cookbook-name>/recipes/disable.rb로 생성될 수 있습니다.

레시피는 서비스가 비활성화될 때 수행할 모든 정리 작업을 포함하고 runit 서비스를 비활성화하는 호출을 가져야 합니다.

runit_service "best-service" do
  action :disable
end

로그 로테이션 처리 방법 확인 및 문서화

Omnibus에서 특정 서비스에 대한 로그 로테이션은 logrotate, svlogd, 둘 다 또는 둘 다 아닌 것으로 처리될 수 있습니다. 새로운 서비스는 해당 서비스의 로그를 관리하고 회전시키는 책임을 나타내는 로그 로테이션 테이블에 포함되어야 합니다. Omnibus GitLab에 서비스를 추가할 때 다음을 수행해야 합니다:

새로운 서비스에 대해 로그 로테이션이 실행 중인지 확인하세요.
새로운 서비스가 로그 로테이션 테이블에 추가되도록 병합 요청을 오픈하세요.

runit(svlogd)를 사용하지 않는 새로운 로그가 추가되는 경우, 해당 로그는 수동으로 logrotate 구성에 추가되어야 합니다. 더 많은 정보를 보려면 로그로테이션 처리 개선 이슈를 참조하세요.

서비스에 대한 추가 구성 파싱

사용자가 설정한 다른 옵션들에 기반하여 특정 구성 옵션을 채우고 싶은 경우, 해당 서비스용 라이브러리를 추가해야 합니다.

라이브러리는 files/gitlab-cookbooks/<cookbook name>/libraries/<service-name>.rb에 추가되어야 합니다.

라이브러리는 서비스 명칭으로 지정된 모듈이며 parse_variables 메서드가 포함되어야 합니다.

module BestService
  class << self
    def parse_variables
      # 사용자가 제공한 구성 값 기반의 추가 구성 설정 설정
    end
  end
end

그런 다음 GitLab 구성이 parse_variables 메서드를 호출하도록해야 합니다.

files/gitlab-cookbooks/package/libraries/config/gitlab.rb로 이동한 후 속성을 라이브러리를 사용하도록 업데이트하세요.

attribute('best_service').use { BestService }

변수 파싱 순서가 중요합니다. 따라서 라이브러리가 다른 서비스의 라이브러리보다 나중에 파싱되기를 원하는 경우 우선 순위 값을 나중에 오는 값으로 업데이트해야 합니다. (기본 우선 순위 값은 20입니다)

attribute('expected_service').use { ExpectedService }
attribute('best_service', sequence: 25).use { BestService }