Terraform Query: Consulta Infraestructura Existente 2025

Terraform Query es la revolucionaria funcionalidad lanzada en Terraform 1.14 que permite descubrir, consultar y auditar infraestructura existente mediante archivos .tfquery.hcl. Esta característica resuelve uno de los desafíos más persistentes en infraestructura como código: identificar y gestionar recursos cloud desplegados manualmente antes de importarlos al estado de Terraform.

¿Qué es Terraform Query?

El comando terraform query ejecuta operaciones de listado contra infraestructura existente en proveedores cloud como AWS, Azure y Google Cloud. A diferencia de las fuentes de datos tradicionales que requieren identificadores específicos, esta nueva funcionalidad permite búsquedas exploratorias mediante filtros declarativos definidos en archivos con extensión .tfquery.hcl.

Según la documentación oficial de HashiCorp, los archivos de consulta se cargan automáticamente desde el directorio raíz de configuración y pueden contener bloques list, provider, variable y locals para definir parámetros de búsqueda sofisticados.

El flujo de trabajo típico consiste en: definir una o más consultas usando el bloque list en archivos .tfquery.hcl, ejecutar terraform query para descubrir recursos que cumplen los criterios, y opcionalmente generar bloques de configuración e importación automáticamente para traer esos recursos bajo gestión de infraestructura como código.

Ventajas de usar Terraform Query

Esta funcionalidad proporciona beneficios significativos para equipos DevOps y plataformas cloud:

Descubrimiento automatizado: Identifica recursos existentes sin conocer previamente sus identificadores específicos, eliminando búsquedas manuales en consolas web.
Auditorías de infraestructura: Ejecuta consultas periódicas para detectar recursos no gestionados, instancias huérfanas o configuraciones que no cumplen políticas corporativas.
Importaciones masivas simplificadas: Genera automáticamente bloques de configuración e importación para decenas o cientos de recursos simultáneamente.
Búsquedas declarativas: Define criterios de búsqueda mediante HCL reutilizable y versionable, en lugar de scripts imperativos propensos a errores.
Gestión multi-región y multi-cuenta: Combina meta-argumentos for_each para ejecutar búsquedas simultáneas en múltiples regiones AWS o proyectos GCP.
Inventarios dinámicos: Mantén inventarios actualizados de tu infraestructura cloud mediante consultas programadas en pipelines CI/CD.

Esta capacidad es especialmente valiosa en organizaciones donde equipos despliegan recursos manualmente o mediante herramientas legacy que no utilizan infraestructura como código. Para más información sobre automatización de infraestructura, revisa nuestra guía de Docker Compose para arquitecturas modernas.

Sintaxis del archivo .tfquery.hcl

Los archivos con extensión .tfquery.hcl utilizan sintaxis HCL estándar y deben ubicarse en el directorio raíz de tu configuración. La estructura básica incluye el bloque list que define qué recursos buscar:

list "aws_instance" "production_servers" {
  provider = aws.us_east_1
  
  filter {
    name   = "tag:Environment"
    values = ["production"]
  }
  
  filter {
    name   = "instance-state-name"
    values = ["running"]
  }
}

El bloque list requiere dos argumentos posicionales: el tipo de recurso a listar (ejemplo: aws_instance, aws_iam_role, aws_cloudwatch_log_group) y un nombre simbólico para identificar los resultados. El argumento provider es obligatorio y especifica qué proveedor configurado utilizar para ejecutar la consulta.

Bloques filter para búsquedas precisas

Los bloques filter refinan los resultados mediante criterios específicos del proveedor. Para AWS, estos filtros corresponden a los parámetros de las APIs Describe* del SDK:

list "aws_instance" "tagged_instances" {
  provider = aws
  
  filter {
    name   = "tag:Team"
    values = ["devops", "platform"]
  }
  
  filter {
    name   = "vpc-id"
    values = [var.production_vpc_id]
  }
  
  filter {
    name   = "instance-type"
    values = ["t3.medium", "t3.large"]
  }
}

Según análisis técnicos de expertos en infraestructura, la capacidad de combinar múltiples filtros permite búsquedas muy específicas, aunque actualmente no existe soporte nativo para filtros negativos (exclusiones).

Comando terraform query en acción

Una vez definidos tus archivos .tfquery.hcl, ejecuta el comando para descubrir recursos:

terraform query

Este comando muestra resultados en formato legible:

list.aws_instance.production_servers:
  - id: i-0abc123def456
    instance_type: t3.medium
    availability_zone: us-east-1a
    tags:
      Name: web-server-01
      Environment: production
  
  - id: i-0def456abc123
    instance_type: t3.large
    availability_zone: us-east-1b
    tags:
      Name: web-server-02
      Environment: production

