기본 문제 해결#

더 고급 문제 해결을 시도하기 전에 다음을 확인합니다.

• Geo 사이트 상태를 점검합니다.
• PostgreSQL 복제 작동 여부를 확인합니다.

Geo 사이트 간 요청 추적#

Geo 문제를 해결할 때는 보조 사이트에서 기본 사이트로, 또는 그 반대 방향으로 오가는 요청을 추적해야 할 수 있습니다. GitLab은 상관 관계 ID를 사용해 여러 서비스에 걸친 관련 로그 항목을 연결합니다.

기본적으로 각 사이트는 요청을 받을 때 자체 상관 관계 ID를 생성합니다. 두 사이트에 걸친 하나의 요청을 같은 상관 관계 ID로 추적하려면, 요청을 받는 각 사이트의 Workhorse가 다른 Geo 사이트에서 들어오는 상관 관계 ID를 수용하도록 구성해야 합니다.

모든 Geo 사이트에서 다음을 수행합니다.

이 설정을 활성화하면 보조 사이트에서 기본 사이트로 보낸 요청이 로그에서 같은 상관 관계 ID를 공유하므로, 두 사이트에 걸쳐 요청을 추적할 수 있습니다.

Geo 사이트 상태 점검#

기본 사이트에서 다음을 수행합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Geo > Sites를 선택합니다.

GitLab은 문제가 있는지 파악할 수 있도록 각 보조 사이트에 대해 다음 상태 점검을 수행합니다.

• 사이트 실행 여부
• 보조 사이트 데이터베이스의 스트리밍 복제 구성 여부
• 보조 사이트 추적 데이터베이스의 구성 여부
• 보조 사이트 추적 데이터베이스의 연결 여부
• 보조 사이트 추적 데이터베이스의 최신 상태 여부
• 보조 사이트 상태 정보가 1시간 이내인지 여부

사이트 상태 정보가 1시간보다 오래되면 사이트가 "Unhealthy"로 표시됩니다. 이 경우 해당 보조 사이트의 Rails 콘솔에서 다음을 실행합니다:

Geo::MetricsUpdateWorker.new.perform

오류가 발생하면 그 오류가 job 완료도 막고 있을 가능성이 큽니다. 실행에 1시간 이상 걸리면, 상태가 간간이 갱신되더라도 "Unhealthy"가 오락가락하거나 계속 유지될 수 있습니다. 사용량 증가, 시간 경과에 따른 데이터 증가, 또는 데이터베이스 인덱스 누락 같은 성능 버그가 원인일 수 있습니다.

top이나 htop 같은 유틸리티로 시스템 CPU 부하를 모니터링할 수 있습니다. PostgreSQL이 CPU를 상당량 사용한다면 문제가 있거나 시스템 프로비저닝이 부족하다는 뜻일 수 있습니다. 시스템 메모리도 함께 모니터링해야 합니다.

메모리를 늘린다면 /etc/gitlab/gitlab.rb 구성에서 PostgreSQL의 메모리 관련 설정도 확인해야 합니다.

상태가 정상적으로 갱신되면 Sidekiq에 문제가 있을 수 있습니다. Sidekiq가 실행 중인지, 로그에 오류가 있는지 확인합니다. 이 job은 1분마다 큐에 추가되어야 하며, job 중복 제거 멱등성 키가 제대로 정리되지 않으면 실행되지 않을 수 있습니다. 이 job은 한 번에 하나만 실행되도록 Redis에서 배타적 리스를 획득합니다. 기본 사이트는 PostgreSQL 데이터베이스에 상태를 직접 기록합니다. 보조 사이트는 상태 데이터를 담은 HTTP Post 요청을 기본 사이트로 전송합니다.

특정 상태 점검이 실패할 때도 사이트가 "Unhealthy"로 표시됩니다. 해당 보조 사이트의 Rails 콘솔에서 다음을 실행하면 실패 원인을 확인할 수 있습니다:

Gitlab::Geo::HealthCheck.new.perform_checks

""(빈 문자열)이나 "Healthy"를 반환하면 점검이 성공한 것입니다. 그 외의 값을 반환하면 메시지에 무엇이 실패했는지 설명되거나 예외 메시지가 표시됩니다.

사용자 인터페이스에서 보고되는 일반적인 오류 메시지의 해결 방법은 일반적인 오류 수정을 참고합니다.

사용자 인터페이스가 작동하지 않거나 로그인할 수 없다면, Geo 상태 점검을 수동으로 실행해 이 정보와 몇 가지 세부 정보를 더 얻을 수 있습니다.

상태 점검 Rake 태스크#

이 Rake 태스크는 기본 또는 보조 Geo 사이트의 Rails 노드에서 실행할 수 있습니다:

sudo gitlab-rake gitlab:geo:check

출력 예시:

Checking Geo ...

GitLab Geo is available ... yes
GitLab Geo is enabled ... yes
This machine's Geo node name matches a database record ... yes, found a secondary node named "Shanghai"
GitLab Geo tracking database is correctly configured ... yes
Database replication enabled? ... yes
Database replication working? ... yes
GitLab Geo HTTP(S) connectivity ...
* Can connect to the primary node ... yes
HTTP/HTTPS repository cloning is enabled ... yes
Machine clock is synchronized ... yes
Git user has default SSH configuration? ... yes
OpenSSH configured to use AuthorizedKeysCommand ... yes
GitLab configured to disable writing to authorized_keys file ... yes
GitLab configured to store new projects in hashed storage? ... yes
All projects are in hashed storage? ... yes
Container Registry replication enabled ... yes
Container Registry Geo events ... last event at 2024-01-15 10:30:00 UTC

