From c8619ff9cf9bd4e558f4de2223e8ea714b072456 Mon Sep 17 00:00:00 2001
From: Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
Date: Wed, 4 Oct 2017 14:48:50 +0530
Subject: [PATCH] Add API documentation about the agent health status endpoint

(gocd/gocd#3781)
---
 source/includes/_035-agent-health.md.erb      |  5 +++
 .../_00-get-agent-health-status.md.erb        | 43 +++++++++++++++++++
 source/index.html.md                          |  1 +
 3 files changed, 49 insertions(+)
 create mode 100644 source/includes/_035-agent-health.md.erb
 create mode 100644 source/includes/agent-health/_00-get-agent-health-status.md.erb

diff --git a/source/includes/_035-agent-health.md.erb b/source/includes/_035-agent-health.md.erb
new file mode 100644
index 00000000000..9f0728008fc
--- /dev/null
+++ b/source/includes/_035-agent-health.md.erb
@@ -0,0 +1,5 @@
+# Agent Health
+
+The agents API allows users to monitor if the agent is connected to the server and is authorized to perform a build.
+
+<%= render_all_sub_topics('agent-health') %>
diff --git a/source/includes/agent-health/_00-get-agent-health-status.md.erb b/source/includes/agent-health/_00-get-agent-health-status.md.erb
new file mode 100644
index 00000000000..46484d51442
--- /dev/null
+++ b/source/includes/agent-health/_00-get-agent-health-status.md.erb
@@ -0,0 +1,43 @@
+## Check agent-server connectivity
+
+```shell
+$ curl 'http://localhost:8152/health/v1/isConnectedToServer'
+```
+
+> The above command returns a plain text response:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: text/plain; charset=utf-8
+
+OK!
+```
+
+This API when invoked on an agent, will indicate if the agent-server connectivity is in a state that allows agents to run builds.
+
+<%= available_since('17.11') %>
+
+<p class='http-request-heading'>HTTP Request</p>
+
+`GET /health/v1/isConnectedToServer` 
+
+You may alternatively use:
+
+`GET /health/latest/isConnectedToServer` 
+
+which will render the most recent version of the api.
+
+<p class='http-request-return-description'>Returns</p>
+
+A status code `200` along with text `OK!` if all the following conditions are met:
+
+- able to establish HTTP(s) contact with the server
+- is authorized by the server (by an admin, or by auto-registration)
+
+The endpoint will return status `503` in any other cases.
+
+Two consecutive failing pings will be treated as having failed healthcheck.
+
+<aside class="notice">
+  <strong>Note:</strong> When a GoCD server is upgraded, the agent will automatically upgrade itself by downloading a copy from the GoCD server. During the time a new agent jar is being downloaded, this api endpoint may not be available.
+</aside>
diff --git a/source/index.html.md b/source/index.html.md
index d07325bf72c..a869555a0d5 100644
--- a/source/index.html.md
+++ b/source/index.html.md
@@ -13,6 +13,7 @@ includes:
   - 010-introduction
   - 020-authentication
   - 030-agents
+  - 035-agent-health
   - 040-users
   - 042-current-user
   - 044-notification-filters