grim/convey

Finish up the healthcheck stuff and add docs with examples. Fixes #21

2017-09-11, Gary Kramlich
7648ec9b2dad
Parents 152edd04308a
Children f51751123396
Finish up the healthcheck stuff and add docs with examples. Fixes #21
4 files changed, 63 insertions(+), 1 deletions(-)
  • +26 -0
    REFERENCE.md
  • +9 -0
    docker/healthcheck.go
  • +10 -1
    docker/run.go
  • +18 -0
    examples/detach-health.yml
    • --- a/REFERENCE.md Mon Sep 11 22:38:41 2017 -0500
    +++ b/REFERENCE.md Mon Sep 11 23:28:07 2017 -0500
    @@ -20,6 +20,10 @@
    A simple plan to show how you can detach a container.
    +## detach-health.yml
    +
    +A simple plan to show how you can specify health commands for a detached container.
    +
    ## environment.yml
    This example shows how environment substitution works in your config file.
    @@ -307,11 +311,24 @@
    | detach | | false | Will run the container in the background allowing other tasks to run. The container will be cleaned up on exit. If the image has a HEALTHCHECK specified in the Dockerfile, convey will wait until it is healthy before proceeding. |
    | entrypoint | | | The entrypoint to use for the container. This is only necessary if the image does not provide one by default. |
    | environment | | | A list of environment variables to set. The should be specified in a `NAME` or `NAME=VALUE` format. If no value is provided, the value of the variable from the host will be provided if it is available. |
    +| healthcheck | | | See the HealthCheck attributes below. |
    | image | Yes | | The image including the registry and tag to run. |
    | labels | | | A list of labels to set on the image being built |
    | workdir | | | The working directory to use in the container. |
    | workspace | | /workspace | The path inside the container to mount the workspace volume. |
    +#### HealthCheck Attributes
    +
    +All of these attributes map directory to the `--health` arguments to `docker run`.
    +
    +| Name | Description |
    +| -------- | ----------- |
    +| command | The command to run as the health check. |
    +| interval | The interval with which to check the health. |
    +| retries | The number of attempts before giving up. |
    +| start-period | How long to wait before starting to check the container's health. |
    +| timeout | How long to wait for a health check to return before aborting. |
    +
    #### Example
    A basic example where the image knows everything to do.
    @@ -330,6 +347,15 @@
    - wget https://somedomain.tld/file1.sha256
    - sha256sum -c file1.sha256
    +A more compilicated example waiting for a detached nginx to start
    +
    + web-server:
    + type: run
    + image: nginx:alpine
    + detach: true
    + command: wget http://localhost
    + interval: 1s
    +
    ----
    ### Tag Tasks
    --- a/docker/healthcheck.go Mon Sep 11 22:38:41 2017 -0500
    +++ b/docker/healthcheck.go Mon Sep 11 23:28:07 2017 -0500
    @@ -19,12 +19,21 @@
    import (
    "strings"
    + "time"
    "github.com/aphistic/gomol"
    "bitbucket.org/rw_grim/convey/state"
    )
    +type HealthCheck struct {
    + Command string `yaml:"command"`
    + Interval time.Duration `yaml:"interval"`
    + Retries int `yaml:"retries"`
    + StartPeriod time.Duration `yaml:"start-period"`
    + Timeout time.Duration `yaml:"timeout"`
    +}
    +
    const (
    containerHasHealthCheckTemplate = `inspect -f "{{.Format}}" {{.Cid}}`
    containerHasHealthCheckFormat = `{{if .Config.Healthcheck}}true{{else}}false{{end}}`
    --- a/docker/run.go Mon Sep 11 22:38:41 2017 -0500
    +++ b/docker/run.go Mon Sep 11 23:28:07 2017 -0500
    @@ -45,11 +45,12 @@
    Script yaml.StringOrSlice `yaml:"script"`
    Shell string `yaml:"shell"`
    Labels yaml.StringOrSlice `yaml:"labels"`
    + HealthCheck HealthCheck `yaml:"healthcheck"`
    }
    func (r *Run) UnmarshalYAML(unmarshal func(interface{}) error) error {
    type rawRun Run
    - raw := rawRun{Shell: "/bin/sh"}
    + raw := rawRun{Shell: "/bin/sh", HealthCheck: HealthCheck{}}
    if err := unmarshal(&raw); err != nil {
    return err
    @@ -76,6 +77,13 @@
    {{range .Labels}} -l '{{.}}'{{end}}
    -l {{.TaskLabel}}
    {{range .Environment}} -e {{.}}{{end}}
    +{{if .HealthCheck}}
    +{{if .HealthCheck.Command}} --health-cmd "{{.HealthCheck.Command}}"{{end}}
    +{{if .HealthCheck.Interval}} --health-interval {{.HealthCheck.Interval}}{{end}}
    +{{if .HealthCheck.Retries}} --health-retries {{.HealthCheck.Retries}}{{end}}
    +{{if .HealthCheck.StartPeriod}} --health-start-period {{.HealthCheck.StartPeriod}}{{end}}
    +{{if .HealthCheck.Timeout}} --health-timeout {{.HealthCheck.Timeout}}{{end}}
    +{{end}}
    {{.Image}}{{if .Command}} {{.Command}}{{end}}`
    // buildScript will create a shell script for the given commands
    @@ -172,6 +180,7 @@
    "Environment": fullEnv,
    "EntryPoint": entryPoint,
    "GID": user.Gid,
    + "HealthCheck": r.HealthCheck,
    "Image": environment.Mapper(r.Image, fullEnv),
    "Labels": environment.SliceMapper(r.Labels, fullEnv),
    "Memory": st.Memory,
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/examples/detach-health.yml Mon Sep 11 23:28:07 2017 -0500
    @@ -0,0 +1,18 @@
    +tasks:
    + normal:
    + image: nginx:alpine
    + detach: true
    + health-check:
    + image: nginx:alpine
    + detach: true
    + healthcheck:
    + interval: 1s
    + timeout: 3s
    + command: wget http://localhost
    +plans:
    + default:
    + stages:
    + - tasks:
    + - normal
    + - tasks:
    + - health-check