Checking Geo ... Finished

환경 변수로 사용자 지정 NTP 서버를 지정할 수도 있습니다. 예를 들면 다음과 같습니다:

sudo gitlab-rake gitlab:geo:check NTP_HOST="ntp.ubuntu.com" NTP_TIMEOUT="30"

지원되는 환경 변수는 다음과 같습니다.

Rake 태스크가 OpenSSH configured to use AuthorizedKeysCommand 점검을 건너뛰면 다음 출력이 표시됩니다:

OpenSSH configured to use AuthorizedKeysCommand ... skipped
  Reason:
  Cannot access OpenSSH configuration file
  Try fixing it:
  This is expected if you are using SELinux. You may want to check configuration manually
  For more information see:
  doc/administration/operations/fast_ssh_key_lookup.md

이 문제는 다음과 같은 경우에 발생할 수 있습니다:

• SELinux를 사용하는 경우.
• SELinux를 사용하지 않으며, 파일 권한 제한으로 git 사용자가 OpenSSH 설정 파일에 접근할 수 없는 경우.

후자의 경우 다음 출력은 root 사용자만 이 파일을 읽을 수 있음을 보여줍니다:

sudo stat -c '%G:%U %A %a %n' /etc/ssh/sshd_config

root:root -rw------- 600 /etc/ssh/sshd_config

파일 소유자나 권한을 변경하지 않고 git 사용자가 OpenSSH 설정 파일을 읽을 수 있게 하려면 acl을 사용합니다:

sudo setfacl -m u:git:r /etc/ssh/sshd_config

동기화 상태 Rake 태스크#

현재 동기화 정보는 Geo 보조 사이트에서 Rails(Puma, Sidekiq, Geo Log Cursor)를 실행하는 임의의 노드에서 이 Rake 태스크를 실행해 수동으로 확인할 수 있습니다.

GitLab은 오브젝트 스토리지에 저장된 오브젝트를 검증하지 않습니다. 오브젝트 스토리지를 사용하는 경우 "verified" 점검이 모두 성공 0건으로 표시됩니다. 이는 예상된 동작이며 문제가 아닙니다.

sudo gitlab-rake gitlab:geo:status

출력에는 다음이 포함됩니다:

• 실패가 발생한 경우 "failed" 항목의 개수
• "total" 대비 "succeeded" 항목의 비율

예시:

                        Geo Site Information
--------------------------------------------
                                      Name: example-us-east-2
                                       URL: https://gitlab.example.com
                                  Geo Role: Secondary
                             Health Status: Healthy
                This Node's GitLab Version: 17.7.0-ee

                     Replication Information
--------------------------------------------
                             Sync Settings: Full
                  Database replication lag: 0 seconds
           Last event ID seen from primary: 12345 (about 2 minutes ago)
                   Last event ID processed: 12345 (about 2 minutes ago)
                    Last status report was: 1 minute ago

                          Replication Status
--------------------------------------------
                    Lfs Objects replicated: succeeded 111 / total 111 (100%)
            Merge Request Diffs replicated: succeeded 28 / total 28 (100%)
                  Package Files replicated: succeeded 90 / total 90 (100%)
       Terraform State Versions replicated: succeeded 65 / total 65 (100%)
           Snippet Repositories replicated: succeeded 63 / total 63 (100%)
        Group Wiki Repositories replicated: succeeded 14 / total 14 (100%)
             Pipeline Artifacts replicated: succeeded 112 / total 112 (100%)
              Pages Deployments replicated: succeeded 55 / total 55 (100%)
                        Uploads replicated: succeeded 2 / total 2 (100%)
                  Job Artifacts replicated: succeeded 32 / total 32 (100%)
                Ci Secure Files replicated: succeeded 44 / total 44 (100%)
         Dependency Proxy Blobs replicated: succeeded 15 / total 15 (100%)
     Dependency Proxy Manifests replicated: succeeded 2 / total 2 (100%)
      Project Wiki Repositories replicated: succeeded 2 / total 2 (100%)
 Design Management Repositories replicated: succeeded 1 / total 1 (100%)
           Project Repositories replicated: succeeded 2 / total 2 (100%)

                         Verification Status
--------------------------------------------
                      Lfs Objects verified: succeeded 111 / total 111 (100%)
              Merge Request Diffs verified: succeeded 28 / total 28 (100%)
                    Package Files verified: succeeded 90 / total 90 (100%)
         Terraform State Versions verified: succeeded 65 / total 65 (100%)
             Snippet Repositories verified: succeeded 63 / total 63 (100%)
          Group Wiki Repositories verified: succeeded 14 / total 14 (100%)
               Pipeline Artifacts verified: succeeded 112 / total 112 (100%)
                Pages Deployments verified: succeeded 55 / total 55 (100%)
                          Uploads verified: succeeded 2 / total 2 (100%)
                    Job Artifacts verified: succeeded 32 / total 32 (100%)
                  Ci Secure Files verified: succeeded 44 / total 44 (100%)
           Dependency Proxy Blobs verified: succeeded 15 / total 15 (100%)
       Dependency Proxy Manifests verified: succeeded 2 / total 2 (100%)
        Project Wiki Repositories verified: succeeded 2 / total 2 (100%)
   Design Management Repositories verified: succeeded 1 / total 1 (100%)
             Project Repositories verified: succeeded 2 / total 2 (100%)

