module "<nombre_local>" {
  source = "<fuente_del_modulo>"

  # Variables de entrada del módulo
  variable_1 = valor_1
  variable_2 = valor_2
}

module "mi_instancia" {
  source  = "terraform-aws-modules/ec2-instance/aws"
  version = "~> 5.0"

  # Variables del módulo
  name          = "mi-servidor"
  instance_type = "t3.micro"

  # --- Argumentos especiales de Terraform ---

  # count: crea múltiples instancias del módulo (como con recursos)
  count = 3

  # for_each: crea una instancia por cada elemento del mapa o set
  # (no se puede usar count y for_each simultáneamente)
  # for_each = { dev = "t3.micro", prod = "t3.large" }

  # depends_on: dependencias explícitas con otros recursos o módulos
  depends_on = [module.red]

  # providers: especifica qué configuración de provider usar (avanzado)
  # providers = {
  #   aws = aws.eu_west_1
  # }
}

# Módulo en un subdirectorio
module "red" {
  source = "./modules/networking"
}

# Módulo en el directorio padre
module "compartido" {
  source = "../modules/comun"
}

# Módulo varios niveles arriba
module "corporativo" {
  source = "../../infraestructura-base/modules/seguridad"
}

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"

  name = "mi-vpc"
  cidr = "10.0.0.0/16"

  azs             = ["eu-west-1a", "eu-west-1b", "eu-west-1c"]
  private_subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
  public_subnets  = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]
}

# Todo el repositorio como módulo
module "ejemplo" {
  source = "github.com/hashicorp/example"
}

# Subdirectorio específico dentro del repositorio
module "s3_bucket" {
  source = "github.com/terraform-aws-modules/terraform-aws-s3-bucket//modules/object"
}

# Con referencia a una rama, tag o commit específico
module "s3_bucket_v3" {
  source = "github.com/terraform-aws-modules/terraform-aws-s3-bucket//modules/object?ref=v3.15.1"
}

# HTTPS (repositorio público o con autenticación via .netrc)
module "interno" {
  source = "git::https://gitlab.empresa.com/infra/terraform-modules.git//vpc?ref=v2.0.0"
}

# SSH (requiere clave SSH configurada)
module "privado" {
  source = "git::ssh://[email protected]/infra/terraform-modules.git//networking?ref=main"
}

module "desde_s3" {
  source = "s3::https://s3-eu-west-1.amazonaws.com/mi-bucket-terraform/modulos/servidor-v1.2.0.zip"
}

module "desde_gcs" {
  source = "gcs::https://www.googleapis.com/storage/v1/mi-bucket/modulos/networking.zip"
}

# Si el módulo tiene en variables.tf:
# variable "nombre" { type = string }
# variable "instancias" { type = number, default = 1 }
# variable "etiquetas" { type = map(string), default = {} }

module "mi_servidor" {
  source = "./modules/servidor"

  # Pasamos valores para las variables del módulo
  nombre     = "servidor-web"           # string
  instancias = 3                        # number
  etiquetas  = {                        # map(string)
    Entorno  = "produccion"
    Proyecto = "tienda-online"
    Equipo   = "backend"
  }
  # 'instancias' y 'etiquetas' tienen default, así que son opcionales
}

variable "entorno" {
  type    = string
  default = "dev"
}

module "base_datos" {
  source = "./modules/database"

  # Usando una variable del módulo raíz
  entorno = var.entorno

  # Usando el output de otro módulo
  subnet_ids = module.red.private_subnet_ids

  # Usando una función de Terraform
  nombre_bd = "${var.entorno}-db-${formatdate("YYYYMMDD", timestamp())}"

  # Expresión condicional
  multi_az = var.entorno == "production" ? true : false
}

module.<nombre_local>.<nombre_output>

module "red" {
  source     = "./modules/networking"
  cidr_block = "10.0.0.0/16"
}

module "compute" {
  source = "./modules/compute"

  # Usamos el output 'subnet_id' del módulo 'red'
  subnet_id = module.red.subnet_id
  vpc_id    = module.red.vpc_id
}

# Podemos usar los outputs en el módulo raíz también
output "ip_servidor" {
  description = "IP pública del servidor creado"
  value       = module.compute.ip_publica
}