Generación automática de configuración

La característica más poderosa es la generación automática de bloques resource e import mediante el flag -generate-config-out:

terraform query -generate-config-out=imported.tf

Este comando crea un archivo imported.tf conteniendo:

import {
  to = aws_instance.production_servers["i-0abc123def456"]
  id = "i-0abc123def456"
}

resource "aws_instance" "production_servers" {
  ami           = "ami-0abc123"
  instance_type = "t3.medium"
  
  tags = {
    Name        = "web-server-01"
    Environment = "production"
  }
  
  # Additional attributes populated from existing resource...
}

Posteriormente ejecuta terraform plan para verificar la configuración generada y terraform apply para importar los recursos al estado. Esto automatiza completamente el tedioso proceso manual de escribir bloques de importación individualmente.

Casos de uso prácticos de Terraform Query

Auditoría de seguridad: detectar instancias sin cifrado

Identifica instancias EC2 con volúmenes EBS no cifrados para cumplir políticas de seguridad:

list "aws_instance" "unencrypted_instances" {
  provider = aws
  
  filter {
    name   = "block-device-mapping.encrypted"
    values = ["false"]
  }
}

Ejecuta esta consulta periódicamente en tu pipeline CI/CD para alertas automáticas sobre configuraciones inseguras. Para gestionar secretos de forma segura, considera herramientas como Vaultwarden.

Inventario multi-región

Combina for_each con múltiples providers para consultas simultáneas en todas las regiones AWS:

locals {
  aws_regions = ["us-east-1", "us-west-2", "eu-west-1"]
}

list "aws_instance" "all_instances" {
  for_each = toset(local.aws_regions)
  
  provider = aws.region[each.value]
  
  filter {
    name   = "instance-state-name"
    values = ["running", "stopped"]
  }
}

Este patrón genera un inventario completo de instancias en múltiples regiones con una sola ejecución.

Importación selectiva de roles IAM

Descubre roles IAM con nombres que siguen convenciones específicas:

variable "role_prefix" {
  description = "Prefijo de roles a importar"
  type        = string
  default     = "app-"
}

list "aws_iam_role" "application_roles" {
  provider = aws
  
  filter {
    name   = "role-name"
    values = ["${var.role_prefix}*"]
  }
}

Ideal para importar masivamente roles creados por herramientas externas o procedimientos manuales legacy.

Monitoreo de logs huérfanos

Identifica grupos de logs CloudWatch sin recursos asociados que consumen costos innecesarios:

list "aws_cloudwatch_log_group" "orphaned_logs" {
  provider = aws
  
  filter {
    name   = "log-group-name-prefix"
    values = ["/aws/lambda/", "/ecs/"]
  }
}

Cruza estos resultados con tus funciones Lambda y servicios ECS existentes para detectar grupos de logs obsoletos. Para monitoreo avanzado, explora Uptime Kuma como complemento.

Soporte de proveedores actual

Al momento del lanzamiento de Terraform 1.14 en noviembre de 2025, el soporte inicial se limita al proveedor AWS con tres tipos de recursos:

aws_instance: Instancias EC2 en todas las regiones
aws_iam_role: Roles IAM globales
aws_cloudwatch_log_group: Grupos de logs CloudWatch

Según la nota de lanzamiento oficial en GitHub, HashiCorp ampliará gradualmente el soporte a más tipos de recursos AWS y otros proveedores cloud en releases subsiguientes de 2025.

La comunidad puede contribuir implementando el protocolo de list resources en providers existentes. Consulta el Terraform Registry para verificar el soporte actual de tu proveedor específico.

Limitaciones y consideraciones

Aunque esta funcionalidad representa un avance significativo, presenta limitaciones importantes:

Cobertura limitada de recursos

Solo tres tipos de recursos AWS soportados en el lanzamiento inicial. Recursos críticos como RDS, S3, VPC y muchos otros aún requieren importación manual tradicional.

Sin filtros negativos nativos

No existe sintaxis para exclusiones directas (ejemplo: «instancias SIN etiqueta X»). Las soluciones actuales requieren múltiples consultas combinadas con operaciones de conjuntos locales, un enfoque ineficiente y complejo.

Configuración generada requiere refinamiento

Los bloques resource generados automáticamente incluyen todos los atributos con sus valores actuales, incluyendo numerosos valores por defecto. La configuración resultante requiere limpieza manual significativa antes de ser production-ready.

