Saltar al contenido principal

Wiedii — Convenciones de Calidad IaC (Terraform/Terragrunt)

📖 En corto: IaC (Infrastructure as Code) es describir la infraestructura —servidores, redes, bases de datos— como código versionado, en vez de configurarla a mano. Terraform (y Terragrunt, que lo organiza) es la herramienta con la que se hace en Wiedii; Checkov y TFLint revisan ese código en busca de fallos de seguridad y estilo. Esta nota es para quien escribe o mantiene repos de infraestructura — no hace falta si tu proyecto no tiene Terraform.

Condicional al tipo de proyecto: aplica solo a repos Terraform/Terragrunt los archivos .checkov.yaml/.tflint.hcl y aqua:tflint. Un repo Go/PHP/JS sin IaC no los recibe. Excepción: pipx:checkov es universal (lo exige el checkov-secrets de base.yaml, que corre en todo repo) — ver sección 3. Adoptada como skill terraform-conventions del plugin wiedii-dev, que genera estos archivos por repo al hacer scaffolding/auditoría.

Por qué la skill genera estos archivos (y no se centralizan en wiedii-configs)​

A diferencia de lefthook (config remota desde wiedii-configs) o taplo (opciones en el hook compartido), Checkov y TFLint no admiten config remota ni merge:

  • Checkov carga un solo .checkov.yaml por repo (sin merge entre archivos).
  • TFLint no tiene remote-config; el .tflint.hcl se define por repo.

Por eso la skill del plugin wiedii-dev encapsula la convención y la genera por repo — un solo sitio que se actualiza (la skill), en vez de copiar archivos estáticos que se quedan viejos.

1. .checkov.yaml (solo checkov framework-específico — TF)​

Este .checkov.yaml es solo para el checkov framework-específico (hoy terraform), que consume el pipeline de terraform.yaml. El secrets-scan universal de base.yaml (todo repo) usa el framework secrets por defecto y no necesita un .checkov.yaml por repo. Por eso un repo no-TF no lleva .checkov.yaml, pero sí pipx:checkov (ver sección 3).

framework: [terraform]
quiet: true
compact: true
download-external-modules: false   # decisión documentada (ver abajo)
skip-path: [".terragrunt-cache/", ".terraform/", ".external_modules/"]
skip-check:
  - CKV_TF_1     # GLOBAL: Wiedii pinnea módulos por versión (registry), no por commit-hash git