모든 오브젝트가 복제되고 검증되었으며, 이 용어들은 Geo 용어집에 정의되어 있습니다. 각 데이터 유형을 복제하고 검증하는 데 사용하는 방법은 지원되는 Geo 데이터 유형에서 자세히 확인할 수 있습니다.

실패한 항목의 자세한 내용은 gitlab-rails/geo.log 파일을 확인합니다

복제 또는 검증 실패가 보이면 해결을 시도할 수 있습니다.

Geo 검사 Rake 태스크 실행 시 발견되는 오류 수정#

이 Rake 태스크를 실행할 때 노드가 올바르게 구성되지 않았다면 오류 메시지가 표시될 수 있습니다:

sudo gitlab-rake gitlab:geo:check

• Rails가 데이터베이스에 연결할 때 비밀번호를 제공하지 않았습니다.

  Checking Geo ...
  
  GitLab Geo is available ... Exception: fe_sendauth: no password supplied
  GitLab Geo is enabled ... Exception: fe_sendauth: no password supplied
  ...
  Checking Geo ... Finished
  

  postgresql['sql_user_password']의 해시를 만들 때 사용한 평문 비밀번호가 gitlab_rails['db_password']에 설정되어 있는지 확인합니다.

• Rails가 데이터베이스에 연결할 수 없습니다.

  Checking Geo ...
  
  GitLab Geo is available ... Exception: FATAL:  no pg_hba.conf entry for host "1.1.1.1",  user "gitlab", database "gitlabhq_production", SSL on
  FATAL:  no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL off
  GitLab Geo is enabled ... Exception: FATAL:  no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL on
  FATAL:  no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL off
  ...
  Checking Geo ... Finished
  

  Rails 노드의 IP 주소가 postgresql['md5_auth_cidr_addresses']에 포함되어 있는지 확인합니다. 또한 IP 주소에 서브넷 마스크를 포함했는지 확인합니다: postgresql['md5_auth_cidr_addresses'] = ['1.1.1.1/32'].

• Rails가 잘못된 비밀번호를 제공했습니다.

  Checking Geo ...
  GitLab Geo is available ... Exception: FATAL:  password authentication failed for user "gitlab"
  FATAL:  password authentication failed for user "gitlab"
  GitLab Geo is enabled ... Exception: FATAL:  password authentication failed for user "gitlab"
  FATAL:  password authentication failed for user "gitlab"
  ...
  Checking Geo ... Finished
  

  gitlab-ctl pg-password-md5 gitlab을 실행해 비밀번호를 입력하는 방식으로, postgresql['sql_user_password']의 해시를 만들 때 사용한 올바른 비밀번호가 gitlab_rails['db_password']에 설정되어 있는지 확인합니다.

• 점검이 not a secondary node를 반환합니다.

  Checking Geo ...
  
  GitLab Geo is available ... yes
  GitLab Geo is enabled ... yes
  GitLab Geo tracking database is correctly configured ... not a secondary node
  Database replication enabled? ... not a secondary node
  ...
  Checking Geo ... Finished
  

  기본 사이트의 웹 인터페이스에서 Admin 영역의 Geo > Sites에 보조 사이트를 추가했는지 확인합니다. 또한 기본 사이트의 Admin 영역에서 보조 사이트를 추가할 때 gitlab_rails['geo_node_name']을 입력했는지 확인합니다.

• 점검이 Exception: PG::UndefinedTable: ERROR: relation "geo_nodes" does not exist를 반환합니다.

  Checking Geo ...
  
  GitLab Geo is available ... no
    Try fixing it:
    Add a new license that includes the GitLab Geo feature
    For more information see:
    https://about.gitlab.com/features/gitlab-geo/
  GitLab Geo is enabled ... Exception: PG::UndefinedTable: ERROR:  relation "geo_nodes" does not exist
  LINE 8:                WHERE a.attrelid = '"geo_nodes"'::regclass
                                             ^
  :               SELECT a.attname, format_type(a.atttypid, a.atttypmod),
                       pg_get_expr(d.adbin, d.adrelid), a.attnotnull, a.atttypid, a.atttypmod,
                       c.collname, col_description(a.attrelid, a.attnum) AS comment
                  FROM pg_attribute a
                  LEFT JOIN pg_attrdef d ON a.attrelid = d.adrelid AND a.attnum = d.adnum
                  LEFT JOIN pg_type t ON a.atttypid = t.oid
                  LEFT JOIN pg_collation c ON a.attcollation = c.oid AND a.attcollation <> t.typcollation
                 WHERE a.attrelid = '"geo_nodes"'::regclass
                   AND a.attnum > 0 AND NOT a.attisdropped
                 ORDER BY a.attnum
  ...
  Checking Geo ... Finished
  

  PostgreSQL 메이저 버전 업그레이드(9 > 10)를 수행할 때는 예상된 동작입니다. initiate-the-replication-process를 따릅니다.

