bflad/tfproviderlint

Terraform Provider Lint Tool Docker镜像文档

1. 镜像概述和主要用途

Terraform Provider Lint Tool（以下简称"TF Provider Lint"）Docker镜像是一款封装了Terraform Provider静态代码分析工具的容器化解决方案。其核心用途是对Terraform Provider源代码进行自动化检查，识别语法错误、代码风格问题、最佳实践违背及潜在逻辑缺陷，支持自定义规则扩展，帮助开发者提升Provider代码质量、一致性及可靠性。

2. 核心功能和特性

• 代码风格一致性检查：内置Terraform Provider开发规范（如HashiCorp官方编码标准），自动检测代码缩进、命名规范（资源/数据源命名、函数命名）、注释完整性等风格问题。
• 语法错误与潜在缺陷检测：静态分析Terraform Provider代码（Go语言实现），识别未处理的错误返回、空指针解引用、资源状态管理不当等运行时风险。
• 最佳实践验证：内置Provider开发最佳实践规则，如资源ID格式校验、参数默认值设置、导入逻辑正确性、文档与代码一致性等。
• 自定义规则支持：允许通过规则配置文件（JSON/YAML格式）扩展检查逻辑，适配团队特定规范。
• 多格式输出：支持文本（默认）、JSON、HTML等输出格式，便于集成到CI报告或本地查看。
• 轻量级设计：基于Alpine Linux基础镜像，镜像体积小（通常<100MB），启动速度快。

3. 使用场景和适用范围

• 本地开发阶段自检：开发者在提交代码前，通过容器快速检查本地修改，提前发现问题。
• CI/CD流水线集成：作为自动化检查环节嵌入GitLab CI、GitHub Actions等流水线，阻止不合规代码合并或发布。
• 团队代码规范统一：通过共享镜像配置（含固定规则集），确保团队成员遵循一致的编码标准。
• Provider发布前验证：在Terraform Provider发布前执行全面检查，确保符合HashiCorp发布要求（如通过terraform provider validate前置检查）。

4. 使用方法和配置说明

4.1 前提条件

• 已安装Docker Engine（20.10+）或Docker Desktop。
• 本地Terraform Provider源代码目录结构规范（符合https://developer.hashicorp.com/terraform/plugin/framework/getting-started/structure%EF%BC%89%E3%80%82

4.2 镜像拉取

从容器仓库拉取最新版本镜像（请替换<image-name>为实际镜像名称，如hashicorp/terraform-provider-lint）：

bash
docker pull docker.xuanyuan.run/<image-name>:latest

4.3 基本使用（docker run）

4.3.1 基础检查命令

挂载本地Provider源代码目录到容器内/workspace路径，执行默认规则检查：

bash
docker run -v $(pwd):/workspace <image-name>:latest \
  lint /workspace  # /workspace为容器内代码根目录

• -v $(pwd):/workspace：将当前目录（本地Provider代码）挂载到容器内工作目录。
• lint /workspace：容器入口命令，指定对/workspace目录下的代码执行检查。

4.3.2 输出结果示例

默认输出文本格式结果，包含错误级别（ERROR/WARN/INFO）、规则ID、文件路径及问题描述：

[ERROR] RULE-ID: RESOURCE-NAME-001  
File: ./internal/provider/resource_example.go:15  
Message: Resource name "example_resource" must follow snake_case format (expected "example_resource_v1").  

[WARN] RULE-ID: PARAM-VALIDATION-002  
File: ./internal/provider/schema_example.go:23  
Message: Parameter "max_size" missing validation for minimum value (recommended: min(1)).  

4.4 高级配置

4.4.1 自定义规则文件

通过挂载自定义规则目录，扩展或覆盖默认规则：

1. 本地创建规则目录（如./custom-rules），包含规则文件（如rules.yaml）。
2. 挂载规则目录到容器内/config/rules，并通过--rule-dir参数指定：

bash
docker run -v $(pwd):/workspace -v $(pwd)/custom-rules:/config/rules <image-name>:latest \
  lint /workspace --rule-dir /config/rules

4.4.2 忽略文件配置

通过.tfproviderlintignore文件指定无需检查的文件或规则（格式类似.gitignore）：

1. 本地创建.tfproviderlintignore，内容示例：

# 忽略测试文件
**/*_test.go  
# 忽略特定规则
RULE-ID:RESOURCE-NAME-001

2. 挂载忽略文件到容器内/workspace/.tfproviderlintignore（或通过--ignore-file指定路径）：

bash
docker run -v $(pwd):/workspace <image-name>:latest \
  lint /workspace --ignore-file /workspace/.tfproviderlintignore

4.4.3 输出格式设置

通过--output-format参数指定输出格式（支持text/json/html），并挂载目录保存结果文件：

bash
# 输出JSON格式到本地./reports目录
docker run -v $(pwd):/workspace -v $(pwd)/reports:/output <image-name>:latest \
  lint /workspace --output-format json --output-path /output/lint-report.json

4.5 Docker Compose配置示例

创建docker-compose.yml简化多环境配置（如固定规则、输出目录）：

yaml
version: '3.8'
services:
  tf-provider-lint:
    image: docker.xuanyuan.run/<image-name>:latest
    volumes:
      - ./:/workspace                # 挂载代码目录
      - ./custom-rules:/config/rules # 挂载自定义规则
      - ./reports:/output            # 挂载输出目录
    command: >
      lint /workspace 
      --rule-dir /config/rules 
      --ignore-file /workspace/.tfproviderlintignore 
      --output-format html 
      --output-path /output/lint-report.html
    environment:
      - LOG_LEVEL=info               # 日志级别（info/warn/debug）

启动检查：

bash
docker-compose up

5. 配置参数和环境变量

5.1 命令行参数

5.2 环境变量

6. 常见问题排查

• 权限错误：容器内用户无代码目录读写权限。解决：添加--user $(id -u):$(id -g)参数，使用当前用户ID运行容器。
• 规则文件未生效：检查--rule-dir路径是否正确，规则文件格式是否符合要求（参考规则文件规范）。
• 输出文件为空：代码无违规问题，或检查范围错误（确认挂载的代码目录正确）。
• CI流水线超时：镜像体积过大导致拉取缓慢。解决：使用特定版本标签（如:v1.2.0）而非latest，或配置镜像缓存。