sbpam/tfc-agent

轻微修改版 TFC Agent 镜像文档

1. 镜像概述

1.1 概述

本镜像为轻微修改的 Terraform Cloud (TFC) Agent 容器化实现，基于官方 TFC Agent 构建，保留核心功能的同时，支持部分自定义配置扩展，适用于需要在自有基础设施中执行 Terraform 运行的场景。

1.2 主要用途

作为 Terraform Cloud 的代理服务，在用户可控的环境中接收并执行来自 Terraform Cloud 的计划、应用等任务，实现基础设施即代码 (IaC) 的本地化执行与管理。

2. 核心功能与特性

2.1 基础兼容性

• 完全兼容官方 TFC Agent 的核心协议与任务执行逻辑，可无缝对接 Terraform Cloud 平台。

2.2 自定义配置支持

• 支持通过环境变量或配置文件调整 Agent 行为（如超时时间、资源限制等），满足特定场景需求。

2.3 安全执行环境

• 继承官方 Agent 的安全隔离机制，任务执行过程与主机环境隔离，降低运行风险。

2.4 资源优化

• 轻微调整进程调度逻辑，优化内存占用与 CPU 资源使用，提升在受限环境下的稳定性。

2.5 日志增强

• 支持自定义日志格式与输出路径，便于集成第三方监控与日志分析工具（如 Prometheus、ELK）。

3. 使用场景与适用范围

3.1 企业级自定义执行环境

• 适用于需要在 Agent 中集成企业内部工具链（如私有镜像仓库、密钥管理服务）的场景。

3.2 数据隐私与合规要求

• 满足***、***等行业对数据本地化处理的需求，避免敏感配置/状态文件传输至第三方服务。

3.3 混合云/多云环境管理

• 在混合云或多云架构中，作为统一执行入口，对接不同云厂商的资源管理接口。

3.4 CI/CD 流水线集成

• 嵌入 CI/CD 流程（如 Jenkins、GitLab CI），实现基础设施部署与应用发布的自动化联动。

3.5 资源受限环境

• 优化后的资源占用特性，适用于边缘计算节点或资源配额有限的私有云环境。

4. 使用方法与配置说明

4.1 前置条件

• 已注册 Terraform Cloud 账户，并创建 Agent Pool（路径：Organization Settings > Agents > Agent Pools）。
• 获取有效的 Agent Token（从 Agent Pool 中生成，需妥善保管，仅展示一次）。
• 主机已安装 Docker 19.03+ 或 Docker Compose 2.0+。

4.2 快速启动（docker run）

通过以下命令启动容器，替换 <AGENT_TOKEN> 为实际 Token：

bash
docker run -d \
  --name tfc-agent-modified \
  -e TFC_AGENT_TOKEN="<AGENT_TOKEN>" \
  -e TFC_AGENT_NAME="modified-agent-01" \  # 可选：自定义 Agent 名称（在 TFC 控制台显示）
  -e TFC_AGENT_LOG_LEVEL="info" \          # 可选：日志级别（debug/info/warn/error）
  -v /var/run/docker.sock:/var/run/docker.sock \  # 可选：如需在任务中使用 Docker（如构建镜像）
  -v /path/to/local/cache:/agent/cache \    # 可选：挂载本地目录作为缓存，加速重复任务
  your-registry/tfc-agent-modified:latest

4.3 Docker Compose 配置

创建 docker-compose.yml 文件，示例如下：

yaml
version: "3.8"
services:
  tfc-agent:
    image: your-registry/tfc-agent-modified:latest
    container_name: tfc-agent-modified
    restart: unless-stopped
    environment:
      - TFC_AGENT_TOKEN=<AGENT_TOKEN>
      - TFC_AGENT_NAME=modified-agent-01
      - TFC_AGENT_LOG_LEVEL=info
      - TFC_AGENT_TIMEOUT=3600  # 可选：任务超时时间（秒），默认 1800
    volumes:
      - ./agent-cache:/agent/cache:rw  # 缓存目录，提升性能
      - ./agent-config:/agent/config:ro  # 可选：挂载自定义配置文件（如 agent.hcl）
      - /var/log/tfc-agent:/agent/logs:rw  # 可选：挂载日志目录，持久化日志
    networks:
      - tfc-agent-net

networks:
  tfc-agent-net:
    driver: bridge

启动命令：docker-compose up -d

4.4 环境变量配置

4.5 卷挂载说明

4.6 自定义配置（修改点说明）

本镜像在官方版本基础上支持通过 /agent/config/agent.hcl 文件扩展配置（需挂载卷），示例配置：

hcl
# agent.hcl - 自定义配置示例（仅列出修改相关项）
log {
  format = "json"  # 官方默认 text，修改支持 json 格式日志
  file   = "/agent/logs/agent.log"
}

resource {
  cpu_limit  = 1024  # CPU 限制（mCPU），默认无限制
  mem_limit  = 2048  # 内存限制（MB），默认无限制
}

5. 注意事项

• Agent Token 安全：TFC_AGENT_TOKEN 具有敏感权限，需通过环境变量或密钥管理服务注入，避免硬编码。
• 版本兼容性：确保镜像版本与 Terraform Cloud 平台版本兼容（建议与官方 TFC Agent 版本号对齐）。
• 资源监控：生产环境建议监控容器 CPU/内存占用，根据任务负载调整 TFC_AGENT_CONCURRENCY 与资源限制。
• 日志轮转：挂载日志目录时，建议配置日志轮转工具（如 logrotate），避免磁盘占满。

6. 故障排查

• 连接失败：检查 TFC_AGENT_TOKEN 是否有效、网络连通性（TFC 服务地址：agent.terraform.io:443）。
• 任务超时：增大 TFC_AGENT_TIMEOUT 或检查任务资源需求是否超过容器限制。
• 缓存异常：清除 /agent/cache 目录并重启容器，排查缓存文件损坏问题。
• 日志缺失：确认日志目录挂载权限为 rw，或检查 TFC_AGENT_LOG_LEVEL 是否设置为 debug。