InfoGrab DocsInfoGrab Docs

Service Ping 내부 API

요약

Service Ping 내부 API는 Service Ping 내보내기 도구처럼 GitLab 인스턴스를 대신해 Service Ping을 보고하는 서비스가 사용합니다. 요청에는 Workhorse 내부 API 인증과 Service Ping JSON Web Token(JWT)이 필요합니다.

Service Ping 내부 API는 Service Ping 내보내기 도구처럼 GitLab 인스턴스를 대신해 Service Ping을 보고하는 서비스가 사용합니다. 다른 소비자는 이 API를 사용할 수 없습니다. 이 문서는 GitLab 코드베이스에서 작업하는 사람을 위한 것입니다.

인증#

요청에는 Workhorse 내부 API 인증과 Service Ping JSON Web Token(JWT)이 필요합니다.

JWT를 만들려면 클라이언트는 다음을 수행합니다.

  1. Service Ping 시크릿을 읽습니다. 시크릿은 gitlab.yml의 service_ping.secret_file로 지정한 파일에 있으며, 기본값은 GitLab Rails 루트의 .gitlab_service_ping_secret입니다. 이 파일에는 Base64로 인코딩된 32바이트 값이 들어 있으며 모든 Rails 노드에서 같아야 합니다. 파일이 만들어지는 방식은 설치 방법에 따라 다릅니다.
    • Linux 패키지 설치: gitlab-ctl reconfigure가 파일을 만듭니다. 값은 gitlab.rb에 gitlab_rails['service_ping_secret']이 설정되어 있으면 그 값에서 가져오고, 그렇지 않으면 생성되어 /etc/gitlab/gitlab-secrets.json에 저장됩니다.
    • Helm 차트 설치: 차트가 Kubernetes Secret을 생성하거나 사용자가 제공한 Secret을 사용하고 이를 Rails Pod에 마운트합니다.
    • 자체 컴파일 설치와 GDK 같은 기타 설치: 파일이 없으면 GitLab이 시작할 때 파일을 만듭니다. Rails 루트에 쓸 수 없으면 GitLab이 경고를 기록하고 파일이 생길 때까지 API 요청이 401 Unauthorized로 실패합니다.
  2. 다음 클레임으로 시크릿과 HS256 알고리즘을 사용해 JWT에 서명합니다.
    • iss: gitlab-service-ping
    • aud: gitlab
    • sub: 호출하는 서비스의 이름입니다. 예: service-ping-exporter.
    • iat: 현재 시간입니다. GitLab은 5분보다 오래전에 발급된 토큰을 거부합니다.
  3. JWT를 Gitlab-Service-Ping-Api-Request 헤더로 전달합니다.

내부 엔드포인트#

인스턴스 식별 정보와 Service Ping 설정 조회#

GET 요청으로 인스턴스의 식별 정보와 Service Ping 설정을 가져옵니다.

GET /internal/service_ping/instance

요청 예시:

curl --header "Gitlab-Service-Ping-Api-Request: <json-web-token>" "https://gitlab.example.com/api/v4/internal/service_ping/instance"

응답 예시:

{
  "identity": {
    "instance_id": "d4f5e6a7-1b2c-4d3e-8f9a-0b1c2d3e4f5a",
    "unique_instance_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "host_name": "gitlab.example.com",
    "instance_version": "18.6.0-ee"
  },
  "settings": {
    "service_ping_enabled": true,
    "service_ping_generation_enabled": true,
    "service_ping_optional_metrics_enabled": true
  }
}

service_ping_enabled는 라이선스가 Service Ping을 요구하는 경우를 포함해 인스턴스가 Service Ping을 전송할 수 있는지를 나타냅니다. Rails는 service_ping_generation_enabled도 true일 때만 Service Ping을 전송합니다. 필드는 추가만 되고 이름이 바뀌거나 제거되지 않으므로 이전 클라이언트도 계속 동작합니다.

