Merge pull request #3 from jumppad-labs/f-health-checks

f-health-checks
jumppad-labs · Jul 5, 2023 · 98e41c0 · 98e41c0
2 parents 7f5500a + 324dfe1
commit 98e41c0
Show file tree

Hide file tree

Showing 3 changed files with 249 additions and 26 deletions.
diff --git a/src/pages/docs/resources/container.mdx b/src/pages/docs/resources/container.mdx
@@ -107,7 +107,22 @@ The `container` resource allows you to create Docker containers.
     ```hcl
       health_check {
         timeout = "30s"
-        http    = "http://localhost:8500/v1/status/leader"
+        http {
+          address = "http://localhost:8500/v1/status/leader"
+          success_codes = [200]
+        }
+        
+        tcp {
+          address = "localhost:8500"
+        }
+        
+       exec {
+          script = <<-EOF
+            #!/bin/bash
+
+            curl "http://localhost:9090"
+          EOF
+        }
       }
     ```
   </Property>
@@ -168,31 +183,128 @@ The `container` resource allows you to create Docker containers.
 
 ## health_check
 
-A health_check stanza allows the definition of a health check which must pass before the container is marked as successfully created.
+A health_check stanza allows the definition of a health check which must pass before 
+the container is marked as successfully created. There are three different types 
+of healthcheck `http`, `tcp`, and `exec`, these are not mutually exclusive, it is
+possible to define more than one health check.
+
+Health checks are executed sequentially, if one health check fails, the following 
+checks are not executed. The execution order is `http`, `tcp`, `exec.
+
 
 ```hcl
-health_check {
-  duration = "60s"
-  http = "http://myendpoint:9090/health"
-  http_status_codes = [200,429] // optional
-}
+  health_check {
+    timeout = "30s"
+    http {
+      address = "http://localhost:8500/v1/status/leader"
+      success_codes = [200]
+    }
+    
+    tcp {
+      address = "localhost:8500"
+    }
+    
+   exec {
+      script = <<-EOF
+        #!/bin/bash
+
+        curl "http://localhost:9090"
+      EOF
+    }
+  }
 ```
 
 <Properties>
   <Property name="timeout" type="duration" required="true" value="">
     The maximum duration to wait before marking the health check as failed. Expressed as a Go duration, e.g. `1s` = 1 second, `100ms` = 100 milliseconds.
   </Property>
-  <Property name="http" type="string" required="true" value="">
-    The URL to check, health check expects a HTTP status code to be returned by the URL in order to pass the health check. HTTP status codes can be specified
-by setting the `http_status_code` parameter. A default code of `200` is configured when `http_status_codes` is not set.
+  <Property name="http" type="#http_health_check" required="false" value="">
+    HTTP Health Check block defining the address to check and expected status codes.
   </Property>
-  <Property name="http_status_codes" type="[]number" required="false" value="[200]">
-    HTTP status codes returned from the endpoint when called. If the returned status code matches any in the array then the health check will pass.
+  <Property name="tcp" type="#tpc_health_check" required="false" value="">
+    TCP Health Check block defining the address to test.
+  </Property>
+  <Property name="exec" type="#exec_health_check" required="false" value="">
+    Exec Health Check block defining either a command to run in the current container,
+    or a script to execute.
   </Property>
 </Properties>
 
 ---
 
+## http_health_check
+
+A HTTP health check executes a HTTP GET request for the given address and evaluates
+the response against the expected `success_codes`. If the reponse matches any of
+the given codes the check passes.
+
+```hcl
+http {
+  address = "http://localhost:8500/v1/status/leader"
+  success_codes = [200]
+}
+```
+
+<Properties>
+  <Property name="address" type="string" required="true" value="">
+    The URL to check, health check expects a HTTP status code to be returned by the URL in order to pass the health check. 
+  </Property>
+  <Property name="http_status_codes" type="[]number" required="true" value="">
+    HTTP status codes returned from the endpoint when called. If the returned status code matches any in the array then the health check will pass.
+  </Property>
+</Properties>
+
+## tcp_health_check
+
+A TCP health check attempts to open a connection to the given address. If a
+connection can be opened then the check passes.
+
+```hcl
+tcp {
+  address = "localhost:8500"
+}
+```
+
+<Properties>
+  <Property name="address" type="string" required="true" value="">
+    The adress to check.
+  </Property>
+</Properties>
+
+## exec_health_check
+
+Exec health checks allow you to execute a command or script in the current container.
+If the command or script receives an exit code `0` the check passes.
+
+<Properties>
+  <Property name="command" type="[]string" required="false" value="">
+    A command to execute.
+
+    ```hcl
+    exec {
+      command = ["pg_isready"]
+    }
+    ```
+  </Property>
+  <Property name="script" type="string" required="false" value="">
+    A script to execute in the target container, the script is coppied to the
+    container into the `/tmp` directory and is then executed. 
+
+    ```hcl
+    exec {
+      script = <<-EOF
+        #!/bin/bash
+        
+        FILE=/etc/resolv.conf
+        if [ -f "$FILE" ]; then
+            echo "$FILE exists."
+        fi
+      EOF
+    }
+    ```
+  </Property>
+</Properties>
+
 ## resources
 
 A resources type allows you to configure the maximum resources which can be consumed.

diff --git a/src/pages/docs/resources/nomad_job.mdx b/src/pages/docs/resources/nomad_job.mdx
@@ -40,8 +40,8 @@ A health_check stanza allows the definition of a health check which must pass be
 
 ```hcl
 health_check {
-  duration = "60s"
-  nomad_jobs = ["example"]
+  timeout = "60s"
+  jobs = ["example"]
 }
 ```
 
@@ -51,7 +51,7 @@ health_check {
     Expressed as a Go duration, e.g. `1s` = 1 second, `100ms` = 100 milliseconds.
   </Property>
 
-  <Property name="nomad_jobs" type="[]string" required="true" value="">
+  <Property name="jobs" type="[]string" required="true" value="">
     An array of nomad jobs that must be marked as "Running" by the Nomad
     server.
   </Property>

diff --git a/src/pages/docs/resources/sidecar.mdx b/src/pages/docs/resources/sidecar.mdx
@@ -115,7 +115,22 @@ to the target container.
     ```hcl
       health_check {
         timeout = "30s"
-        http    = "http://localhost:8500/v1/status/leader"
+        http {
+          address = "http://localhost:8500/v1/status/leader"
+          success_codes = [200]
+        }
+        
+        tcp {
+          address = "http://localhost:8500/v1/status/leader"
+        }
+        
+       exec {
+          script = <<-EOF
+            #!/bin/bash
+
+            curl "http://localhost:9090"
+          EOF
+        }
       }
     ```
   </Property>
@@ -173,29 +188,125 @@ to the target container.
 
 ## health_check
 
-A health_check stanza allows the definition of a health check which must pass before the container is marked as successfully created.
+A health_check stanza allows the definition of a health check which must pass before 
+the container is marked as successfully created. There are three different types 
+of healthcheck `http`, `tcp`, and `exec`, these are not mutually exclusive, it is
+possible to define more than one health check.
+
+Health checks are executed sequentially, if one health check fails, the following 
+checks are not executed. The execution order is `http`, `tcp`, `exec.
+
 
 ```hcl
-health_check {
-  duration = "60s"
-  http = "http://myendpoint:9090/health"
-  http_status_codes = [200,429] // optional
-}
+  health_check {
+    timeout = "30s"
+    http {
+      address = "http://localhost:8500/v1/status/leader"
+      success_codes = [200]
+    }
+    
+    tcp {
+      address = "localhost:8500"
+    }
+    
+   exec {
+      script = <<-EOF
+        #!/bin/bash
+
+        curl "http://localhost:9090"
+      EOF
+    }
+  }
 ```
 
 <Properties>
   <Property name="timeout" type="duration" required="true" value="">
     The maximum duration to wait before marking the health check as failed. Expressed as a Go duration, e.g. `1s` = 1 second, `100ms` = 100 milliseconds.
   </Property>