• Rails에 Geo 추적 데이터베이스에 연결하는 데 필요한 설정이 없는 것으로 보입니다.

  Checking Geo ...
  
  GitLab Geo is available ... yes
  GitLab Geo is enabled ... yes
  GitLab Geo tracking database is correctly configured ... no
  Try fixing it:
  Rails does not appear to have the configuration necessary to connect to the Geo tracking database. If the tracking database is running on a node other than this one, then you may need to add configuration.
  ...
  Checking Geo ... Finished
  

  • 모든 서비스를 단일 노드에서 실행하는 보조 사이트라면 Geo 데이터베이스 복제 - 보조 서버 구성을 따릅니다.
  • 보조 사이트의 추적 데이터베이스를 전용 노드에서 실행한다면 다중 서버용 Geo - Geo 보조 사이트에 Geo 추적 데이터베이스 구성을 따릅니다
  • 보조 사이트의 추적 데이터베이스를 Patroni 클러스터에서 실행한다면 Geo 데이터베이스 복제 - 추적 PostgreSQL 데이터베이스용 Patroni 클러스터 구성을 따릅니다
  • 보조 사이트의 추적 데이터베이스를 외부 데이터베이스에서 실행한다면 외부 PostgreSQL 인스턴스를 사용하는 Geo를 따릅니다
  • GitLab Rails 앱을 실행하는 서비스(Puma, Sidekiq, Geo Log Cursor)가 없는 노드에서 Geo 검사 태스크를 실행했다면 이 오류는 무시할 수 있습니다. 해당 노드에는 Rails 구성이 필요하지 않습니다.

메시지: Container Registry Geo events ... none found#

Container Registry Geo events ... none found가 표시되는데 Container Registry 복제 이벤트가 있어야 한다고 예상한다면, 기본 사이트의 레지스트리 알림 설정이 Container Registry 복제 구성 가이드와 일치하는지 확인합니다.

메시지: Machine clock is synchronized ... Exception#

Rake 태스크는 서버 시계가 NTP와 동기화되어 있는지 확인하려고 시도합니다. Geo가 올바르게 동작하려면 시계가 동기화되어 있어야 합니다. 예를 들어 보안상의 이유로, 기본 사이트와 보조 사이트의 서버 시간이 약 1분 이상 차이 나면 Geo 사이트 간 요청이 실패합니다. 이 점검 태스크가 시간 불일치가 아닌 다른 이유로 완료되지 못했다면, 반드시 Geo가 동작하지 않는다는 뜻은 아닙니다.

점검을 수행하는 Ruby gem에는 기준 시간 소스로 pool.ntp.org가 하드코딩되어 있습니다.

• 예외 메시지 Machine clock is synchronized ... Exception: Timeout::Error

  이 문제는 서버가 pool.ntp.org 호스트에 접근할 수 없을 때 발생합니다.

• 예외 메시지 Machine clock is synchronized ... Exception: No route to host - recvfrom(2)

  이 문제는 pool.ntp.org 호스트명이 시간 서비스를 제공하지 않는 서버로 확인될 때 발생합니다.

이 경우 환경 변수로 사용자 지정 NTP 서버를 지정합니다.

클라우드 네이티브 GitLab 배포에서는 Kubernetes의 컨테이너가 호스트 시계에 접근할 수 없으므로 오류가 발생합니다:

Machine clock is synchronized ... Exception: getaddrinfo: Servname not supported for ai_socktype

메시지: cannot execute INSERT in a read-only transaction#

보조 사이트에서 이 오류가 발생하면 gitlab-rails나 gitlab-rake 명령을 비롯한 GitLab Rails 사용 전반과 Puma, Sidekiq, Geo Log Cursor 서비스에 영향을 줄 가능성이 큽니다.

ActiveRecord::StatementInvalid: PG::ReadOnlySqlTransaction: ERROR:  cannot execute INSERT in a read-only transaction
/opt/gitlab/embedded/service/gitlab-rails/app/models/application_record.rb:86:in `block in safe_find_or_create_by'
/opt/gitlab/embedded/service/gitlab-rails/app/models/concerns/cross_database_modification.rb:92:in `block in transaction'
/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/database.rb:332:in `block in transaction'
/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/database.rb:331:in `transaction'
/opt/gitlab/embedded/service/gitlab-rails/app/models/concerns/cross_database_modification.rb:83:in `transaction'
/opt/gitlab/embedded/service/gitlab-rails/app/models/application_record.rb:86:in `safe_find_or_create_by'
/opt/gitlab/embedded/service/gitlab-rails/app/models/shard.rb:21:in `by_name'
/opt/gitlab/embedded/service/gitlab-rails/app/models/shard.rb:17:in `block in populate!'
/opt/gitlab/embedded/service/gitlab-rails/app/models/shard.rb:17:in `map'
/opt/gitlab/embedded/service/gitlab-rails/app/models/shard.rb:17:in `populate!'
/opt/gitlab/embedded/service/gitlab-rails/config/initializers/fill_shards.rb:9:in `<top (required)>'
/opt/gitlab/embedded/service/gitlab-rails/config/environment.rb:7:in `<top (required)>'
/opt/gitlab/embedded/bin/bundle:23:in `load'
/opt/gitlab/embedded/bin/bundle:23:in `<main>'

PostgreSQL 읽기 전용 복제본 데이터베이스에서는 다음 오류가 발생합니다:

2023-01-17_17:44:54.64268 ERROR:  cannot execute INSERT in a read-only transaction
2023-01-17_17:44:54.64271 STATEMENT:  /*application:web,db_config_name:main*/ INSERT INTO "shards" ("name") VALUES ('storage1') RETURNING "id"