Dependencia de configuración existente

Las operaciones de búsqueda requieren inicialización en un directorio con configuración válida y bloques provider definidos. No puedes ejecutar consultas exploratoria sin contexto previo de infraestructura.

Performance en grandes entornos

Consultas sin filtros restrictivos pueden generar miles de resultados en entornos empresariales, causando timeouts o respuestas extremadamente lentas. Siempre aplica filtros específicos.

Integración con importaciones masivas

Esta característica complementa perfectamente el sistema de importación masiva introducido en Terraform 1.5. El flujo completo es:

Descubrimiento: Ejecuta terraform query -generate-config-out=imports.tf para generar configuración e importaciones automáticamente.
Revisión: Examina imports.tf, elimina valores por defecto innecesarios y ajusta configuración según tus convenciones.
Validación: Ejecuta terraform validate -query para validación offline de archivos de consulta sin acceder a proveedores.
Planificación: Ejecuta terraform plan para verificar que la importación no causará cambios inesperados.
Importación: Ejecuta terraform apply para importar recursos al estado y comenzar gestión declarativa.

Este workflow automatizado reduce drásticamente el tiempo necesario para adoptar infraestructura como código en entornos legacy. Según la documentación de HCP Terraform, esta capacidad también funciona en workspaces cloud con soporte para importaciones colaborativas.

Comparación con alternativas

vs. Data Sources tradicionales

Las fuentes de datos (data blocks) requieren identificadores específicos conocidos previamente (IDs, ARNs, nombres exactos). Esta nueva funcionalidad permite búsquedas exploratorias sin conocimiento previo, facilitando descubrimiento de recursos.

vs. Herramientas externas (Terraformer, etc.)

Herramientas como Terraformer analizan APIs cloud y generan configuración completa. Sin embargo, requieren instalación externa, mantenimiento separado y generan configuración frecuentemente desorganizada. Esta solución nativa se integra directamente con el workflow estándar sin dependencias adicionales.

vs. Scripts personalizados

Muchos equipos desarrollan scripts Python/Bash para listar recursos mediante AWS CLI o SDKs. Estos scripts son imperativos, difíciles de mantener y no versionables fácilmente. Los archivos .tfquery.hcl son declarativos, reutilizables y se gestionan junto con el resto de tu infraestructura como código.

Mejores prácticas para Terraform Query

Siempre aplica filtros restrictivos

Evita consultas amplias sin filtros. Siempre especifica criterios como región, etiquetas, estados o VPCs para limitar resultados:

list "aws_instance" "specific_search" {
  provider = aws
  
  # BUENO: Múltiples filtros restrictivos
  filter {
    name   = "tag:Project"
    values = ["ecommerce"]
  }
  filter {
    name   = "vpc-id"
    values = [var.vpc_id]
  }
  
  # EVITAR: Sin filtros = miles de resultados
}

Versiona archivos .tfquery.hcl

Trata los archivos de consulta como código de infraestructura. Inclúyelos en repositorios Git para trazabilidad, revisión por pares y reutilización entre equipos.

Utiliza variables para consultas parametrizadas

Define variables para criterios de búsqueda cambiantes:

variable "environment" {
  description = "Entorno a auditar"
  type        = string
}

list "aws_instance" "env_instances" {
  provider = aws
  
  filter {
    name   = "tag:Environment"
    values = [var.environment]
  }
}

Ejecuta consultas específicas mediante terraform query -var="environment=staging".

Automatiza auditorías en CI/CD

Integra consultas periódicas en pipelines para detectar drift, recursos no gestionados o violaciones de políticas:

- name: Audit Unmanaged Resources
  run: |
    terraform init
    terraform query -generate-config-out=audit.tf
    if [ -s audit.tf ]; then
      echo "Resources no gestionados detectados"
      exit 1
    fi

Limpia configuración generada

Nunca uses directamente la configuración generada sin revisión. Elimina atributos computados, valores por defecto y organiza código según tus convenciones antes de aplicar.

Futuro y roadmap esperado

Basándonos en el patrón histórico de HashiCorp y feedback comunitario, se anticipan estas evoluciones:

Expansión de recursos AWS: Soporte para RDS, S3, Lambda, VPC, Security Groups y otros recursos críticos durante 2025.
Providers adicionales: Azure, Google Cloud, Kubernetes y providers populares recibirán soporte gradualmente.
Filtros avanzados: Operadores lógicos complejos (AND, OR, NOT) para consultas más sofisticadas.
Output formats: Exportación a JSON, YAML o CSV para integración con herramientas externas de inventario.
Búsqueda cross-provider: Consultas federadas que busquen simultáneamente en AWS, Azure y GCP.
Terraform Cloud integration: Dashboards visuales de recursos descubiertos en HCP Terraform.