-  <Property name="http" type="string" required="true" value="">
-    The URL to check, health check expects a HTTP status code to be returned by the URL in order to pass the health check. HTTP status codes can be specified
-by setting the `http_status_code` parameter. A default code of `200` is configured when `http_status_codes` is not set.
+  <Property name="http" type="#http_health_check" required="false" value="">
+    HTTP Health Check block defining the address to check and expected status codes.
+  </Property>
+  <Property name="tcp" type="#tpc_health_check" required="false" value="">
+    TCP Health Check block defining the address to test.
+  </Property>
+  <Property name="exec" type="#exec_health_check" required="false" value="">
+    Exec Health Check block defining either a command to run in the current container,
+    or a script to execute.
   </Property>
-  <Property name="http_status_codes" type="[]number" required="false" value="[200]">
+</Properties>
+
+## http_health_check
+
+A HTTP health check executes a HTTP GET request for the given address and evaluates
+the response against the expected `success_codes`. If the reponse matches any of
+the given codes the check passes.
+
+```hcl
+http {
+  address = "http://localhost:8500/v1/status/leader"
+  success_codes = [200]
+}
+```
+
+<Properties>
+  <Property name="address" type="string" required="true" value="">
+    The URL to check, health check expects a HTTP status code to be returned by the URL in order to pass the health check. 
+  </Property>
+  <Property name="http_status_codes" type="[]number" required="true" value="">
     HTTP status codes returned from the endpoint when called. If the returned status code matches any in the array then the health check will pass.
   </Property>
 </Properties>
 
+## tcp_health_check
+
+A TCP health check attempts to open a connection to the given address. If a
+connection can be opened then the check passes.
+
+```hcl
+tcp {
+  address = "localhost:8500"
+}
+```
+
+<Properties>
+  <Property name="address" type="string" required="true" value="">
+    The adress to check.
+  </Property>
+</Properties>
+
+## exec_health_check
+
+Exec health checks allow you to execute a command or script in the current container.
+If the command or script receives an exit code `0` the check passes.
+
+<Properties>
+  <Property name="command" type="[]string" required="false" value="">
+    A command to execute.
+
+    ```hcl
+    exec {
+      command = ["pg_isready"]
+    }
+    ```
+  </Property>
+  <Property name="script" type="string" required="false" value="">
+    A script to execute in the target container, the script is coppied to the
+    container into the `/tmp` directory and is then executed. 
+
+    ```hcl
+    exec {
+      script = <<-EOF
+        #!/bin/bash
+        
+        FILE=/etc/resolv.conf
+        if [ -f "$FILE" ]; then
+            echo "$FILE exists."
+        fi
+      EOF
+    }
+    ```
+  </Property>
+</Properties>
 ---
 
 ## resources