diff options
author | Achilleas Pipinellis <axilleas@axilleas.me> | 2017-07-11 17:30:20 +0300 |
---|---|---|
committer | Achilleas Pipinellis <axilleas@axilleas.me> | 2017-07-16 11:22:05 +0300 |
commit | e1339d9409d410ab4351b2a2c1e30b6f9f65282e (patch) | |
tree | 0007fef6f1ec0cea9a7e55ecf20c5a5b9a066d5f /doc | |
parent | d9ed329b8c4282e8b722034df22dc1949e46c732 (diff) |
Update health check docs
Diffstat (limited to 'doc')
-rw-r--r-- | doc/user/admin_area/monitoring/health_check.md | 157 |
1 files changed, 87 insertions, 70 deletions
diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 69a9dfc3500..ffc6f98a110 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -6,7 +6,7 @@ be deprecated in GitLab 9.1. Read more in the [old behavior](#old-behavior) section. - [Access token](#access-token) has been deprecated in GitLab 9.4 - in favor of [IP Whitelist](#ip-whitelist) + in favor of [IP whitelist](#ip-whitelist) GitLab provides liveness and readiness probes to indicate service health and reachability to required services. These probes report on the status of the @@ -14,106 +14,123 @@ database connection, Redis connection, and access to the filesystem. These endpoints [can be provided to schedulers like Kubernetes][kubernetes] to hold traffic until the system is ready or restart the container as needed. -## IP Whitelist +## IP whitelist -To access monitoring resources the client IP needs to be included in the whitelist. -To add or remove hosts or IP ranges from the list you can edit `gitlab.rb` or `gitlab.yml`. +To access monitoring resources, the client IP needs to be included in a whitelist. +You can add single hosts or use IP ranges. -Example whitelist configuration: -```yaml -monitoring: - ip_whitelist: - - 127.0.0.0/8 # by default only local IPs are allowed to access monitoring resources -``` +**For Omnibus installations** -## Access Token (Deprecated) +1. Open `/etc/gitlab/gitlab.rb` and add or uncomment the following: -An access token needs to be provided while accessing the probe endpoints. The current -accepted token can be found under the **Admin area ➔ Monitoring ➔ Health check** -(`admin/health_check`) page of your GitLab instance. + ```ruby + gitlab_rails['monitoring_whitelist'] = ['127.0.0.0/8'] + ``` -![access token](img/health_check_token.png) +1. Save the file and [reconfigure] GitLab for the changes to take effect. -The access token can be passed as a URL parameter: +--- -``` -https://gitlab.example.com/-/readiness?token=ACCESS_TOKEN -``` +**For installations from source** -which will then provide a report of system health in JSON format: +1. Edit `config/gitlab.yml`: -``` -{ - "db_check": { - "status": "ok" - }, - "redis_check": { - "status": "ok" - }, - "fs_shards_check": { - "status": "ok", - "labels": { - "shard": "default" - } - } -} -``` + ```yaml + monitoring: + ip_whitelist: + - 127.0.0.0/8 # by default only local IPs are allowed to access monitoring resources + ``` + +1. Save the file and [restart] GitLab for the changes to take effect. -## Using the Endpoint +[reconfigure]: ../../../administration/gitlab_restart.md#omnibus-gitlab-reconfigure +[restart]: ../../../administration/gitlab_restart.md#installations-from-source + +## Using the endpoint With default whitelist settings, the probes can be accessed from localhost: - `http://localhost/-/readiness` - `http://localhost/-/liveness` -## Status +which will then provide a report of system health in JSON format. -On failure, the endpoint will return a `500` HTTP status code. On success, the endpoint -will return a valid successful HTTP status code, and a `success` message. +Readiness example output: -## Old behavior +``` +{ + "queues_check" : { + "status" : "ok" + }, + "redis_check" : { + "status" : "ok" + }, + "shared_state_check" : { + "status" : "ok" + }, + "fs_shards_check" : { + "labels" : { + "shard" : "default" + }, + "status" : "ok" + }, + "db_check" : { + "status" : "ok" + }, + "cache_check" : { + "status" : "ok" + } +} +``` ->**Notes:** - - Liveness and readiness probes were [introduced][ce-10416] in GitLab 9.1. - - The `health_check` endpoint was [introduced][ce-3888] in GitLab 8.8 and will - be deprecated in GitLab 9.1. Read more in the [old behavior](#old-behavior) - section. +Liveness example output: -GitLab provides a health check endpoint for uptime monitoring on the `health_check` web -endpoint. The health check reports on the overall system status based on the status of -the database connection, the state of the database migrations, and the ability to write -and access the cache. This endpoint can be provided to uptime monitoring services like -[Pingdom][pingdom], [Nagios][nagios-health], and [NewRelic][newrelic-health]. +``` +{ + "fs_shards_check" : { + "status" : "ok" + }, + "cache_check" : { + "status" : "ok" + }, + "db_check" : { + "status" : "ok" + }, + "redis_check" : { + "status" : "ok" + }, + "queues_check" : { + "status" : "ok" + }, + "shared_state_check" : { + "status" : "ok" + } +} +``` -Once you have the [access token](#access-token) or your client IP is [whitelisted](#ip-whitelist), -health information can be retrieved as plain text, JSON, or XML using the `health_check` endpoint: +## Status -- `https://gitlab.example.com/health_check?token=ACCESS_TOKEN` -- `https://gitlab.example.com/health_check.json?token=ACCESS_TOKEN` -- `https://gitlab.example.com/health_check.xml?token=ACCESS_TOKEN` +On failure, the endpoint will return a `500` HTTP status code. On success, the endpoint +will return a valid successful HTTP status code, and a `success` message. -You can also ask for the status of specific services: +## Access token (Deprecated) -- `https://gitlab.example.com/health_check/cache.json?token=ACCESS_TOKEN` -- `https://gitlab.example.com/health_check/database.json?token=ACCESS_TOKEN` -- `https://gitlab.example.com/health_check/migrations.json?token=ACCESS_TOKEN` +>**Note:** +Access token has been deprecated in GitLab 9.4 +in favor of [IP whitelist](#ip-whitelist) -For example, the JSON output of the following health check: +An access token needs to be provided while accessing the probe endpoints. The current +accepted token can be found under the **Admin area ➔ Monitoring ➔ Health check** +(`admin/health_check`) page of your GitLab instance. -```bash -curl --header "TOKEN: ACCESS_TOKEN" https://gitlab.example.com/health_check.json -``` +![access token](img/health_check_token.png) -would be like: +The access token can be passed as a URL parameter: ``` -{"healthy":true,"message":"success"} +https://gitlab.example.com/-/readiness?token=ACCESS_TOKEN ``` -On failure, the endpoint will return a `500` HTTP status code. On success, the endpoint -will return a valid successful HTTP status code, and a `success` message. Ideally your -uptime monitoring should look for the success message. - [ce-10416]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10416 [ce-3888]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3888 [pingdom]: https://www.pingdom.com |