이 상황은 다음과 같은 경우에 발생할 수 있습니다:

• 초기 구성 중 보조 사이트가 아직 자신이 보조 사이트임을 인식하지 못한 경우입니다. 이 오류를 해결하려면 3단계. 보조 사이트 추가를 따릅니다.

• Geo 보조 사이트를 업그레이드하는 중인 경우입니다. gitlab_rails['auto_migrate']가 true로 설정되어 있어 GitLab이 복제본 데이터베이스에 데이터베이스 마이그레이션을 시도할 수 있는데, 이는 필요하지 않습니다. 이 오류를 해결하는 방법은 다음과 같습니다:

  1. 보조 사이트의 GitLab Rails 노드에 root로 SSH 접속합니다.

  2. /etc/gitlab/gitlab.rb를 편집해 이 설정을 주석 처리하거나 false로 설정합니다:

     gitlab_rails['auto_migrate'] = false
     

  3. GitLab을 재구성합니다:

     sudo gitlab-ctl reconfigure
     

PostgreSQL 복제 작동 여부 확인#

PostgreSQL 복제가 작동하는지 확인하려면 다음을 점검합니다:

• 사이트가 올바른 데이터베이스 노드를 가리키는지 확인합니다.
• Geo가 현재 사이트를 올바르게 감지하는지 확인합니다.

문제가 계속되면 고급 복제 문제 해결을 참고합니다.

사이트가 가리키는 데이터베이스 노드 확인#

기본 Geo 사이트가 쓰기 권한이 있는 데이터베이스 노드를 가리키도록 해야 합니다.

보조 사이트는 읽기 전용 데이터베이스 노드만 가리켜야 합니다.

Geo의 현재 사이트 감지 여부 확인#

Geo는 다음 논리에 따라 /etc/gitlab/gitlab.rb에서 현재 Puma 또는 Sidekiq 노드의 Geo 사이트 이름을 찾습니다:

1. "Geo node name"을 가져옵니다 (설정 이름을 "Geo site name"으로 변경하는 이슈가 있습니다):
   • Linux 패키지: gitlab_rails['geo_node_name'] 설정을 가져옵니다.
   • GitLab Helm 차트: global.geo.nodeName 설정을 가져옵니다(Charts와 GitLab Geo 참고).
2. 해당 값이 정의되어 있지 않으면 external_url 설정을 가져옵니다.

이 이름은 Geo Sites 대시보드에서 같은 Name을 가진 Geo 사이트를 찾는 데 사용됩니다.

현재 머신의 사이트 이름이 데이터베이스의 사이트와 일치하는지 확인하려면 검사 태스크를 실행합니다:

sudo gitlab-rake gitlab:geo:check

현재 머신의 사이트 이름과, 일치하는 데이터베이스 레코드가 기본 사이트인지 보조 사이트인지를 표시합니다.

This machine's Geo node name matches a database record ... yes, found a secondary node named "Shanghai"

This machine's Geo node name matches a database record ... no
  Try fixing it:
  You could add or update a Geo node database record, setting the name to "https://example.com/".
  Or you could set this machine's Geo node name to match the name of an existing database record: "London", "Shanghai"
  For more information see:
  doc/administration/geo/replication/troubleshooting/_index.md#can-geo-detect-the-current-node-correctly

Name 필드 설명에 있는 권장 사이트 이름에 대한 자세한 내용은 Geo Admin 영역 공통 설정을 참고합니다.

OS 로케일 데이터 호환성 확인#

가능하다면 모든 사이트의 Geo 노드를 Geo 실행 요구 사항에 정의된 대로 같은 방법과 같은 운영 체제로 배포해야 합니다.

Geo 사이트 간에 서로 다른 운영 체제나 서로 다른 운영 체제 버전을 배포한다면, Geo를 설정하기 전에 로케일 데이터 호환성 점검을 수행해야 합니다. 여러 GitLab 배포 방법을 섞어 쓰는 경우에도 glibc를 확인해야 합니다. Linux 패키지 설치, GitLab Docker 컨테이너, Helm 차트 배포, 외부 데이터베이스 서비스 간에 로케일이 다를 수 있습니다. glibc 버전 호환성을 확인하는 방법을 포함해 PostgreSQL용 운영 체제 업그레이드 문서를 참고합니다.

Geo는 PostgreSQL과 스트리밍 복제를 사용해 Geo 사이트 간에 데이터를 복제합니다. PostgreSQL은 텍스트 정렬에 운영 체제 C 라이브러리가 제공하는 로케일 데이터를 사용합니다. C 라이브러리의 로케일 데이터가 Geo 사이트 간에 호환되지 않으면 잘못된 쿼리 결과가 발생하고, 이는 보조 사이트의 잘못된 동작으로 이어집니다.

예를 들어 Ubuntu 18.04(및 그 이전)와 RHEL/CentOS 7(및 그 이전)은 이후 릴리스와 호환되지 않습니다. 자세한 내용은 PostgreSQL 위키를 참고합니다.

일반적인 오류 수정#

이 절에서는 웹 인터페이스의 Admin 영역에 보고되는 일반적인 오류 메시지와 그 해결 방법을 설명합니다.

기존 추적 데이터베이스를 재사용할 수 없음#

Geo는 기존 추적 데이터베이스를 재사용할 수 없습니다.