output "url_aplicacion" {
  description = "URL de acceso a la aplicación"
  value       = "https://${module.compute.ip_publica}"
}

# Con count: se crea una lista de módulos
module "servidor" {
  source = "./modules/servidor"
  count  = 3

  nombre = "servidor-${count.index}"
}

# Acceder al output de una instancia específica
output "ip_primer_servidor" {
  value = module.servidor[0].ip_publica
}

# Acceder a todos los outputs como lista
output "todas_las_ips" {
  value = module.servidor[*].ip_publica
}

# Con for_each: se crea un mapa de módulos
module "servidor" {
  source   = "./modules/servidor"
  for_each = toset(["web", "api", "worker"])

  nombre = each.key
}

# Acceder al output de una instancia específica
output "ip_servidor_web" {
  value = module.servidor["web"].ip_publica
}

# Acceder a todos los outputs como mapa
output "todas_las_ips" {
  value = { for k, v in module.servidor : k => v.ip_publica }
}

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "5.1.2"          # Versión exacta: muy restrictivo
}

module "ec2" {
  source  = "terraform-aws-modules/ec2-instance/aws"
  version = "~> 5.0"         # >= 5.0, < 6.0: acepta parches y menores
}

module "rds" {
  source  = "terraform-aws-modules/rds/aws"
  version = ">= 6.0, < 7.0"  # Rango explícito
}

module "s3" {
  source  = "terraform-aws-modules/s3-bucket/aws"
  version = "!= 3.5.0"        # Cualquier versión excepto la 3.5.0 (tiene un bug)
}

root/
├── main.tf                   ← módulo raíz
└── modules/
    ├── aplicacion-completa/  ← módulo de nivel 1
    │   ├── main.tf           ← llama a los módulos de nivel 2
    │   ├── variables.tf
    │   ├── outputs.tf
    │   └── (no tiene submódulos propios aquí)
    ├── red/                  ← módulo de nivel 2
    │   ├── main.tf
    │   ├── variables.tf
    │   └── outputs.tf
    └── servidor/             ← módulo de nivel 2
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

# modules/aplicacion-completa/main.tf
# Este módulo "orquesta" otros módulos

module "red_interna" {
  source     = "../red"       # ruta relativa desde este módulo
  cidr_block = var.cidr_red
  nombre     = "${var.nombre_app}-red"
}

module "servidor_web" {
  source    = "../servidor"
  nombre    = "${var.nombre_app}-web"
  subnet_id = module.red_interna.subnet_id  # output del módulo de red
}

# Inicialización completa: descarga providers Y módulos
terraform init

# Salida típica cuando hay módulos:
# Initializing modules...
# - red in modules/networking
# - compute in modules/compute
# Downloading terraform-aws-modules/vpc/aws 5.1.2 for vpc...
# - vpc in .terraform/modules/vpc
#
# Initializing provider plugins...
# ...

# Descarga los módulos referenciados
terraform get

# Actualiza los módulos ya descargados a sus versiones más recientes
# (respetando las restricciones de version)
terraform get -update

# Ver versiones actuales descargadas
cat .terraform/modules/modules.json

# Actualizar módulos a la versión más reciente permitida
terraform get -update

# Tras actualizar, verificar el plan para ver qué cambia
terraform plan

{
  "Modules": [
    {
      "Key": "vpc",
      "Source": "registry.terraform.io/terraform-aws-modules/vpc/aws",
      "Version": "5.1.2",
      "Dir": ".terraform/modules/vpc"
    }
  ]
}

# main.tf — módulo raíz que orquesta la infraestructura completa

terraform {
  required_version = ">= 1.0"
  required_providers {
    local = {
      source  = "hashicorp/local"
      version = "~> 2.0"
    }
  }
}

# Módulo de "base de datos" (conceptual con archivos locales)
module "base_datos_dev" {
  source = "./modules/configuracion-app"

  nombre_aplicacion = "postgresql"
  directorio_destino = "/tmp/configs/dev/db"

  configuracion_servidor = {
    host    = "localhost"
    puerto  = 5432
    workers = 4
  }
  entorno = "development"
}

# Módulo de "API" que depende de la base de datos
module "api_dev" {
  source = "./modules/configuracion-app"

