Francesco Oghabi

Terraform Modules: Organizzare Codice Infrastrutturale

I Terraform modules rappresentano uno degli strumenti più potenti per organizzare, riutilizzare e gestire il codice infrastrutturale in modo efficiente. In questo articolo esploreremo come strutturare e implementare moduli Terraform per ottimizzare i workflow DevOps e garantire la scalabilità dell'infrastruttura as code.

Che cosa sono i Terraform Modules

Un modulo Terraform è essenzialmente un contenitore per più risorse che vengono utilizzate insieme. Ogni configurazione Terraform ha almeno un modulo, chiamato root module, che consiste nei file di configurazione nella directory principale. Un modulo può chiamare altri moduli, permettendo di includere le risorse figlio nella configurazione in modo modulare.

I moduli consentono di:

  • Organizzare la configurazione in componenti logici e riutilizzabili
  • Incapsulare gruppi di risorse dedicate a uno scopo specifico
  • Fornire un livello di astrazione che semplifica la gestione dell'infrastruttura
  • Standardizzare le configurazioni attraverso diversi ambienti
  • Facilitare la collaborazione tra team

Struttura di un Terraform Module

Un modulo Terraform ben strutturato segue convenzioni specifiche per garantire leggibilità e manutenibilità. La struttura base include:

my-module/
├── main.tf          # Contiene le risorse principali
├── variables.tf     # Dichiara le variabili di input
├── outputs.tf       # Definisce gli output del modulo
├── versions.tf      # Specifica le versioni dei provider
└── README.md        # Documentazione del modulo

File main.tf

Il file main.tf contiene le definizioni delle risorse principali del modulo. È buona pratica organizzare le risorse in modo logico e aggiungere commenti esplicativi:

# main.tf
resource "aws_vpc" "main" {
  cidr_block           = var.vpc_cidr
  enable_dns_hostnames = true
  enable_dns_support   = true

  tags = merge(var.tags, {
    Name = "${var.name}-vpc"
  })
}

resource "aws_subnet" "public" {
  count = length(var.public_subnet_cidrs)
  
  vpc_id                  = aws_vpc.main.id
  cidr_block              = var.public_subnet_cidrs[count.index]
  availability_zone       = data.aws_availability_zones.available.names[count.index]
  map_public_ip_on_launch = true

  tags = merge(var.tags, {
    Name = "${var.name}-public-${count.index + 1}"
    Type = "Public"
  })
}

File variables.tf

Il file variables.tf definisce tutte le variabili di input del modulo, includendo tipo, descrizione e valori di default quando appropriato:

# variables.tf
variable "name" {
  description = "Nome base per le risorse"
  type        = string
}

variable "vpc_cidr" {
  description = "CIDR block per la VPC"
  type        = string
  default     = "10.0.0.0/16"
}

variable "public_subnet_cidrs" {
  description = "Lista dei CIDR blocks per le subnet pubbliche"
  type        = list(string)
  default     = ["10.0.1.0/24", "10.0.2.0/24"]
}

variable "tags" {
  description = "Map di tag da applicare alle risorse"
  type        = map(string)
  default     = {}
}

File outputs.tf

Il file outputs.tf espone i valori che possono essere utilizzati da altri moduli o configurazioni:

# outputs.tf
output "vpc_id" {
  description = "ID della VPC creata"
  value       = aws_vpc.main.id
}

output "public_subnet_ids" {
  description = "Lista degli ID delle subnet pubbliche"
  value       = aws_subnet.public[*].id
}

output "vpc_cidr_block" {
  description = "CIDR block della VPC"
  value       = aws_vpc.main.cidr_block
}

Utilizzo dei Moduli

Per utilizzare un modulo nella configurazione Terraform, si utilizza il blocco module. I moduli possono essere caricati da diverse sorgenti:

Moduli Locali

Per utilizzare un modulo presente nel filesystem locale:

module "vpc" {
  source = "./modules/vpc"
  
  name               = "production"
  vpc_cidr          = "10.0.0.0/16"
  public_subnet_cidrs = ["10.0.1.0/24", "10.0.2.0/24"]
  
  tags = {
    Environment = "production"
    Owner      = "devops-team"
  }
}

Moduli dal Terraform Registry

È possibile utilizzare moduli pubblici dal Terraform Registry:

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

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

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

  enable_nat_gateway = true
  enable_vpn_gateway = true

  tags = {
    Terraform = "true"
    Environment = "production"
  }
}

Moduli da Repository Git

I moduli possono essere caricati direttamente da repository Git:

module "vpc" {
  source = "git::https://github.com/company/terraform-modules.git//vpc?ref=v1.2.0"
  
  name     = "staging"
  vpc_cidr = "10.1.0.0/16"
}

Best Practices per i Terraform Modules

Naming Convention

Adottare convenzioni di naming consistenti facilita la comprensione e la manutenzione:

  • Utilizzare nomi descrittivi per i moduli (es. vpc-with-nat, rds-postgres)
  • Prefissare le variabili con il contesto quando necessario
  • Utilizzare snake_case per variabili e output
  • Mantenere coerenza nei tag e nelle convenzioni di naming delle risorse

Versioning