soft-fail: false
  • CKV_TF_1 = skip global, consecuencia directa del estilo registry + pin por versión (no por commit-hash git). El rationale queda documentado en el propio archivo.
  • CKV_AWS_158 / CKV_AWS_224 (CMK) NO son globales. Son supresiones de seguridad → decisión de política. La skill las deja como hueco a justificar por proyecto, o como default de organización explícito con visto bueno del TL — nunca silencioso.
  • --download-external-modules (default false): la skill ofrece la decisión — escanear dentro de terraform-aws-modules/* (true) vs confiar en ellos (false). Si true, configurar un --external-modules-download-path persistente (caché).

2. .tflint.hcl​

El bloque plugin apunta a GitHub (no a GitLab):

plugin "terraform" {
  enabled = true
  version = "<pin>"
  source  = "github.com/terraform-linters/tflint-ruleset-terraform"   # tflint --init SOLO soporta GitHub
  preset  = "recommended"
}

plugin "aws" {
  enabled = true
  version = "<pin>"
  source  = "github.com/terraform-linters/tflint-ruleset-aws"
}
  • tflint --init solo instala desde GitHub (github.com/org/repo); GitLab self-hosted no está soportado → los rulesets se referencian upstream, pinneados, con GITHUB_TOKEN en CI (por el rate limit). No se alojan en wiedii-configs.
  • Versiones pinneadas (política de versiones pinneadas).

3. Entradas de mise.toml​

"pipx:checkov" = "<pin>"            # PyPI → backend pipx de mise (usa uvx porque uv está presente). NO aqua. Pinnear la versión actual (verificar antes: `pipx run checkov -v` o PyPI).
"aqua:terraform-linters/tflint" = "<pin>"
  • Checkov vía mise pipx: (1 fuente de verdad, pinneado, vía uv) — no uvx checkov@x suelto ni uv tool install fuera de mise. Ver mise-tooling (selección de backend). pipx:checkov es UNIVERSAL: va en el mise.toml de todo repo Wiedii (lo invoca el hook checkov-secrets de base.yaml), no solo en repos TF. Solo .checkov.yaml (framework terraform), .tflint.hcl y aqua:tflint son TF-condicionales.
  • TFLint vía aqua: (curado, checksum-verified).
  • Gotcha: mise.lock pinnea la versión, no todo el árbol de deps Python de Checkov (aceptable para un linter).

4. Job de lefthook (tflint + checkov) — vive en wiedii-configs, se consume vía remotes:​

El pre-commit IaC (terraform fmt → terragrunt hcl fmt → tflint --fix → checkov, en ese orden) no se define por repo: vive una sola vez en wiedii-configs → lefthook/terraform.yaml, aparte del base.yaml agnóstico de stack (que no incluye tflint/checkov — ver lefthook). Su contenido canónico es fuente única en wiedii-configs (no se replica aquí para no derivar); ese archivo se autodocumenta: orden de pasos garantizado, por qué un solo command (evita carreras con parallel: true), scope por directorio cambiado y los --skip-path de cachés (.terragrunt-cache/, .external_modules/, .terraform/).

Un repo Terraform/Terragrunt lo consume desde su lefthook.yaml con un bloque remotes::

remotes:
  - git_url: git@gitlab.wiedii.co:wildcat/wiedii-configs.git
    ref: main            # rastrea la rama main de wiedii-configs (canónico). main está protegida (solo MRs revisadas),
                                 # así que cada merge revisado actualiza los hooks de todos los consumidores en el siguiente lefthook install.
                                 # migrar a `ref: vX.Y.Z` si wiedii-configs adopta tags SemVer
    configs:
      - lefthook/base.yaml       # requerido en todos los stacks
      - lefthook/terraform.yaml  # repos Terraform/Terragrunt

Requisitos en el repo consumidor (los genera esta skill / el scaffolding): .tflint.hcl y .checkov.yaml en la raíz del repo, y terraform (o tofu), tflint, checkov y terragrunt (solo si se usa) declarados en su mise.toml. Los plugins de TFLint se instalan una vez con tflint --init (paso de setup del consumidor) — nunca dentro del hook: --init descarga de GitHub y tiene rate limit.

No inlinear el job en el lefthook.yaml local. Si un repo lo copió localmente (p. ej. al migrar los before_hook de Terragrunt a lefthook), reemplazarlo por el bloque remotes: de arriba — el contenido canónico es de wiedii-configs, mantenerlo duplicado deriva.

Qué NO cubre esta política (lo hacen otros repos)​

  • El job de lefthook (tflint + checkov pre-commit) vive en wiedii-configs (lefthook/terraform.yaml) — ver sección 4 para consumirlo vía remotes:. Su contenido canónico es fuente única allí, no se mantiene en esta nota.
  • Quitar los before_hook, el stage de Checkov en CI y la caché de providers son cambios del repo consumidor (pipeline centralizado, gestionado por Infra).

Relacionado​

  • mise-tooling — mise.toml: backends, tasks, versiones pinneadas.
  • lefthook — hooks compartidos desde wiedii-configs (donde vive el job tflint+checkov).
  • security-scanners — Trivy/Snyk/SonarQube (escáneres de seguridad/calidad en CI).
  • ci-caching — caché en pipelines (referencia para la caché de providers/módulos).
  • renovate — TFLint/Terraform en la actualización automática de dependencias.