새 보조 사이트를 사용하거나, Geo 보조 사이트 복제 재설정에 따라 보조 사이트 전체를 재설정하는 것이 가장 안전합니다.

재설정하지 않고 보조 사이트를 재사용하면 보조 사이트가 일부 Geo 이벤트를 놓쳤을 수 있어 위험합니다. 예를 들어 삭제 이벤트를 놓치면 보조 사이트에 삭제되어야 할 데이터가 영구히 남습니다. 마찬가지로 데이터의 물리적 위치를 옮기는 이벤트를 놓치면, 한쪽 위치에는 데이터가 영구히 고립되고 다른 쪽 위치에는 재검증될 때까지 데이터가 없습니다. GitLab이 해시 스토리지로 전환한 이유가 여기에 있으며, 해시 스토리지에서는 데이터를 옮길 필요가 없습니다. 이벤트 손실로 인한 다른 알려지지 않은 문제도 있을 수 있습니다.

테스트 환경처럼 이러한 위험이 해당되지 않거나, 메인 Postgres 데이터베이스에 Geo 사이트 추가 이후의 모든 Geo 이벤트가 여전히 남아 있음을 알고 있다면 이 상태 점검을 우회할 수 있습니다:

1. 마지막으로 처리된 이벤트 시각을 확인합니다. 보조 사이트의 Rails 콘솔에서 다음을 실행합니다:

   Geo::EventLogState.last.created_at.utc
   

2. 출력을 복사합니다. 예를 들면 2024-02-21 23:50:50.676918 UTC입니다.

3. 보조 사이트의 생성 시각을 더 이전으로 보이도록 변경합니다. 기본 사이트의 Rails 콘솔에서 다음을 실행합니다:

   GeoNode.secondary_nodes.last.update_column(:created_at, DateTime.parse('2024-02-21 23:50:50.676918 UTC') - 1.second)
   

   이 명령은 문제가 발생한 보조 사이트가 가장 마지막에 생성된 사이트라고 가정합니다.

4. Admin > Geo > Sites에서 보조 사이트의 상태를 갱신합니다. 보조 사이트의 Rails 콘솔에서 다음을 실행합니다:

   Geo::MetricsUpdateWorker.new.perform
   

5. 보조 사이트가 정상으로 표시되어야 합니다. 그렇지 않으면 보조 사이트에서 gitlab-rake gitlab:geo:check를 실행하거나, 보조 사이트를 다시 추가한 뒤 아직 Rails를 재시작하지 않았다면 재시작합니다.

6. 누락되거나 오래된 데이터를 다시 동기화하려면 Admin > Geo > Sites로 이동합니다.

7. 보조 사이트 아래에서 Replication Details를 선택합니다.

8. 모든 데이터 유형에 대해 Reverify all을 선택합니다.

Geo 사이트에 쓰기 가능한 데이터베이스가 있음#

이 오류 메시지는 Geo가 접근할 수 있어야 하는 보조 사이트의 데이터베이스 복제본에 문제가 있음을 나타냅니다. 보조 사이트 데이터베이스에 쓰기가 가능하다면 해당 데이터베이스가 기본 사이트와의 복제용으로 구성되지 않았다는 신호입니다. 보통 다음 중 하나를 뜻합니다:

• 지원되지 않는 복제 방법을 사용했습니다(예: 논리 복제).
• Geo 데이터베이스 복제 설정 지침을 올바르게 따르지 않았습니다.
• 데이터베이스 연결 정보가 올바르지 않습니다. 즉 /etc/gitlab/gitlab.rb 파일에 잘못된 사용자를 지정했습니다.

Geo 보조 사이트에는 두 개의 별도 PostgreSQL 인스턴스가 필요합니다:

• 기본 사이트의 읽기 전용 복제본입니다.
• 복제 메타데이터를 보관하는 일반 쓰기 가능 인스턴스, 즉 Geo 추적 데이터베이스입니다.

이 오류 메시지는 보조 사이트의 복제본 데이터베이스가 잘못 구성되어 복제가 중단되었음을 나타냅니다.

데이터베이스를 복구하고 복제를 재개하려면 다음 중 하나를 수행합니다:

• Geo 보조 사이트 복제를 재설정합니다.
• Linux 패키지로 새 Geo 보조 사이트를 설정합니다.

새 보조 사이트를 처음부터 설정한다면 Geo 클러스터에서 기존 사이트를 제거해야 합니다.

Geo 사이트가 기본 사이트의 데이터베이스를 복제하지 않는 것으로 보임#

데이터베이스가 올바르게 복제되지 않는 가장 일반적인 원인은 다음과 같습니다:

• 보조 사이트가 기본 사이트에 도달할 수 없습니다. 자격 증명과 방화벽 규칙을 확인합니다.
• SSL 인증서 문제입니다. 기본 사이트에서 /etc/gitlab/gitlab-secrets.json을 복사했는지 확인합니다.
• 데이터베이스 스토리지 디스크가 가득 찼습니다.
• 데이터베이스 복제 슬롯이 잘못 구성되었습니다.
• 데이터베이스가 복제 슬롯이나 다른 대안을 사용하지 않으며, WAL 파일이 제거되어 복제를 따라잡을 수 없습니다.

지원되는 구성을 위해 Geo 데이터베이스 복제 지침을 따랐는지 확인합니다.

Geo 데이터베이스 버전(...)이 최신 마이그레이션(...)과 일치하지 않음#