Service Ping 내부 API

GitLab v19.6
원문 보기

요약

Service Ping 내부 API는 Service Ping 내보내기 도구처럼 GitLab 인스턴스를 대신해 Service Ping을 보고하는 서비스가 사용합니다. 요청에는 Workhorse 내부 API 인증과 Service Ping JSON Web Token(JWT)이 필요합니다.

Service Ping 내부 API는 Service Ping 내보내기 도구처럼 GitLab 인스턴스를 대신해 Service Ping을 보고하는 서비스가 사용합니다. 다른 소비자는 이 API를 사용할 수 없습니다. 이 문서는 GitLab 코드베이스에서 작업하는 사람을 위한 것입니다.

인증#

요청에는 Workhorse 내부 API 인증과 Service Ping JSON Web Token(JWT)이 필요합니다.

JWT를 만들려면 클라이언트는 다음을 수행합니다.

  1. Service Ping 시크릿을 읽습니다. 시크릿은 gitlab.yml의 service_ping.secret_file로 지정한 파일에 있으며, 기본값은 GitLab Rails 루트의 .gitlab_service_ping_secret입니다. 이 파일에는 Base64로 인코딩된 32바이트 값이 들어 있으며 모든 Rails 노드에서 같아야 합니다. 파일이 만들어지는 방식은 설치 방법에 따라 다릅니다.
    • Linux 패키지 설치: gitlab-ctl reconfigure가 파일을 만듭니다. 값은 gitlab.rb에 gitlab_rails['service_ping_secret']이 설정되어 있으면 그 값에서 가져오고, 그렇지 않으면 생성되어 /etc/gitlab/gitlab-secrets.json에 저장됩니다.
    • Helm 차트 설치: 차트가 Kubernetes Secret을 생성하거나 사용자가 제공한 Secret을 사용하고 이를 Rails Pod에 마운트합니다.
    • 자체 컴파일 설치와 GDK 같은 기타 설치: 파일이 없으면 GitLab이 시작할 때 파일을 만듭니다. Rails 루트에 쓸 수 없으면 GitLab이 경고를 기록하고 파일이 생길 때까지 API 요청이 401 Unauthorized로 실패합니다.
  2. 다음 클레임으로 시크릿과 HS256 알고리즘을 사용해 JWT에 서명합니다.
    • iss: gitlab-service-ping
    • aud: gitlab
    • sub: 호출하는 서비스의 이름입니다. 예: service-ping-exporter.
    • iat: 현재 시간입니다. GitLab은 5분보다 오래전에 발급된 토큰을 거부합니다.
  3. JWT를 Gitlab-Service-Ping-Api-Request 헤더로 전달합니다.

내부 엔드포인트#

인스턴스 식별 정보와 Service Ping 설정 조회#

GET 요청으로 인스턴스의 식별 정보와 Service Ping 설정을 가져옵니다.

GET /internal/service_ping/instance

요청 예시:

curl --header "Gitlab-Service-Ping-Api-Request: <json-web-token>" "https://gitlab.example.com/api/v4/internal/service_ping/instance"

응답 예시:

{
  "identity": {
    "instance_id": "d4f5e6a7-1b2c-4d3e-8f9a-0b1c2d3e4f5a",
    "unique_instance_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "host_name": "gitlab.example.com",
    "instance_version": "18.6.0-ee"
  },
  "settings": {
    "service_ping_enabled": true,
    "service_ping_generation_enabled": true,
    "service_ping_optional_metrics_enabled": true
  }
}

service_ping_enabled는 라이선스가 Service Ping을 요구하는 경우를 포함해 인스턴스가 Service Ping을 전송할 수 있는지를 나타냅니다. Rails는 service_ping_generation_enabled도 true일 때만 Service Ping을 전송합니다. 필드는 추가만 되고 이름이 바뀌거나 제거되지 않으므로 이전 클라이언트도 계속 동작합니다.