  nombre_aplicacion = "mi-api"
  directorio_destino = "/tmp/configs/dev/api"

  configuracion_servidor = {
    host    = "localhost"
    puerto  = 3000
    workers = 2
  }
  entorno = "development"

  # Dependencia explícita: la API se configura después de la BD
  depends_on = [module.base_datos_dev]
}

# Outputs del módulo raíz
output "archivos_creados" {
  value = {
    base_datos = module.base_datos_dev.resumen
    api        = module.api_dev.resumen
  }
}

# Nota: Este ejemplo requiere credenciales AWS configuradas.
# Lo incluimos como referencia de sintaxis real.

terraform {
  required_version = ">= 1.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "eu-west-1"
}

# -----------------------------------------------
# Módulo de VPC del registry oficial
# Documentación: registry.terraform.io/modules/terraform-aws-modules/vpc/aws
# -----------------------------------------------
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"

  name = "mi-proyecto-vpc"
  cidr = "10.0.0.0/16"

  # Zonas de disponibilidad donde crear subredes
  azs = ["eu-west-1a", "eu-west-1b", "eu-west-1c"]

  # Subredes privadas (sin acceso directo a internet)
  private_subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]

  # Subredes públicas (con acceso a internet via IGW)
  public_subnets = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]

  # Crear NAT Gateway para que las subredes privadas puedan acceder a internet
  enable_nat_gateway = true
  # Un solo NAT gateway para ahorrar costes (en producción usa uno por AZ)
  single_nat_gateway = true

  # Etiquetas aplicadas a todos los recursos del módulo
  tags = {
    Proyecto   = "mi-proyecto"
    Entorno    = "produccion"
    GestionPor = "terraform"
  }
}

# -----------------------------------------------
# Módulo de instancia EC2 del registry oficial
# -----------------------------------------------
module "servidor_web" {
  source  = "terraform-aws-modules/ec2-instance/aws"
  version = "~> 5.0"

  name = "servidor-web"

  # AMI de Amazon Linux 2023 (ejemplo, el ID varía por región)
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"

  # Usamos el output del módulo VPC para colocar el servidor en la subred correcta
  subnet_id              = module.vpc.public_subnets[0]
  vpc_security_group_ids = [aws_security_group.web.id]

  # Asignación de IP pública (necesario en subred pública)
  associate_public_ip_address = true

  tags = {
    Proyecto = "mi-proyecto"
    Rol      = "web-server"
  }
}

