Containerpilot 配置文件之 Jobs

ContainerPilot job是用户定义的进程和规则，用于何时执行它，如何进行健康检查，以及如何向Consul做广告。这些规则旨在允许灵活性覆盖几乎可能要运行的任何类型的进程。一些可能的job配置包括：

一个长时间运行的应用程序，如Web服务器，如果崩溃，需要重新启动。
一次性设置任务，在容器的生命周期开始运行，但不会再次运行。
每隔几分钟或几小时运行的定期进程，例如备份。
当某些其他事件发生时运行的任务，例如仅当另一个job变得健康时运行。

Lifecycle Events

每个job都会发出与其进程的生命周期相关联的事件。任何job都可以通过任何其他job（甚至是自己的事件）通过when配置来响应事件。

healthy ：当job的健康检查成功时排出。
unhealthy ：当job健康检查失败时发出。
exitSuccess ：当与job相关联的进程退出时退出代码0时发出。
exitFailed ：与job相关联的进程以非0退出代码退出时发出。
stopping ：当job被要求停止时，但在此之前发出。当job有停止超时时有用。
stopped ：job停止时发出。请注意，这与退出的进程不同，因为job可能会执行其进程的许多执行。

此外，job可能会对这些事件做出反应：

startup ：当ContainerPilot准备启动时，发布到所有job。
shutdown ：当ContainerPilot关闭时发布到所有job。
changed ：当watch看到依赖性的变化时发布。
enterMaintenance ：当控制 enterMaintenance被告知进入容器的维护模式时发布。发生这种情况时，所有job都将自动从consul注销，因此如果还有其他任务要执行，您只需要对此事件做出反应。
退出维护：当控制 exitMaintenance被告知要退出容器的维护模式时发布。

Configuration

job配置包括以下字段：

jobs: [

  {

    name: "app",

    exec: "/bin/app",

    // 'when' defines the events that cause the job to run

    when: {

      source: "setup",

      once: "exitSuccess",

      timeout: "60s"

      // interval: "10s",     // can't be set at the same time as 'source'/'once'

      // each: "exitSuccess", // can't be set at the same time as 'once'

    },

    // these fields interact with 'when' behaviors (see below)

    timeout: "300s",

    stopTimeout: "10s",

    restarts: "unlimited",

    // 'health' defines how the job is health checked

    health: {

      exec: "/usr/bin/curl --fail -s -o /dev/null http://localhost/app",

      interval: 5,

      tll: 10,

      timeout: "5s",

    },

    // 'port', 'tags', 'interfaces', and 'consul' define options for

    // service discovery with Consul

    port: 80,

    tags: [

      "app",

      "prod"

    ],

    interfaces: [

      "eth0",

      "eth1[1]",

      "192.168.0.0/16",

      "2001:db8::/64",

      "eth2:inet",

      "eth2:inet6",

      "inet",

      "inet6",

      "static:192.168.1.100", // a trailing comma isn't an error!

    ],

    consul: {

      enableTagOverride: true,

      deregisterCriticalServiceAfter: "10m"

    }

  }
]

`name`

name字段是job的名称，因为它将显示在日志和事件中。它也将是服务的名称，因为它将出现在consul（如果job注册到consul）。 consul服务的每个实例将具有由容器name +主机名组成的唯一ID。名称必须符合consul要求; 它们以小写字母开始，并包含大小写字母，数字或-但不包含其他字符。（或者换句话说，它们必须匹配正则表达式^[az][a-zA-Z0-9\-]+$ ）

`exec`

exec字段是job运行时调用的可执行文件（及其参数）。此字段可以包含字符串或字符串数组（有关格式的详细信息，请参阅下文）。要运行的命令将设置一个进程组，并且当进程退出时，此整个进程组将通过ContainerPilot获取。该进程将同时运行到所有其他job，因此该进程不会阻止其他ContainerPilot事件的处理。

Running and timing fields

`when`

when字段定义启动job的exec的事件。默认情况下，一旦ContainerPilot完成启动，job的exec进程就会启动。许多job将希望有一个配置来确定一些特定事件等待，使用when字段。

source是触发job的事件的源。
once只会触发一次job的start
each 每次发生时都会触发job的start
interval是执行job之间的时间。支持毫秒，秒，分钟。频率必须是具有时间单位后缀的正非零持续时间。（例如： 60s ，请参阅golang ParseDuration文档以获取此格式）有效时间单位为ns ， us （或µs ）， ms ， s ， m ， h 。最小间隔为1ms但实际上需要20-50ms的时间进行分叉和执行，所以间隔应该更长。
timeout是可选的，是等待在放弃之前收到的事件的时间量。此字段的格式与interval的格式相同。