La comunidad puede acelerar este roadmap contribuyendo a repositorios oficiales en GitHub y votando por funcionalidades en el issue tracker público.

Ejemplo completo: migración de entorno legacy

Imaginemos un escenario real: tienes 50 instancias EC2 desplegadas manualmente en producción que necesitas importar:

# discovery.tfquery.hcl
locals {
  production_vpc = "vpc-abc123"
  regions = ["us-east-1", "us-west-2"]
}

variable "team" {
  description = "Equipo propietario"
  type        = string
  default     = "platform"
}

list "aws_instance" "production_fleet" {
  for_each = toset(local.regions)
  
  provider = aws.region[each.value]
  
  filter {
    name   = "vpc-id"
    values = [local.production_vpc]
  }
  
  filter {
    name   = "tag:Team"
    values = [var.team]
  }
  
  filter {
    name   = "instance-state-name"
    values = ["running"]
  }
}

list "aws_iam_role" "app_roles" {
  provider = aws
  
  filter {
    name   = "role-name"
    values = ["app-*"]
  }
}

Ejecuta el descubrimiento:

terraform init
terraform query -generate-config-out=imported_resources.tf

Revisa y limpia imported_resources.tf, luego aplica:

terraform plan
terraform apply

En minutos has importado decenas de recursos que manualmente habrían requerido horas o días de trabajo tedioso.

Preguntas frecuentes (FAQ)

¿Terraform Query funciona con todos los proveedores?

No. En el lanzamiento inicial de Terraform 1.14, solo el proveedor AWS soporta esta funcionalidad con tres tipos de recursos: aws_instance, aws_iam_role y aws_cloudwatch_log_group. HashiCorp expandirá gradualmente el soporte a más recursos y proveedores durante 2025. Verifica la documentación del proveedor específico para conocer su estado actual.

¿Cómo filtro recursos que NO tienen cierta etiqueta?

Actualmente no existe soporte nativo para filtros negativos. La solución temporal requiere ejecutar dos consultas: una sin filtros de etiquetas y otra con la etiqueta específica, luego usar operaciones de conjuntos locales para calcular la diferencia. HashiCorp planea añadir operadores lógicos más sofisticados en futuras versiones.

¿Puedo ejecutar consultas sin inicializar mi directorio?

No. El comando terraform query requiere un directorio inicializado con terraform init y bloques provider configurados. Esto garantiza que las credenciales y configuración del proveedor estén disponibles para ejecutar las APIs de listado.

¿La configuración generada está lista para producción?

No. La configuración generada automáticamente incluye todos los atributos del recurso con sus valores actuales, incluyendo numerosos valores por defecto y atributos computados. Debes revisar y limpiar manualmente la configuración antes de usarla en producción, eliminando atributos innecesarios y ajustándola a tus convenciones de código.

¿Qué diferencia hay entre terraform query y data sources?

Los bloques data tradicionales requieren identificadores específicos conocidos previamente (ID, ARN, nombre exacto). Esta funcionalidad permite búsquedas exploratorias mediante filtros sin conocimiento previo de identificadores, facilitando el descubrimiento de recursos. Además, puede generar automáticamente bloques de importación, algo que las fuentes de datos no hacen.

Conclusión

Terraform Query representa un avance significativo en la gestión de infraestructura como código, especialmente para organizaciones con recursos legacy desplegados manualmente. La capacidad de descubrir, auditar e importar masivamente infraestructura existente mediante archivos .tfquery.hcl declarativos reduce drásticamente el esfuerzo necesario para adoptar prácticas modernas de IaC.

Aunque el soporte inicial se limita a AWS con tres tipos de recursos, el roadmap de HashiCorp indica expansión gradual durante 2025. Equipos que operan en AWS pueden comenzar a utilizar esta funcionalidad inmediatamente para auditorías de seguridad, inventarios multi-región e importaciones masivas automatizadas.

Implementa las mejores prácticas descritas: aplica siempre filtros restrictivos, versiona tus archivos de consulta, parametriza búsquedas mediante variables y automatiza auditorías en pipelines CI/CD. Estas prácticas maximizan los beneficios mientras minimizan riesgos.

Descarga Terraform 1.14 o superior y comienza a explorar tu infraestructura cloud con el poder de búsquedas declarativas. Combina esta capacidad con herramientas de monitoreo y seguridad para una plataforma cloud robusta y completamente automatizada.