github.com/outbrain/consul@v1.4.5/website/source/intro/getting-started/checks.html.md (about)

     1  ---
     2  layout: "intro"
     3  page_title: "Registering Health Checks"
     4  sidebar_current: "gettingstarted-checks"
     5  description: |-
     6    We've now seen how simple it is to run Consul, add nodes and services, and query those nodes and services. In this step, we will continue our tour by adding health checks to both nodes and services. Health checks are a critical component of service discovery that prevent using services that are unhealthy.
     7  ---
     8  
     9  # Health Checks
    10  
    11  We've now seen how simple it is to run Consul, add nodes and services, and
    12  query those nodes and services. In this section, we will continue our tour
    13  by adding health checks to both nodes and services. Health checks are a
    14  critical component of service discovery that prevent using services that
    15  are unhealthy.
    16  
    17  This step builds upon [the Consul cluster created previously](join.html).
    18  At this point, you should have a two-node cluster running.
    19  
    20  ## Defining Checks
    21  
    22  Similar to a service, a check can be registered either by providing a
    23  [check definition](/docs/agent/checks.html) or by making the
    24  appropriate calls to the [HTTP API](/api/health.html).
    25  
    26  We will use the check definition approach because, just like with
    27  services, definitions are the most common way to set up checks.
    28  
    29  In Consul 0.9.0 and later the agent must be configured with
    30  `enable_script_checks` set to true in order to enable script checks.
    31  
    32  Create two definition files in the Consul configuration directory of
    33  the second node:
    34  
    35  ```text
    36  vagrant@n2:~$ echo '{"check": {"name": "ping",
    37    "args": ["ping", "-c1", "google.com"], "interval": "30s"}}' \
    38    >/etc/consul.d/ping.json
    39  
    40  vagrant@n2:~$ echo '{"service": {"name": "web", "tags": ["rails"], "port": 80,
    41    "check": {"args": ["curl", "localhost"], "interval": "10s"}}}' \
    42    >/etc/consul.d/web.json
    43  ```
    44  
    45  The first definition adds a host-level check named "ping". This check runs
    46  on a 30 second interval, invoking `ping -c1 google.com`. On a `script`-based
    47  health check, the check runs as the same user that started the Consul process.
    48  If the command exits with an exit code >= 2, then the check will be flagged as
    49  failing and the service will be considered unhealthy. An exit code of 1 will
    50  be considered as warning state. This is the contract for any
    51  [`script`-based health check](/docs/agent/checks.html#check-scripts).
    52  
    53  The second command modifies the service named `web`, adding a check that sends a
    54  request every 10 seconds via curl to verify that the web server is accessible.
    55  As with the host-level health check, if the script exits with an exit code >= 2,
    56  the check will be flagged as failing and the service will be considered unhealthy.
    57  
    58  Now, restart the second agent, reload it with `consul reload`, or send it a `SIGHUP` signal. You should see the
    59  following log lines:
    60  
    61  ```text
    62  ==> Starting Consul agent...
    63  ...
    64      [INFO] agent: Synced service 'web'
    65      [INFO] agent: Synced check 'service:web'
    66      [INFO] agent: Synced check 'ping'
    67      [WARN] Check 'service:web' is now critical
    68  ```
    69  
    70  The first few lines indicate that the agent has synced the new
    71  definitions. The last line indicates that the check we added for
    72  the `web` service is critical. This is because we're not actually running
    73  a web server, so the curl test is failing!
    74  
    75  ## Checking Health Status
    76  
    77  Now that we've added some simple checks, we can use the HTTP API to inspect
    78  them. First, we can look for any failing checks using this command (note, this
    79  can be run on either node):
    80  
    81  ```text
    82  vagrant@n1:~$ curl http://localhost:8500/v1/health/state/critical
    83  [{"Node":"agent-two","CheckID":"service:web","Name":"Service 'web' check","Status":"critical","Notes":"","ServiceID":"web","ServiceName":"web","ServiceTags":["rails"]}]
    84  ```
    85  
    86  We can see that there is only a single check, our `web` service check, in the
    87  `critical` state.
    88  
    89  Additionally, we can attempt to query the web service using DNS. Consul
    90  will not return any results since the service is unhealthy:
    91  
    92  ```text
    93  dig @127.0.0.1 -p 8600 web.service.consul
    94  ...
    95  
    96  ;; QUESTION SECTION:
    97  ;web.service.consul.		IN	A
    98  ```
    99  
   100  ## Next Steps
   101  
   102  In this section, you learned how easy it is to add health checks. Check definitions
   103  can be updated by changing configuration files and sending a `SIGHUP` to the agent.
   104  Alternatively, the HTTP API can be used to add, remove, and modify checks dynamically.
   105  The API also allows for a "dead man's switch", a
   106  [TTL-based check](/docs/agent/checks.html#TTL). TTL checks can be used to integrate an
   107  application more tightly with Consul, enabling business logic to be evaluated as part
   108  of assessing the state of the check.
   109  
   110  Next, we will explore [Consul's K/V store](kv.html).