Question

选项

查看全部选项，使用以下命令

consul-template -h 

命令行

CLI 接口支持上面出现的所有选项。

查询 demo.consul.io 这个 Consul 实例(agent).渲染模板文件 /tmp/template.ctmpl 保存到 /tmp/result , 运行 Consul-template 服务直到直到手动结束:

consul-template \
  -consul demo.consul.io \
  -template "/tmp/template.ctmpl:/tmp/result"

查询本地的 Consul 实例(agent),一旦模板发生变化渲染模板并重启 Nginx ,如果 Consul 不可用 30 秒重试一次:

consul-template \
  -consul 127.0.0.1:8500 \
  -template "/tmp/template.ctmpl:/var/www/nginx.conf:service nginx restart" \
  -retry 30s \
  -once

查询一个 Consul 实例，渲染多个模板并作为服务直到停止:

consul-template \
  -consul my.consul.internal:6124 \
  -template "/tmp/nginx.ctmpl:/var/nginx/nginx.conf:service nginx restart" \
  -template "/tmp/redis.ctmpl:/var/redis/redis.conf:service redis restart" \
  -template "/tmp/haproxy.ctmpl:/var/haproxy/haproxy.conf"

查询一个需要权限验证的 Consul 实例，将渲染后的模板输出到控制台而不写入磁盘.在这个例子中 -template 的第二个和第三个参数是必须的但是被忽略了.这个文件将不会被写入磁盘，命令也不会被执行。

$ consul-template \
  -consul my.consul.internal:6124 \
  -template "/tmp/template.ctmpl:/tmp/result:service nginx restart"
  -dry

使用 SSL 证书进行 Consul 的查询:

$ consul-template \
  -consul 127.0.0.1:8543 \
  -ssl \
  -ssl-cert /path/to/client/cert.pem \
  -ssl-ca-cert /path/to/ca/cert.pem \
  -template "/tmp/template.ctmpl:/tmp/result" \
  -dry \
  -once

查询 Consul 并启动一个子进程.模板的变化会发送指令给子进程.详细的说明请查看 这里 .

$ consul-template \
  -template "/tmp/in.ctmpl:/tmp/result" \
  -exec "/sbin/my-server"

配置文件

Consul-Template 配置文件是使用 HashiCorp Configuration Language (HCL) 编写的.这意味着 Consul Template 是和 JSON 兼容的，查看更多信息请查看 HCL 规范

配置文件语法支持上面的所有的选项，除非在表格中进行标明。

// 这是要连接的 Consul Agent 的地址.默认为 127.0.0.1:8500.这是 Consul 的默认绑定地址和端口.
// 不建议你直接与 Consul 的 Server 直接进行交互，请与本地的 Consul Agent 进行交互.这样做是有一些原因
// 最重要的是本地 agent 可以复用与 server 的连接.减少 HTTP 的连接数.另外这个地址更好记.
consul = "127.0.0.1:8500"

// 这是用于连接 Consul 的 ACL token. 如果你的集群未启用就不需要设置.
//
// 这个选项也可以通过环境变量 CONSUL_TOKEN 来进行设置
token = "abcd1234"

// 这是监听出发 reload 事件的信号，默认值如下所示.将这个值设置为空将引起 CT ,从而不监听 reload 事件
reload_signal = "SIGHUP"

// 这是监听出发 core dump 事件的信号，默认值如下所示.将这个值设置为空将引起 CT ,从而不监听 core dump 信号
dump_signal = "SIGQUIT"

// 这是监听出发 graceful stop 事件的信号，默认值如下所示.将这个值设置为空将引起 CT ,从而不监听 graceful stop 信号
kill_signal = "SIGINT"

// 这是连接 Consul 的重试时间.Consul Template 是高容错的设计.这意味着，出现失败他不会退出.而按照
// 分布式系统的惯例进行指数补偿和重试来等待集群恢复.
retry = "10s"

