Service Ping internal API
The Service Ping internal API is used by services that report Service Ping on behalf of a GitLab instance, such as the Service Ping exporter. The API cannot be used by other consumers. This documentation is intended for people working on the GitLab codebase.
Authentication
Requests require Workhorse internal API authentication and a Service Ping JSON Web Token (JWT).
To create the JWT, clients:
- Read the Service Ping secret.
The secret is in the file set by
service_ping.secret_fileingitlab.yml, by default.gitlab_service_ping_secretin the GitLab Rails root. The file contains a Base64-encoded 32-byte value, and must be the same on every Rails node. How the file is created depends on the installation method:- Linux package installations:
gitlab-ctl reconfigurecreates the file. The value comes fromgitlab_rails['service_ping_secret']ingitlab.rbif set, otherwise it is generated and stored in/etc/gitlab/gitlab-secrets.json. - Helm chart installations: the chart generates a Kubernetes Secret, or uses one you provide, and mounts it into the Rails pods.
- Other installations, such as self-compiled installations and the GDK: GitLab creates the file
at startup if it does not exist.
If the Rails root is not writable, GitLab logs a warning and
requests to the API fail with
401 Unauthorizeduntil the file exists.
- Linux package installations:
- Sign a JWT with the secret and the
HS256algorithm, with these claims:iss:gitlab-service-pingaud:gitlabsub: The name of the calling service, for exampleservice-ping-exporter.iat: The current time. GitLab rejects tokens issued more than five minutes ago.
- Pass the JWT in the
Gitlab-Service-Ping-Api-Requestheader.
Internal endpoints
Fetch the instance identity and Service Ping settings
Use a GET request to retrieve the identity of the instance and its Service Ping settings.
GET /internal/service_ping/instanceExample request:
curl --header "Gitlab-Service-Ping-Api-Request: <json-web-token>" "https://gitlab.example.com/api/v4/internal/service_ping/instance"Example response:
{
"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 reports whether the instance is allowed to send Service Ping,
including when the license requires Service Ping.
Rails sends Service Ping only when service_ping_generation_enabled is also true.
Fields are only added, never renamed or removed, so older clients keep working.