Il versioning dei moduli è cruciale per garantire stabilità e controllo delle modifiche:

module "database" {
  source  = "git::https://github.com/company/tf-modules.git//database?ref=v2.1.0"
  # Sempre specificare una versione specifica per ambienti di produzione
  
  db_name     = "production_db"
  db_instance_class = "db.t3.medium"
}

Input Validation

Implementare validazione degli input per prevenire errori di configurazione:

variable "environment" {
  description = "Environment name"
  type        = string
  
  validation {
    condition = contains(["dev", "staging", "production"], var.environment)
    error_message = "Environment must be dev, staging, or production."
  }
}

variable "instance_count" {
  description = "Number of instances to create"
  type        = number
  default     = 1
  
  validation {
    condition     = var.instance_count > 0 && var.instance_count <= 10
    error_message = "Instance count must be between 1 and 10."
  }
}

Moduli Annidati e Composizione

I moduli possono utilizzare altri moduli, creando una gerarchia che permette composizioni complesse ma mantenibili:

# modules/application/main.tf
module "vpc" {
  source = "../vpc"
  
  name     = var.app_name
  vpc_cidr = var.vpc_cidr
  tags     = var.tags
}

module "database" {
  source = "../rds"
  
  vpc_id           = module.vpc.vpc_id
  subnet_ids       = module.vpc.private_subnet_ids
  db_name          = var.db_name
  db_instance_class = var.db_instance_class
  
  tags = var.tags
}

module "web_servers" {
  source = "../ec2-cluster"
  
  vpc_id              = module.vpc.vpc_id
  subnet_ids          = module.vpc.public_subnet_ids
  instance_count      = var.web_server_count
  instance_type       = var.web_instance_type
  database_endpoint   = module.database.endpoint
  
  tags = var.tags
}

Testing dei Moduli

Il testing è fondamentale per garantire l'affidabilità dei moduli. Esistono diversi approcci:

Terratest

Terratest è un framework Go per testare il codice infrastrutturale:

package test

import (
    "testing"
    "github.com/gruntwork-io/terratest/modules/terraform"
    "github.com/stretchr/testify/assert"
)

func TestVPCModule(t *testing.T) {
    terraformOptions := &terraform.Options{
        TerraformDir: "../examples/basic",
        Vars: map[string]interface{}{
            "name": "test-vpc",
            "vpc_cidr": "10.0.0.0/16",
        },
    }

    defer terraform.Destroy(t, terraformOptions)
    terraform.InitAndApply(t, terraformOptions)

    vpcId := terraform.Output(t, terraformOptions, "vpc_id")
    assert.NotEmpty(t, vpcId)
}

Directory examples/

Creare esempi di utilizzo facilita il testing e la documentazione:

my-module/
├── examples/
│   ├── basic/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   └── advanced/
│       ├── main.tf
│       ├── variables.tf
│       └── outputs.tf
├── main.tf
├── variables.tf
└── outputs.tf

Registry di Moduli Privati

Per organizzazioni che necessitano di moduli privati, Terraform Cloud e Terraform Enterprise offrono registry privati. È anche possibile implementare soluzioni self-hosted:

Struttura del Repository

terraform-aws-vpc/
├── README.md
├── main.tf
├── variables.tf
├── outputs.tf
├── versions.tf
└── examples/
    └── basic/
        ├── main.tf
        └── outputs.tf

Tagging per Versioning

Utilizzare tag Git semantici per le versioni:

git tag -a "v1.0.0" -m "Initial release"
git tag -a "v1.1.0" -m "Added support for multiple AZs"
git push origin --tags

Troubleshooting Comune

Circular Dependencies

Evitare dipendenze circolari tra moduli strutturando la gerarchia in modo appropriato:

Problema Soluzione
Modulo A dipende da B che dipende da A Estrarre le dipendenze comuni in un modulo separato
Riferimenti circolari tra output e input Utilizzare data sources o risorse intermedie

Gestione dello State

Ogni modulo mantiene il proprio stato nel context del modulo chiamante. Per moduli complessi, considerare l'uso di backend remoti:

terraform {
  backend "s3" {
    bucket = "company-terraform-state"
    key    = "modules/vpc/terraform.tfstate"
    region = "us-west-2"
  }
}

Conclusioni

I Terraform modules rappresentano un elemento fondamentale per la gestione scalabile dell'infrastruttura as code. La loro corretta implementazione permette di ottenere codice più organizzato, riutilizzabile e manutenibile. Attraverso l'adozione delle best practices discusse - dalla strutturazione dei file alla gestione delle versioni, dal testing alla documentazione - è possibile costruire un ecosistema di moduli robusto che facilita la collaborazione tra team e accelera il deployment dell'infrastruttura.

L'investimento iniziale nella progettazione e nell'organizzazione dei moduli ripaga significativamente nel lungo termine, riducendo la duplicazione del codice, minimizzando gli errori e garantendo consistenza tra diversi ambienti. Con l'evolversi dell'infrastruttura cloud e delle pratiche DevOps, i moduli Terraform rimangono uno strumento indispensabile per professionisti IT che vogliono mantenere controllo e flessibilità nella gestione dell'infrastruttura moderna.