如果interval字段被设置，它是唯一允许的字段。否则， once和each字段是互斥的 - 您可以设置一个或另一个，但不能同时设置。

`timeout`

下面的timeout字段是可选的，是在job开始之前等待的时间，在它被杀死之前。以这种方式杀死的进程立即终止（ SIGKILL ），没有机会清理其状态，并且不会发送心跳。

对于像服务器这样的长期运行的job，你通常会想要省略这个字段。如果省略此字段，并且该job没有when.frequency字段，则job将永远不会超时。如果该字段被省略，并且job确实有一个when.frequency字段，那么超时将默认为该频率。

如果设置并不是默认值，则最小超时值为1ms （对于此格式，请参阅golang ParseDuration文档），但实际上，进程需要20-50ms的分叉和执行，所以超时时间应该更长。

`stopTimeout`

一些job需要在开始关闭之前执行任务，但在完成之前。例如，一个consulagent可能需要通过consul leave从可用节点列表中删除，这需要agent仍在运行才能执行。

在这种情况下，job将需要在stopping和stopped事件之间留下时间。 stopTimeout字段是job在退出并杀死其进程之前等待的时间。在下面的示例中， consul-agentjob在被要求停止之后等待5秒钟，以允许leave-consuljob运行。

jobs: [

  {

    name: "consul-agent",

    exec: "consul agent...",

    stopTimeout: "5s"

  },

  {

    name: "leave-consul",

    exec: "consul leave",

    when: {

      source: "consul-agent",

      once: "stopping"

  }
 }
]

`restarts`

restarts字段是restarts进程的次数，如果它退出。此字段支持任何非负数值（例如0或1 ）或字符串"unlimited"或"never" 。此值是可选的，默认为"never" 。

了解这个字段与when字段的比较很重要。只有当job接收到自己的exitSuccess或exitFailure事件时才会重新启动。 when字段用于触发其他事件。在下面的示例中， appjob首先在dbjobhealthy运行时启动，但会在退出时重新启动。

jobs: [

  {

    name: "app",

    restarts: "unlimited",

    when: {

      source: "db",

      once: "healthy"

    }

  }
]

Health checks

health领域定义了ContainerPilot如何确定job是否健康。此字段是可选的。没有health领域的job不会发生healthy和changed事件。

exec字段是运行到健康状态的可执行文件（及其参数）来检查job。
interval是健康检查之间的时间（秒）。
ttl是成功进行健康检查的几秒钟内的生存时间。这应该比interval轮询率更长，以便检查和TTL不竞争; 否则job将在consul馆标示不健康。
timeout是强制杀死健康检查exec之前等待的值。死亡的健康检查方式立即终止（ SIGKILL ），没有机会清理他们的状态，心跳不会被发送。最小超时时间为1ms （对于此格式，请参阅golang ParseDuration文档），但实际上，进程需要花费20-50ms进行分片和执行，所以超时时间应该更长。

Service discovery

以下字段定义job如何在consul部门注册。

`port`

port字段是服务将向consul广告的端口。请注意，这假定job正在侦听该端口，但不会更改任何进程。如果要动态分配此端口，可以对exec和port字段使用环境变量和模板呈现。例如：

jobs: [

  {

    name: "myjob",

    exec: "node /bin/server.js --port {{ .PORT }}",

    port: {{ .PORT }}

  }
]

`tags`

tags字段是在Consul中将job注册为服务时使用的可选的标记数组。其他容器可以使用watches这些标签来通过标签过滤服务。

`interfaces`

interfaces字段是可选的单个或数组的接口规范。如果给出，服务的IP将从匹配的第一个接口规范获得。（默认值为["eth0:inet"] ）。 ContainerPilot用于接口IP地址的值将被设置为名称为CONTAINERPILOT_{JOB}_IP的环境变量。请参阅环境变量部分。

`consul`

consul是job具体consul配置的可选块。

enableTagOverride如果设置为true，则外部agent可以更新目录中的此服务并修改标记。
deregisterCriticalServiceAfter是Go时间格式的超时。如果检查处于关键状态超过此配置值，则其关联服务（及其所有相关检查）将自动取消注册

Exec arguments

配置子进程（ jobs/exec和jobs/health/exec ）的所有exec字段都接受字符串或数组。如果给出一个字符串，命令和它的参数用空格分隔; 否则，数组的第一个元素是命令路径，其余的是它的参数。这有助于分解长命令行。

字符串命令

health: {

  exec: "/usr/bin/curl --fail -s http://localhost/app"

}

数组命令

health: {

  exec: [

    "/usr/bin/curl",

    "--fail",

    "-s",

    "http://localhost/app"

  ]

}