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"
  ]
}