onecommons/unfurl

Unfurl：DevOps 基础设施管理工具

镜像概述和主要用途

Unfurl 是一款用于管理 DevOps 基础设施的命令行工具，旨在通过 git 跟踪配置、密钥、软件依赖及部署历史，集成 Terraform、Ansible、Helm 等现有 DevOps 工具，将流程封装为可重用构建块，以应用中心术语描述云基础设施。其核心价值在于简化云服务的克隆、部署和协作，目标是让任何人都能像克隆代码一样轻松部署云服务，实现可重现的应用档案、去中心化的云基础设施及协作式云服务构建。

核心功能和特性

无服务器，无代理

• 独立 CLI 工具，可在本地开发环境或自动化 CI/CD 管道中使用，无需服务端或代理。

基于应用中心描述部署基础设施

• 使用 OASIS TOSCA 标准 YAML 词汇描述云基础设施高层模型及依赖项（如计算实例、数据库）。
• 支持导入可重用组件或自定义组件，声明依赖项实现增量部署。
• 提供路径查询 DSL 表达资源动态关系，Jinja2 模板支持成熟的模板功能，动态匹配与替换适配不同环境、服务及云提供商。

集成现有 DevOps 工具

• 开箱支持 Terraform、Ansible、shell、Helm、Octodns、Kubernetes、Docker、Supervisor 等工具。
• 提供插件接口自定义集成其他工具，API 支持动态配置实现计划生成完全控制。

开发者友好的状态管理

• 所有资源状态以人类可读、可编辑的应用中心格式存储在 git 中，便于手动覆盖或修复资源表示，支持交互式开发。
• 配置文件保留注释、顺序和空白，YAML 语法宏减少重复代码，提升编辑友好性。

零安装

• 支持本地机器管理和引导部署，自动下载安装指定软件版本和代码。
• 创建管理隔离部署环境（Docker 容器或 Python 虚拟环境 + asdf），清晰分离本地与共享配置，减少本地配置步骤。

灵活的密钥管理

• 声明密钥并保护仓库，支持内联加密或外部密钥管理器（如 HashiCorp Vault）。
• 自动加密“secrets”文件夹中的文件，输出和日志中敏感内容自动脱敏。

"Day Two" 操作

• 提供检查、发现和修复命令，支持定义备份、恢复等维护任务的自定义工作流。

使用场景和适用范围

• 可重现的应用部署：需要创建完全功能化、可重现的 Web 应用档案，确保部署一致性。
• 云基础设施去中心化：追求位置独立性，降低对单一云提供商的依赖，实现基础设施去中心化。
• 协作式云服务构建：希望像协作开发开源软件一样，共同构建和运行云服务，支持克隆、分叉和共享部署配置。
• 跨环境部署：需在不同云服务提供商或环境中部署基础设施，通过自适应模型减少手动配置。

详细使用方法和配置说明

基本工作流程

1. 初始化或克隆仓库

   • 创建新仓库：unfurl init
   • 克隆现有仓库：unfurl clone <仓库地址>

2. 编辑配置文件
   仓库包含以下关键 YAML 文件，描述部署所需的全部信息：

   • 环境中的云服务账户凭据、密钥等敏感信息
   • 代码仓库和容器镜像 registry 配置
   • 基于 TOSCA 标准的云基础设施模型及依赖项
   • 调用 Terraform/Ansible 等工具的操作定义（Unfurl 可自动安装工具）

3. 部署基础设施
   执行 unfurl deploy，Unfurl 基于目标环境和模型生成部署计划，调用对应工具操作，并将最新配置及云账户变更历史提交到 git。

4. 共享与协作

   • 推送到 Github/Gitlab 等 git 服务共享，通过分支或子模块控制环境访问权限。
   • 拉取变更后审核 PR，批准后部署；克隆仓库可部署到新环境（模型自适应不同服务，减少手动调整）。

安装方法

通过 pip 安装

bash
# 默认安装（创建虚拟环境）
pip install unfurl

# 使用系统 Python 安装完整版本
pip install unfurl[full]

# 从源码安装最新版本
pip3 install "git+https://github.com/onecommons/unfurl.git#egg=unfurl"

使用 Docker 容器

bash
docker run --rm -it -v $(pwd):/data -w /data onecommons/unfurl:stable unfurl ...
# stable：对应 PyPI 发布版本；latest：对应仓库最新源码

Shell 自动补全配置

开发与测试

源码克隆

bash
git clone --recurse-submodules https://github.com/onecommons/unfurl

构建文档

bash
tox -e docs

构建分发包

bash
python setup.py sdist bdist_wheel
# 安装构建的包示例
pip install ./dist/unfurl-<版本号>-py2.py3-none-any.whl

运行单元测试

1. 安装 tox：pip install tox==3.28.0（使用 asdf 管理 Python 时需额外安装 tox-asdf）
2. 安装系统依赖：python-dev、libcrypt-dev、openssl-dev（根据 OS 调整）
3. 运行测试：

bash
# 运行所有测试环境
tox

# 运行单个测试（例如 tests/test_runtime.py）
tox -- tests/test_runtime.py

# 重新创建测试环境（依赖安装失败时）
tox -r

注意事项

• 安全风险：早期开发阶段，仅克隆和部署可信仓库，Docker 运行时未配置隔离，项目可能包含可执行代码，存在系统访问风险。
• 并发控制：防止多实例同时修改资源的锁定机制仅对本地仓库副本有效。
• 增量更新：需通过 --force 和 --instance 命令行选项显式限制任务，实现部分增量更新。

相关资源

• 完整文档：[***]
• 快速入门：[***]
• Unfurl Cloud 平台：[***]