Linux 패키지 설치를 사용한다면 업그레이드 중에 무언가 실패했을 수 있습니다. 다음을 수행할 수 있습니다:

• sudo gitlab-ctl reconfigure를 실행합니다.
• 보조 사이트에서 root로 sudo gitlab-rake db:migrate:geo를 실행해 데이터베이스 마이그레이션을 수동으로 트리거합니다.

gitlab-rake gitlab:geo:status 실행 시 PG::UndefinedTable 오류#

sudo gitlab-rake gitlab:geo:status를 실행할 때 PG::UndefinedTable 오류가 발생할 수 있습니다. 이 문제는 Geo 추적 데이터베이스 마이그레이션이 실행되지 않았거나 중간에 중단되어 레지스트리 테이블이 없을 때 발생합니다.

해결 방법은 보류 중인 마이그레이션을 확인하고 실행하는 것입니다.

sudo gitlab-rake db:migrate:status:geo
sudo gitlab-rake db:migrate:geo

그런 다음 sudo gitlab-rake gitlab:geo:status를 다시 실행하여 추적 데이터베이스가 최신 상태인지 확인합니다.

GitLab이 리포지터리의 100%를 초과해 동기화되었다고 표시함#

프로젝트 레지스트리의 고립된 레코드가 원인일 수 있습니다. 이러한 레코드는 레지스트리 워커가 주기적으로 정리하므로, 스스로 해결될 시간을 둡니다.

기본 사이트의 체크섬 실패#

Geo Primary Verification 정보 화면에서 확인되는 체크섬 실패는 파일 누락이나 체크섬 불일치가 원인일 수 있습니다. gitlab-rails/geo.log 파일에서 "Repository cannot be checksummed because it does not exist" 또는 "File is not checksummable - file does not exist at: <path>" 같은 오류 메시지를 찾을 수 있습니다. 오류 메시지에는 누락된 파일을 식별하는 데 도움이 되는 파일 경로가 포함됩니다.

실패한 항목에 대한 추가 정보는 무결성 검사 Rake 태스크를 실행해 확인합니다:

sudo gitlab-rake gitlab:artifacts:check
sudo gitlab-rake gitlab:ci_secure_files:check
sudo gitlab-rake gitlab:lfs:check
sudo gitlab-rake gitlab:uploads:check

개별 오류의 자세한 정보는 VERBOSE=1 변수를 사용합니다.

보조 사이트가 UI에 Unhealthy로 표시됨#

기본 사이트의 /etc/gitlab/gitlab.rb에서 external_url 값을 변경했거나 프로토콜을 http에서 https로 바꿨다면, 보조 사이트가 Unhealthy로 표시될 수 있습니다. geo.log에서 다음 오류를 찾을 수도 있습니다:

"class": "Geo::NodeStatusRequestService",
...
"message": "Failed to Net::HTTP::Post to primary url: http://primary-site.gitlab.tld/api/v4/geo/status",
  "error": "Failed to open TCP connection to :80 (Connection refused - connect(2) for \"\" port 80)"

이 경우 모든 사이트에서 변경된 URL을 갱신합니다:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Geo > Sites를 선택합니다.
3. URL을 변경하고 변경 사항을 저장합니다.

메시지: 백업 중 ERROR: canceling statement due to conflict with recovery#

Geo 보조 사이트에서 백업을 실행하는 것은 지원되지 않습니다.

보조 사이트에서 백업을 실행하면 다음 오류 메시지가 표시될 수 있습니다:

Dumping PostgreSQL database gitlabhq_production ...
pg_dump: error: Dumping the contents of table "notes" failed: PQgetResult() failed.
pg_dump: error: Error message from server: ERROR:  canceling statement due to conflict with recovery
DETAIL:  User query might have needed to see row versions that must be removed.
pg_dump: error: The command was: COPY public.notes (id, note, [...], last_edited_at) TO stdout;

Geo 보조 사이트에서 GitLab 업그레이드 중에 데이터베이스 백업이 자동으로 수행되지 않도록 하려면 다음 빈 파일을 생성합니다:

sudo touch /etc/gitlab/skip-auto-backup

오브젝트 검증 중 기본 사이트의 높은 CPU 사용량#

GitLab 16.11부터 GitLab 17.2까지는 PostgreSQL 인덱스 누락으로 CPU 사용량이 높아지고 아티팩트 검증 진행이 느려집니다. 또한 Geo 보조 사이트가 비정상으로 보고될 수 있습니다. 이슈 471727에 이 동작이 자세히 설명되어 있습니다.

이 문제를 겪고 있는지 판단하려면 영향 여부 확인 절차를 따릅니다.

영향을 받는다면 우회 방법의 절차에 따라 인덱스를 수동으로 생성합니다. 인덱스를 생성하는 동안 PostgreSQL은 작업이 끝날 때까지 리소스를 약간 더 소비합니다. 이후 검증이 계속되는 동안에는 CPU 사용량이 계속 높을 수 있으나, 쿼리는 훨씬 더 빠르게 완료되고 보조 사이트 상태도 올바르게 갱신됩니다.

검증 실패: Verification timed out after (...)#

Geo가 같은 artifact_id에 대해 중복된 JobArtifactRegistry 항목을 생성할 수 있으며, 이는 기본 사이트와 보조 사이트 간 동기화 실패로 이어질 수 있습니다. 이 문제는 UploadRegistry와 PackageFileRegistry 항목에도 영향을 줄 수 있습니다.