# Grupo de seguridad (definido directamente, no como módulo)
resource "aws_security_group" "web" {
  name   = "sg-web"
  vpc_id = module.vpc.vpc_id  # Output del módulo VPC

  ingress {
    from_port   = 80
    to_port     = 80
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

# Outputs del módulo raíz
output "vpc_id" {
  value = module.vpc.vpc_id
}

output "ip_servidor" {
  value = module.servidor_web.public_ip
}

# main.tf

terraform {
  required_version = ">= 1.0"
  required_providers {
    local = {
      source  = "hashicorp/local"
      version = "~> 2.0"
    }
  }
}

# Definimos los proyectos como un mapa de objetos.
# Esto nos permite usar for_each para crear todos los proyectos con una sola
# llamada al módulo.
locals {
  proyectos = {
    "portal-clientes" = {
      descripcion = "Portal web para gestión de clientes"
      version     = "3.1.0"
      autor       = "Equipo Frontend"
      caracteristicas = ["autenticacion-sso", "dashboard-analiticas", "exportacion-csv"]
    }
    "api-pagos" = {
      descripcion = "API de procesamiento de pagos"
      version     = "2.0.5"
      autor       = "Equipo Backend"
      caracteristicas = ["stripe-integration", "webhooks", "idempotencia"]
    }
    "worker-emails" = {
      descripcion = "Worker asíncrono para envío de emails"
      version     = "1.2.0"
      autor       = "Equipo Plataforma"
      caracteristicas = ["plantillas-html", "cola-reintentos", "tracking"]
    }
  }
}

# for_each en el bloque module: crea una instancia del módulo por cada proyecto.
# each.key es la clave del mapa (nombre del proyecto).
# each.value es el objeto con los datos del proyecto.
module "proyectos" {
  source   = "./modules/gestion-proyecto"
  for_each = local.proyectos

  # each.key contiene el nombre del proyecto (clave del mapa)
  nombre_proyecto = each.key

  # each.value contiene el objeto con los demás datos
  descripcion     = each.value.descripcion
  version         = each.value.version
  autor           = each.value.autor
  caracteristicas = each.value.caracteristicas
}

# Output: mapa de nombre_proyecto => directorio_base
# La expresión for transforma el mapa de módulos en un nuevo mapa.
output "directorios_proyectos" {
  description = "Mapa de proyectos a sus directorios base creados."
  value = {
    # k es el nombre del proyecto (each.key), v es la instancia del módulo
    for k, v in module.proyectos : k => v.directorio_base
  }
}

# Output: lista de todos los archivos README creados
output "todos_los_readme" {
  description = "Lista de rutas de todos los README.md creados."
  value = [
    for k, v in module.proyectos : v.ruta_readme
  ]
}

# Output: mapa completo con todos los detalles
output "resumen_completo" {
  description = "Información completa de todos los proyectos creados."
  value = {
    for k, v in module.proyectos : k => {
      directorio    = v.directorio_base
      readme        = v.ruta_readme
      configuracion = v.ruta_configuracion
    }
  }
}

# 1. Inicializar el proyecto
terraform init

# 2. Ver el plan: qué recursos se crearán
terraform plan

# Salida esperada del plan:
# Plan: 9 to add, 0 to change, 0 to destroy.
# (3 proyectos × 3 archivos cada uno = 9 archivos)

# 3. Aplicar los cambios
terraform apply -auto-approve

# 4. Ver los outputs
terraform output directorios_proyectos
# {
#   "api-pagos" = "/tmp/proyectos/api-pagos"
#   "portal-clientes" = "/tmp/proyectos/portal-clientes"
#   "worker-emails" = "/tmp/proyectos/worker-emails"
# }

terraform output todos_los_readme
# tolist([
#   "/tmp/proyectos/api-pagos/README.md",
#   "/tmp/proyectos/portal-clientes/README.md",
#   "/tmp/proyectos/worker-emails/README.md",
# ])

# 5. Verificar los archivos creados
ls /tmp/proyectos/
# api-pagos  portal-clientes  worker-emails

cat /tmp/proyectos/portal-clientes/README.md

# 6. Limpiar recursos cuando termines
terraform destroy -auto-approve

# Si necesitas el directorio de un proyecto específico:
output "directorio_api_pagos" {
  value = module.proyectos["api-pagos"].directorio_base
}

# Si necesitas verificar que una clave existe antes de usarla:
output "directorio_condicional" {
  value = contains(keys(module.proyectos), "api-pagos") ? module.proyectos["api-pagos"].directorio_base : "no existe"
}

Error: Module not installed

  on main.tf line 5:
   5: module "vpc" {

This module is not yet installed. Run "terraform init" to install all modules
required by this configuration.

# INCORRECTO: Terraform busca "modules/networking" en el registry público
module "red" {
  source = "modules/networking"  # ← falta ./
}

# CORRECTO
module "red" {
  source = "./modules/networking"
}

# PELIGROSO: sin version, usará siempre la última disponible
module "vpc" {
  source = "terraform-aws-modules/vpc/aws"
  # Si publican la versión 6.0 con breaking changes, tu infra se romperá
}

# CORRECTO
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"
}

Error: Unsupported attribute

  on main.tf line 25, in output "mi_output":
  25:   value = module.servidor.ip_privada

This object does not have an attribute named "ip_privada".

# Cambiar de esto:
module "servidor" {
  count = 2
  ...
}

# A esto:
module "servidor" {
  for_each = toset(["web", "api"])
  ...
}
# RESULTADO: Terraform destruye module.servidor[0], module.servidor[1]
# y crea module.servidor["web"], module.servidor["api"]
# ¡Puede causar downtime!

root/
├── main.tf
└── modules/
    ├── orquestador/
    │   └── main.tf        ← llama a ../networking
    └── networking/
        └── main.tf

# modules/orquestador/main.tf
module "red" {
  source = "../networking"   # Correcto: relativo a modules/orquestador/
  # NO: source = "./modules/networking"  (sería relativo al root)
}