Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/asicsdigital/healthcheck

Reference implementation of service healthcheck endpoint
https://github.com/asicsdigital/healthcheck

docker-compose golang healthcheck

Last synced: 4 days ago
JSON representation

Reference implementation of service healthcheck endpoint

Awesome Lists containing this project

README 

        
# Healthcheck Reference Implementation



A dedicated healthcheck endpoint is a crucial component of making any web service operable.  This repo contains a reference implementation of ASICS Digital's standard healthcheck endpoint; the intended audience consists of application developers (who can refer to this implementation when building their own healthchecks) and infrastructure engineers (who can refer to this implementation when building tools that consume healthcheck results).



A healthcheck endpoint has the following qualities:



* It is accessed via a static URI path which is not used for any other application functionality.  

  **Good**: `https://app.example.com/health-check`  

  **Bad**: `https://app.example.com/login`  

* It responds to a HTTP GET request.  

  **Good**: `GET https://app.example.com/health-check`  

  **Bad**: `POST https://app.example.com/status?action=healthcheck`  

* It does not require any authentication information.  

  **Good**: `curl https://app.example.com/health-check`  

  **Bad**: `curl -H 'Authorization: ablablablabla' https://app.example.com/health-check`  

  **Worse**: `curl -u 'sooper:seekrit' https://app.example.com/health-check`  

  **OMG STOPPP**: `curl -H 'X-MyFancyPantsToken: ablablablabla' https://app.example.com/health-check`

* It returns HTTP response code 200 to indicate a healthy service; any other response code indicates an unhealthy service.  

  **Good**: `GET https://app.example.com/health-check` -> `HTTP/1.1 200 OK`  

  **Sideeye**: `GET https://app.example.com/health-check` -> `HTTP/1.1 401 Not Authorized`  

  **NOOOOOOOO**: `GET https://app.example.com/health-check` -> `HTTP/1.1 200 OK` (in the body: `Status: Unhealthy`)

* It returns a body consisting solely of JSON-encoded text (with Content-Type `application/json`) that validates against the JSONschema included in this repository.  

  **Good**: `GET https://app.example.com/health-check` -> `{"application":"my_app","status":200,"metrics":"{}"}`  

  **Unacceptable**: `GET https://app.example.com/health-check` -> `noes`  

  **SRSLY WTF**: `GET https://app.example.com/health-check` -> `oh noes
OOPSY WOOPSY
`



## The purpose of a healthcheck



FIXME



## Using this reference implementation



There are several ways to start up this reference implementation for testing or experimentation.  The application reads some runtime configuration values from its environment; these values control the information returned by the healthcheck endpoint.



### Our publically-hosted endpoint



```sh

$ curl https://healthcheck.staging.asics.digital/healthcheck | jq .

```



To change the values, access the us-east-1 staging Consul cluster at https://asics-services.us-east-1.staging.asics.digital and modify the entries under `healthcheck/` in the key/value store.  Changes will be reflected in the endpoint immediately.



### Local Docker



In one shell:



```sh

$ docker pull asicsdigital/healthcheck:latest

$ docker run --rm -it \

  -p 8080:8080 \

  -e CONSUL_HTTP_ADDR="https://asics-services.us-east-1.staging.asics.digital" \

  -e CONSUL_HTTP_AUTH="consul:GET_THIS_FROM_1PASSWORD" \

  asicsdigital/healthcheck:latest

```



In another shell:



```sh

curl http://localhost:8080/healthcheck | jq .

```



You can also pass in a VAULT_TOKEN and a VAULT_ADDR to this example to read secrets from Vault.



( Someone will have had to have run `vault write secret/healthcheck HONEYCOMB_API_KEY=