이 문제를 겪고 있는지 판단하고 중복 항목을 제거하는 방법은 다음과 같습니다:

1. 보조 사이트에서 Rails 콘솔을 엽니다.

2. 중복이 있는 모델 레코드 ID의 개수를 확인합니다:

   artifact_ids = Geo::JobArtifactRegistry.group(:artifact_id).having('COUNT(*) > 1').pluck(:artifact_id); artifact_ids.size
   upload_ids = Geo::UploadRegistry.group(:file_id).having('COUNT(*) > 1').pluck(:file_id); upload_ids.size
   package_file_ids = Geo::PackageFileRegistry.group(:package_file_id).having('COUNT(*) > 1').pluck(:package_file_id); package_file_ids.size
   

3. ID를 출력합니다:

   puts 'BEGIN Artifact IDs', artifact_ids, 'END Artifact IDs'
   puts 'BEGIN Upload IDs', upload_ids, 'END Upload IDs'
   puts 'BEGIN Package File IDs', package_file_ids, 'END Package File IDs'
   

   출력이 비어 있으면 영향을 받지 않습니다. 비어 있지 않다면 나중에 연결이 끊길 경우를 대비해 터미널 출력을 텍스트 파일로 저장합니다.

4. 모든 중복을 삭제합니다:

   Geo::JobArtifactRegistry.where(artifact_id: artifact_ids).delete_all
   Geo::UploadRegistry.where(file_id: upload_ids).delete_all
   Geo::PackageFileRegistry.where(package_file_id: package_file_ids).delete_all
   

5. 백그라운드 job이 레지스트리 행을 다시 생성하고 재동기화할 때까지 기다립니다.

수정에 관한 소식은 이슈 479852에서 확인합니다.

보조 사이트에서 Geo Rake 검사 태스크 실행 시 end of file reached 오류#

보조 사이트에서 상태 점검 Rake 태스크를 실행할 때 다음 오류가 발생할 수 있습니다:

Can connect to the primary node ... no
Reason:
end of file reached

설정에 기본 사이트의 URL이 잘못 지정된 경우 발생할 수 있습니다. 문제를 해결하려면 Rails 콘솔에서 다음 명령을 실행합니다:

primary = Gitlab::Geo.primary_node
primary.internal_uri
Gitlab::HTTP.get(primary.internal_uri, allow_local_requests: true, limit: 10)

앞의 출력에서 internal_uri 값이 올바른지 확인합니다. 기본 사이트의 URL이 올바르지 않다면 /etc/gitlab/gitlab.rb와 Admin > Geo > Sites에서 다시 확인합니다.

Geo 메트릭 수집으로 인한 과도한 데이터베이스 IO#

Geo 메트릭 수집은 ci_job_artifact_states와 job_artifact_registry 같은 큰 테이블을 스캔하므로 비용이 복제된 데이터의 양에 비례해 커집니다. 다음 해결 방법을 순서대로 고려합니다.

1. 복제되는 데이터 양 줄이기. 근본 원인을 해결하고 동기화 및 검증 부하도 줄입니다.
2. 사전 계산된 검증 요약 사용. 전체 테이블 스캔을 증분 업데이트로 대체합니다.
3. 메트릭 수집 빈도 줄이기. 모니터링의 최신성을 데이터베이스 부하 감소와 맞바꿉니다.

Geo 메트릭 수집이 잦아 데이터베이스 부하가 높다면 geo_metrics_update_worker job의 실행 빈도를 줄일 수 있습니다. 이 조정은 메트릭 수집이 데이터베이스 성능에 큰 영향을 주는 대규모 GitLab 인스턴스에서 데이터베이스 부담을 완화하는 데 도움이 됩니다.

간격을 늘리면 Geo 메트릭이 덜 자주 갱신됩니다. 그 결과 메트릭이 더 오랜 기간 최신 상태가 아니게 되며, 이는 Geo 복제를 실시간으로 모니터링하는 능력에 영향을 줄 수 있습니다. 메트릭이 10분 넘게 최신 상태가 아니면 사이트는 Admin Area에서 임의로 "Unhealthy"로 표시됩니다.

다음 예시는 job이 30분마다 실행되도록 설정합니다. 필요에 맞게 cron 스케줄을 조정합니다.

사전 계산된 검증 요약 사용#

히스토리

• GitLab 19.0에서 geo_job_artifact_verification_summaries라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.

메트릭 수집 빈도를 줄이는 대신, CI job 아티팩트에 대해 사전 계산된 검증 요약을 활성화할 수 있습니다. 이 방식은 전체 테이블 스캔을 증분 갱신으로 대체하므로 변경된 데이터만 다시 집계합니다.

활성화하면 백그라운드 워커가 전용 테이블에 요약 집계를 유지합니다. 검증 상태가 바뀌면 데이터베이스 트리거가 해당 버킷을 dirty로 표시하고, 워커는 그 버킷만 다시 계산합니다. 이로써 대규모 인스턴스에서 메트릭 수집으로 인한 데이터베이스 부하가 수십 배 이상 줄어듭니다.

활성화하는 방법은 다음과 같습니다:

sudo gitlab-rails runner 'Feature.enable(:geo_job_artifact_verification_summaries)'

비활성화하는 방법은 다음과 같습니다:

sudo gitlab-rails runner 'Feature.disable(:geo_job_artifact_verification_summaries)'