gfranks/spruce

Spruce Docker镜像文档

镜像概述

Spruce是一个通用的YAML和JSON合并工具，设计用于直观地合并YAML/JSON模板，以可重复的方式生成复杂配置文件。它能够整合通用顶层定义与特定站点配置，最大程度减少配置重复（DRY原则），并提供多种数据操作和外部系统集成能力。

核心功能与特性

• YAML/JSON合并：支持多文件合并，自动处理嵌套结构和键值覆盖
• 丰富操作符：提供多种操作符（如(( prepend ))）用于数组操作和数据转换
• 语义化比较：通过spruce diff命令分析YAML文件的功能差异，忽略键顺序等无关变化
• 格式转换：使用spruce json将YAML文档转换为JSON格式
• 外部集成：支持与CredHub、Vault等密钥管理系统集成，安全获取凭据
• 配置审计：通过spruce vaultinfo分析配置文件中Vault路径依赖，便于权限管理和审计

使用场景与适用范围

• 配置生成：合并基础模板与环境特定配置，生成最终部署配置
• 配置管理：统一管理多环境（开发、测试、生产）配置，减少重复定义
• CI/CD流程：在自动化流程中动态生成配置文件
• 配置审计：分析配置中的外部依赖（如Vault路径），确保权限最小化
• 格式转换：在需要JSON输入的系统中使用YAML配置源

使用方法与配置说明

前提条件

• 安装Docker引擎（1.13.0+）

基本使用（Docker方式）

假设使用Spruce镜像，基本命令格式：

bash
docker run --rm -v $(pwd):/workdir spruce [子命令] [参数]

示例：合并YAML文件

1. 创建待合并文件：

bash
# 创建first.yml
cat > first.yml <<EOF
some_data: this will be overwritten later
a_random_map:
  key1: some data
heres_an_array:
- first element
EOF

# 创建second.yml
cat > second.yml <<EOF
some_data: 42
a_random_map:
  key2: adding more data
heres_an_array:
- (( prepend ))
- zeroth element
more_data: 84
EOF

2. 执行合并：

bash
docker run --rm -v $(pwd):/workdir spruce merge first.yml second.yml

输出结果：

yaml
a_random_map:
  key1: some data
  key2: adding more data
heres_an_array:
- zeroth element
- first element
more_data: 84
some_data: 42

常用子命令

spruce diff：语义化比较YAML文件

bash
docker run --rm -v $(pwd):/workdir spruce diff file1.yml file2.yml

spruce json：YAML转JSON

bash
docker run --rm -v $(pwd):/workdir spruce json input.yml > output.json

spruce vaultinfo：分析Vault路径依赖

bash
docker run --rm -v $(pwd):/workdir spruce vaultinfo config1.yml config2.yml

从源码编译（非Docker方式）

如需本地编译，步骤如下：

1. 安装Go环境（参考Go安装文档）
2. 获取源码：go get github.com/geofffranks/spruce
3. 进入源码目录：cd ~/go/src/github.com/geofffranks/spruce/
4. 编译并测试：make all

在线 Playground

可通过play.spruce.cf在线测试数据合并和转换，支持多版本Spruce，可保存和分享示例。

详细文档资源

• https://github.com/geofffranks/spruce/blob/master/doc/operators.md
• https://github.com/geofffranks/spruce/blob/master/doc/merging.md
• https://github.com/geofffranks/spruce/blob/master/doc/array-merging.md
• https://github.com/geofffranks/spruce/blob/master/doc/environment-variables-and-defaults.md
• https://github.com/geofffranks/spruce/blob/master/doc/integrating-with-credhub.md
• https://github.com/geofffranks/spruce/blob/master/doc/pulling-creds-from-vault.md

许可证

Spruce基于https://github.com/geofffranks/spruce/blob/master/LICENSE%E5%BC%80%E6%BA%90%E3%80%82