// This is the maximum interval to allow "stale" data. By default, only the
// Consul leader will respond to queries; any requests to a follower will
// forward to the leader. In large clusters with many requests, this is not as
// scalable, so this option allows any follower to respond to a query, so long
// as the last-replicated data is within these bounds. Higher values result in
// less cluster load, but are more likely to have outdated data.
// 这是允许陈旧数据的最大时间.Consul 默认只有领袖对请求进行相应.所有对追随者的请求将被转发给领袖.
// 在有大量请求的大型集群中，这显得不够有扩展性.所以这个选项允许任何追随者响应查询，只要最后复制的数据
// 在这个范围内.数值越高，越减少集群负载，但是更容易接受到过期数据.
max_stale = "10m"

// 这是 log 的等级，如果你找到了 bug,请打开 debug 日志，这样我们可以更好的定位问题.这个选项也可用在命令行.
log_level = "warn"

// 这是存放 Consul Template 进程的 PID 文件的路径，如果你计划发送定制的信号到这个进程这会比较有用.
pid_file = "/path/to/pid"

// 这是一个静止定时器，他定义了在模板渲染之前等待集群达到一致状态的最小和最大时间.
// 这对于一些变化较大的系统中比较有用，可以减少模板渲染的次数
wait = "5s:10s"


// 这是 Vault 配置的开始
// Vault 是 HashiCorp 的另外一个产品
vault {
  // This is the address of the Vault leader. The protocol (http(s)) portion
  // of the address is required.
  address = "https://vault.service.consul:8200"

  // This is the token to use when communicating with the Vault server.
  // Like other tools that integrate with Vault, Consul Template makes the
  // assumption that you provide it with a Vault token; it does not have the
  // incorporated logic to generate tokens via Vault's auth methods.
  //
  // This value can also be specified via the environment variable VAULT_TOKEN.
  token = "abcd1234"

  // This option tells Consul Template to automatically renew the Vault token
  // given. If you are unfamiliar with Vault's architecture, Vault requires
  // tokens be renewed at some regular interval or they will be revoked. Consul
  // Template will automatically renew the token at half the lease duration of
  // the token. The default value is true, but this option can be disabled if
  // you want to renew the Vault token using an out-of-band process.
  //
  // Note that secrets specified in a template (using {{secret}} for example)
  // are always renewed, even if this option is set to false. This option only
  // applies to the top-level Vault token itself.
  renew = true

  // This section details the SSL options for connecting to the Vault server.
  // Please see the SSL options below for more information (they are the same).
  ssl {
    // ...
  }
}

// 这部分配置请求的基本的权限验证信息
auth {
  enabled  = true
  username = "test"
  password = "test"
}

// 这部分配置连接到 Consul 服务器的 SSL 信息.
ssl {
  // 使用 SSL 需要先打开这个开关
  enabled = true

  // This enables SSL peer verification. The default value is "true", which
  // will check the global CA chain to make sure the given certificates are
  // valid. If you are using a self-signed certificate that you have not added
  // to the CA chain, you may want to disable SSL verification. However, please
  // understand this is a potential security vulnerability.
  verify = false

  // This is the path to the certificate to use to authenticate. If just a
  // certificate is provided, it is assumed to contain both the certificate and
  // the key to convert to an X509 certificate. If both the certificate and
  // key are specified, Consul Template will automatically combine them into an
  // X509 certificate for you.
  cert = "/path/to/client/cert"
  key = "/path/to/client/key"

  // This is the path to the certificate authority to use as a CA. This is
  // useful for self-signed certificates or for organizations using their own
  // internal certificate authority.
  ca_cert = "/path/to/ca"
}

// 设置连接到 syslog 服务器的配置
// 用于进行日志记录 syslog {
  // 打开开关
  enabled = true

  // 设备名称
  facility = "LOCAL5"
}

// This block defines the configuration for de-duplication mode. Please see the
// de-duplication mode documentation later in the README for more information
// on how de-duplication mode operates.
deduplicate {
  // This enables de-duplication mode. Specifying any other options also enables
  // de-duplication mode.
  enabled = true

  // This is the prefix to the path in Consul's KV store where de-duplication
  // templates will be pre-rendered and stored.
  prefix = "consul-template/dedup/"
}

