Configuring Canary App Health Endpoint
This topic describes how to use the Pivotal Healthwatch API to do view or update the canary app health URL for your Tanzu Application Service (TAS for VMs) deployment.
For more information about this metric, see Canary App Health in Pivotal Healthwatch Metrics.
Prerequisite
The steps in this document require that you generate bearer tokens for a UAA client with the healthwatch.read
and healthwatch.admin
scopes. For more information on granting these scopes, see Allow Additional Users to Access the Pivotal Healthwatch UI in Installing Pivotal Healthwatch. For an example of generating and using a UAAC token for API calls, see Using the Ops Manager API in the Ops Manager documentation.
Check Healthwatch API Status
To check the availability of the Healthwatch API, run:
curl https://healthwatch-api.SYSTEM-DOMAIN/info
Where SYSTEM-DOMAIN
is the system domain URL configured in the TAS for VMs tile. For example, sys.example.com
.
A successful response is a 200
/OK
with the message "HAPI is happy"
.
View Canary URL
GET /v1/canary?deployment=cf-GUID
To view the currently configured canary URL, run:
uaac curl https://healthwatch-api.SYSTEM-DOMAIN/v1/canary?deployment=cf-GUID
Where SYSTEM-DOMAIN
is the system domain URL configured in the TAS for VMs tile. For example, sys.example.com
.
Note: The cf deployment is currently the only supported deployment for the canary URL configuration. These endpoints only support deployment names beginning with cf
. For more information about the cf deployment metric change, see Changed “deployment” Field Value for PAS Metrics in Pivotal Application Service v2.4 Release Notes. cf-GUID
is shown on the healthwatch.SYSTEM-DOMAIN/diego/capacity
page, where SYSTEM-DOMAIN
is the system domain URL configured in the TAS for VMs tile.
This returns a JSON object in the following format:
{ "deployment":"cf-GUID", "url":"CONFIGURED-CANARY-URL" }
Where CONFIGURED-CANARY-URL
is the currently configured canary URL.
Update Canary URL
POST /v1/canary?deployment=cf-GUID
To update the canary URL for a deployment, run:
uaac curl -X POST "https://healthwatch-api.SYSTEM-DOMAIN/v1/canary?deployment=cf-GUID" \
-H "Content-Type: application/json" \
--data "{\"url\":\"https://CANARY-URL.com\"}"
Where:
SYSTEM-DOMAIN
is the system domain URL configured in the TAS for VMs tile. For example,sys.example.com
.CANARY-URL
is the URL you want to have checked for HTTP 200 responses.
Understand the Response
See the following table for possible response codes and their explanations.
Response code | Explanation |
---|---|
200
|
A record was updated. |
400
|
A validation error occurred. |
500
|
An error occurred while trying to update the record. Check the logs for the healthwatch-api app.
|
See the following table for details about the contents of the response payload, which is in JSON format.
Field | Explanation |
---|---|
deployment
|
The deployment name. |
url
|
The configured canary endpoint. |
reachable
|
Boolean indicating whether the endpoint was reachable from the Healthwatch API. |
responseBody
|
The response from attempting an HTTP GET request to the canary endpoint. |