轻微修改版 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。