veracross/consult

Consult

为Ruby/Rails应用自动从https://github.com/hashicorp/consul%E5%92%8Chttps://github.com/hashicorp/vault%E7%94%9F%E6%88%90%E9%85%8D%E7%BD%AE%E5%92%8C%E5%AF%86%E9%92%A5%E3%80%82

![Gem Version]([] ![CircleCI]([] ![Maintainability]([***]

背景

该Gem是https://github.com/hashicorp/consul-template%E7%9A%84%22%E7%B2%BE%E7%A5%9E%E5%85%84%E5%BC%9F%22%EF%BC%8C%E4%BD%86%E4%B8%93%E4%B8%BARuby/Rails%E7%8E%AF%E5%A2%83%E8%AE%BE%E8%AE%A1%E3%80%82%E5%AE%83%E4%B8%8D%E5%85%B7%E5%A4%87Consul Template的全部功能，适用于更简单的场景。最重要的是，不会监控租约和配置变更以自动重新渲染。Consult适用于更静态或中长期存在的应用配置。

我们使用Consul Template进行服务器级配置，但应用级配置更复杂。在开发、测试和生产环境中以一致方式获取配置和密钥是个难题。例如，我们希望避免在生产环境使用Consul Template，而在开发环境使用其他自定义解决方案。

使用Consult，所有环境中的流程保持一致。

安装

将以下行添加到应用的Gemfile中：

ruby
gem 'consult'

然后执行：

$ bundle

或自行安装：

$ gem install consult

使用

使用Consult需要一个配置YAML文件和一系列模板文件。配置文件作为模板及其设置的清单，还包含Vault和Consul的可选连接设置。

Consult生成的文件（如secrets.yml、database.yml等）的现有副本应从应用的源代码控制中删除，并添加到.gitignore中。仅将模板保留在源代码控制中，而非生成的文件！

如果该Gem包含在Rails应用中，模板将在Rails启动时渲染。配置或凭据变更可通过重启应用生效。

CLI

通过CLI按需渲染模板。默认情况下，这将绕过模板TTL以强制渲染并提供详细输出。参见consult --help获取选项。

bash
$ bundle exec consult
Consult: 已渲染 my_config
Consult: 已渲染 secrets

Consult CLI也可通过Docker使用：

bash
$ docker run --rm -v .:/app veracross/consult:latest --directory /app

如果模板引用localhost（如本仓库spec目录中的模板），请将--net host添加到命令中。

配置

yaml
# 可选；如果设置，Consult将渲染此特定环境
# 默认为 ENV['RAILS_ENV'] 或 Rails.env（如果存在Rails）
env: test

# "shared"是所有环境默认使用的基础配置
# 注意：不需要使用YAML合并语法即可让特定环境包含共享配置
shared:
  # 可选
  consul:
    # 优先使用 ENV['CONSUL_HTTP_ADDR'] 环境变量
    address: http://0.0.0.0:8500
    # 优先使用 ENV['CONSUL_HTTP_TOKEN'] 环境变量，或 ~/.consul-token 文件
    # 在此处设置令牌不是最佳实践，因为Consul令牌应具有相对较短的TTL
    # 并从环境中读取，但这便于测试
    token: 5d3f1c66-d405-4ad1-b634-ea30be4fb539

  # 可选
  vault:
    # 优先使用 ENV['VAULT_ADDR'] 环境变量
    address: http://0.0.0.0:8200
    # 优先使用 ENV['VAULT_TOKEN'] 环境变量，或 ~/.vault-token 文件
    # 在此处设置令牌不是最佳实践，因为Vault令牌应具有相对较短的TTL
    # 并从环境中读取，但这便于测试
    token: 8fcd5aed-3eb9-412d-8923-1397af7aede2

  # 枚举模板
  templates:
    database:
      # 相对路径默认为 #{Rails.root}
      # 模板路径
      path: config/templates/database.yml
      # 渲染后文件的目标路径
      dest: config/database.yml
      # 如果文件小于此时间（秒），则不重新渲染
      ttl: 3600 # 秒

# 特定环境的配置
# 注意：环境键将与"shared"配置深度合并
test:
  templates:
    secrets:
      path: config/templates/secrets.yml
      dest: config/secrets.yml
      # 可在每个模板基础上定义变量
      vars:
        test_specific_key: and_the_value

    extra_test_config:
      # 通常缺少模板会报错，但可通过配置允许
      skip_missing_template: true
      # 配置文件也通过ERB处理，因此路径可动态生成
      path: config/templates/<%= ENV['extra_test_file'] %>.yml
      dest: config/extra_test_config.yml

production:
  # 可在环境级别定义变量，供这些模板使用
  vars:
    hello: world

  templates:
    # 可将多个文件连接在一起
    my_config:
      paths:
        - config/templates/one.yml
        - config/templates/two.yml
      dest: config/my_config.yml

    # 模板可来自Consul
    your_config:
      consul_keys:
        - some/consul/key
        - another/consul/key
      dest: config/your_config.txt

模板

模板文件通过ERB处理。因此，它们可执行ERB能做的任何事情。Consult还提供一些辅助函数。

注意，在底层，Consult使用https://github.com/WeAreFarmGeek/diplomat%E5%92%8Chttps://github.com/hashicorp/vault-ruby%E3%80%82%E5%9B%A0%E6%AD%A4%EF%BC%8CConsul%E5%AF%B9%E8%B1%A1%E6%98%AFDiplomat%E5%AF%B9%E8%B1%A1%EF%BC%8CVault%E5%AF%B9%E8%B1%A1%E6%98%AFVault Gem对象。参见它们的API文档了解更多信息。Diplomat通常返回具有标题大小写属性的结构体。

Consul函数

service(name) - 获取指定服务的节点。

yaml
<% service("redis").each do |node| %>
host: <%= node.Address %>
port: <%= node.ServicePort %>
<% end %>

返回

host: redis1.local
port: 6379

query(name_or_id, options: nil) - 通过名称或ID执行指定的预准备查询

ruby
<% query('pg-production').tap do |result| %>
  service: <%= result.Service %>
  nodes:
  <% result.Nodes.each do |node| %>
    address: <%= node['Node']['Address']
  <% end %>
<% end %>

query_nodes(name_or_id, options: nil) - 仅返回预准备查询的节点

yml
<% query_nodes('pg-production').each do |node| %>
<%= node['Node'] %>:
  host: <%= node['Address'] %>
  datacenter: <%= node['Datacenter'] %>
<% end %>

pg1:
  host: 10.0.100.101
  datacenter: us-east-1
pg2:
  host: 10.0.100.102
  datacenter: us-east-2

key(key, options: nil, not_found: :reject, found: :return) - 返回给定键的值

yml
'<% key('apps/infrastructure/node/dns') %>':
<<: *common
  host: <%= key('apps/infrastructure/node/dns') %>
  port: 1433

'db1':
<<: *common
  host: db1
  port: 1433

Vault函数

secret(path) - 获取给定路径的密钥。

# Vault KV v2
username: <%= secret('secret/data/credentials').data.dig(:data, :username) %>

# Vault KV v1
username: <%= secret('secret/credentials').data[:username] %>

生成

username: kylo.ren

secrets(path) - 列出给定路径的所有密钥

ruby
<% secrets('secret').each do |path| %>
  <%= path %>
<% end %>

生成

foo
bar
baz

工具函数

timestamp - 渲染当前UTC时间戳。

<%= timestamp %>

渲染

2018-02-23 14:20:29 UTC

indent(string, level, separator = '\n') - 将多行字符串缩进level

yml
keys:
  multi_line: |
<%= indent secret('secret/keys/multi_line).data[:value], 4 %>

渲染

yml
keys:
  multi_line: |
    30ada39cccf79aadbd1d870bc15f0086
    7ea8d734e81e9c6710faa15b0aff516c
    27778ab3b1e10db2028352f12c3c07bb
    e7ec40d1e45834681b4dc3548230d1ca

with(whatever) - 接收whatever并将其返回。等同于tap，但作为[Consul Template]/Go模板约定的桥梁提供。

yml
<% with secret "secrets/credentials" do |s| %>
username: <%= s.data[:username] %>
password: <%= s.data[:password] %>
<% end %>

更多完整示例

将多个服务器渲染到database.yml文件中，按名称键控。

yml
# database.yml
<% service("postgres").each do |node| %>
'<%= node.Node %>':
  host: <%= node.Address %>
  port: <%= node.ServicePort %>
  <%- with secret "secret/base/sql-server/#{node.Node}/web" do |s| -%>
  # 凭据租约有效期至 <%= (timestamp + s.lease_duration).to_s %>
  username: <%= s.data[:username] %>
  password: <%= s.data[:password] %>
  <% end -%>
<% end %>

生成类似如下内容

yml
# database.yml
'db1':
  host: 10.0.100.101
  port: 5432
  # 凭据租约有效期至 2018-02-24 16:08:29 UTC
  username: foo
  password: bar
'db2':
  host: 10.0.100.102
  port: 5432
  # 凭据租约有效期至 2018-02-24 16:08:29 UTC
  username: baz
  password: qux

密钥

yml
# secrets.yml
shared:
  rollbar_token: <%= secret('secrets/third_party').data[:rollbar] %>
  scout_token: <%= secret('secrets/third_party').data[:scout] %>

development:
  secret_key_base: abcd1234....

production:
  secret_key_base: <%= secret('secret/apps/myapp').data[:secret_key_base] %>

然后在应用中通过Rails.application.secrets引用密钥。

ruby
# config/initializers/rollbar.rb
Rollbar.configure do |config|
  config.access_token = Rails.application.secrets.rollbar_token
end

开发

检出仓库后，运行bin/setup安装依赖。也可运行bin/console获取交互式提示以进行实验。测试说明见下文。

要将该Gem安装到本地机器，运行bundle exec rake install。要发布新版本，更新version.rb中的版本号，然后运行bundle exec rake release，这将创建版本的git标签，推送git提交和标签，并将.gem文件推送到rubygems.org。

测试

通过Docker运行Consul和Vault可简化测试。启动它们的最小容器：

$ docker-compose up

然后运行bundle exec rspec或bundle exec guard。

贡献

错误报告和拉取请求可在GitHub上提交：https://github.com/veracross/consult%E3%80%82

许可证

该Gem作为开源软件发布，遵循MIT许可证条款。