// This block defines the configuration for exec mode. Please see the exec mode
// documentation at the bottom of this README for more information on how exec
// mode operates and the caveats of this mode.
exec {
  // This is the command to exec as a child process. There can be only one
  // command per Consul Template process.
  command = "/usr/bin/app"

  // This is a random splay to wait before killing the command. The default
  // value is 0 (no wait), but large clusters should consider setting a splay
  // value to prevent all child processes from reloading at the same time when
  // data changes occur. When this value is set to non-zero, Consul Template
  // will wait a random period of time up to the splay value before reloading
  // or killing the child process. This can be used to prevent the thundering
  // herd problem on applications that do not gracefully reload.
  splay = "5s"

  // This defines the signal that will be sent to the child process when a
  // change occurs in a watched template. The signal will only be sent after
  // the process is started, and the process will only be started after all
  // dependent templates have been rendered at least once. The default value
  // is "" (empty or nil), which tells Consul Template to restart the child
  // process instead of sending it a signal. This is useful for legacy
  // applications or applications that cannot properly reload their
  // configuration without a full reload.
  reload_signal = "SIGUSR1"

  // This defines the signal sent to the child process when Consul Template is
  // gracefully shutting down. The application should begin a graceful cleanup.
  // If the application does not terminate before the `kill_timeout`, it will
  // be terminated (effectively "kill -9"). The default value is "SIGTERM".
  kill_signal = "SIGINT"

  // This defines the amount of time to wait for the child process to gracefully
  // terminate when Consul Template exits. After this specified time, the child
  // process will be force-killed (effectively "kill -9"). The default value is
  // "30s".
  kill_timeout = "2s"
}

// 这部分定义了对模板的配置，和其他配置块不同.这部分可以针对不同模板配置多次.也可以在 CLI 命令
// 直接进行配置
template {
  // 这是输入模板的配置文件路径，必选项
  source = "/path/on/disk/to/template.ctmpl"

  // 这是源模板渲染之后存放的路径，如果父目录不存在 Consul Template 会尝试进行创建
  destination = "/path/on/disk/where/template/will/render.txt"

  // This is the optional command to run when the template is rendered. The
  // command will only run if the resulting template changes. The command must
  // return within 30s (configurable), and it must have a successful exit code.
  // Consul Template is not a replacement for a process monitor or init system.
  // 这是当模板渲染完成后可选的要执行的命令.这个命令只会在模板发生改变后才会运行.这个命令必须要在 30 秒
  // 内进行返回（可配置),必须返回一个成功的退出码.Consul Template 不能替代进程监视或者 init 系统
  // 的功能
  command = "restart service foo"

  // 这是最大的等待命令返回的时间，默认是 30 秒
  command_timeout = "60s"

  // 这是渲染后的文件的权限，如果不设置,Consul Template 将去匹配之前已经存在的文件的权限.
  // 如果文件不存在，权限会被设置为 0644
  perms = 0600

  // 这个选项对渲染之前的文件进行备份.他保持一个备份.
  // 这个选项在发生意外更高时，有一个回滚策略.
  backup = true

  // 模板的分隔符，默认是 "{{"和"}}".但是对于一些模板用其他的分隔符可能更好
  // 可以避免与本身的冲突
  left_delimiter  = "{{"
  right_delimiter = "}}"

  // 这是最小和最大等待渲染一个新模板和执行命令的时间.使用 分号 个号.如果忽略最大值，最大
  // 值会被设置为最小值的 4 倍.这个选项没有默认值.这个值相对全局所以的等待时间有最高优先级
  wait = "2s:6s"
}

注意: 不是所有的选项都是必选的.例如: 如果你没有使用 Vault 你不用设置这一块. 类似的你没有使用 syslog 系统你也不需要指定 syslog 配置。

为了更加安全, token 也可以从环境变量里读取，使用 CONSUL_TOKEN 和 VAULT_TOKEN .强烈建议你不要把 token 放到未加密的文本配置文件中。

查询 nyc3 demo 的 Consul 示例，渲染模板 /tmp/template.ctmpl 到 /tmp/result .运行 Consul Template 直到服务停止:

consul = "nyc3.demo.consul.io"

template {
  source      = "/tmp/template.ctmpl"
  destination = "/tmp/result"
}

如果一个用一个目录替换文件，所以这个目录中的文件会递归的安装 Go walk 函数的顺序进行合并.所以如果多个文件定义了 consul key 则最后一个将会被使用，注意，符号链接不会被加入。

在命令行指定的选项，优先于配置文件