Infrastruttura Terraform

Terraform è uno strumento open-source per l’infrastruttura come codice che ti permette di creare, modificare e migliorare l’infrastruttura in modo sicuro e prevedibile.

Il generatore di infrastruttura Terraform crea un progetto di infrastruttura Terraform. L’applicazione generata include best practice di sicurezza attraverso i controlli di sicurezza di Checkov.

Utilizzo

Genera un Progetto Terraform

Puoi generare un nuovo progetto Terraform in due modi:

VSCode

1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - terraform#project
5. Compila i parametri richiesti
   • name: tf-infra
6. Clicca su Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=tf-infra

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=tf-infra

npm

npx nx g @aws/nx-plugin:terraform#project --name=tf-infra

bun

bunx nx g @aws/nx-plugin:terraform#project --name=tf-infra

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=tf-infra --dry-run

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=tf-infra --dry-run

npm

npx nx g @aws/nx-plugin:terraform#project --name=tf-infra --dry-run

bun

bunx nx g @aws/nx-plugin:terraform#project --name=tf-infra --dry-run

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	string	-	Il nome del progetto.
type	string	application	Se si tratta di una libreria terraform (moduli riutilizzabili) o di un'app (distribuibile).
directory	string	packages	La directory del nuovo progetto.
subDirectory	string	-	La sottodirectory in cui viene posizionato il progetto. Per impostazione predefinita corrisponde al nome del progetto.

Output del Generatore

Il generatore crea strutture di file diverse in base al tipo di progetto:

type = application

Tipo Applicazione

Per progetti di applicazione (--type=application), il generatore crea un’applicazione Terraform completa con gestione dello stato remoto:

• Directorysrc

  • main.tf File di configurazione principale Terraform
  • providers.tf Configurazione provider con backend S3
  • variables.tf Definizioni variabili di input
  • outputs.tf Definizioni valori di output
  • Directoryenv File di variabili specifici per ambiente

    • dev.tfvars Variabili ambiente di sviluppo
• Directorybootstrap Configurazione bootstrap per stato remoto

  • main.tf Bucket S3 e politiche per lo storage dello stato
  • providers.tf Configurazione provider AWS
  • variables.tf Definizioni variabili bootstrap
• Directoryscripts Helper Node eseguiti dai target nx bootstrap e init

  • aws-config.ts Risolve account + regione tramite la catena di credenziali AWS SDK
  • bootstrap.ts Effettua pull/push del tfstate bootstrap ed esegue terraform apply
  • init.ts Esegue terraform init con la configurazione backend S3
• project.json Configurazione progetto e target di build

Moduli Terraform condivisi

Il generatore crea anche una libreria packages/common/terraform che inizialmente aggiunge solo un modulo metrics (crea uno stack Cloudformation vuoto con metadati) automaticamente strumentato per permettere al team nx-plugin-for-aws di tracciare le metriche di utilizzo.

type = library

Tipo Libreria

Per progetti libreria (--type=library), il generatore crea una struttura più semplice per moduli Terraform riutilizzabili:

• Directorysrc

  • main.tf File principale modulo Terraform
• project.json Configurazione progetto e target di build

Applicazione vs libreria

I progetti applicazione includono capacità di deployment completo con gestione stato remoto, mentre i progetti libreria sono pensati per creare moduli Terraform riutilizzabili consumabili da altri progetti.

Implementare la tua Infrastruttura Terraform

Puoi iniziare a scrivere la tua infrastruttura Terraform in src/main.tf, ad esempio:

src/main.tf

locals {
  account_id = data.aws_caller_identity.current.account_id
  aws_region = data.aws_region.current.id
}

resource "null_resource" "print_info" {
  # triggers = {
  #   always_run = timestamp()
  # }

  provisioner "local-exec" {
    command = "echo 'AWS Region: ${local.aws_region}, AWS Account: ${local.account_id}, Environment: ${var.environment}'"
  }
}

# Dichiarare la propria infrastruttura qui
resource "aws_s3_bucket" "my_bucket" {
  bucket = "my-unique-bucket-name"
}

Dipendenze cross-project

Se vuoi eseguire un modulo da un progetto separato (lib), puoi farlo così:

module "lib_module" {
  source = "../../path/to/my-lib/src"
}

Questo aggiornerà automaticamente il grafo Nx per aggiungere una dipendenza tra la tua applicazione consumer e la tua lib.

Configurazione Ambiente

Configura le variabili specifiche per ambiente nei file src/env/*.tfvars.

Per aggiungere nuovi ambienti, crea un nuovo file src/env/<environment>.tfvars con le variabili specifiche e aggiungi nuove voci per apply, destroy, init, plan nel project.json per la nuova configurazione ambiente. Ad esempio, aggiungiamo un ambiente prod:

src/env/prod.tfvars

# Variabili ambiente produzione
environment = "prod"
region      = "us-west-2"

project.json

{
  "targets": {
        "apply": {
            "executor": "nx:run-commands",
            "defaultConfiguration": "dev",
            "configurations": {
                "dev": {
                    "command": "terraform apply ../../../dist/packages/infra/terraform/dev.tfplan"
                },
                "prod": {
                    "command": "terraform apply ../../../dist/packages/infra/terraform/prod.tfplan"
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd": "{projectRoot}/src"
            },
            "dependsOn": ["plan"]
        },
        "destroy": {
            "executor": "nx:run-commands",
            "defaultConfiguration": "dev",
            "configurations": {
                "dev": {
                    "command": "terraform destroy -var-file=env/dev.tfvars"
                },
                "prod": {
                    "command": "terraform destroy -var-file=env/prod.tfvars"
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd":"{projectRoot}/src"
            },
            "dependsOn": ["init"]
        },
        "init": {
            "executor": "nx:run-commands",
            "defaultConfiguration": "dev",
            "configurations": {
                "dev": {
                    "env": { "TF_ENV": "dev" }
                },
                "prod": {
                    "env": { "TF_ENV": "prod" }
                }
            },
            "options": {
                "forwardAllArgs": true,
                "commands": ["tsx {projectRoot}/scripts/init.ts {projectRoot}"],
                "cwd": "{workspaceRoot}"
            }
        },
        "plan": {
            "executor": "nx:run-commands",
            "defaultConfiguration": "dev",
            "configurations": {
                "dev": {
                    "command": "terraform plan -var-file=env/dev.tfvars -out=../../../dist/packages/infra/terraform/dev.tfplan"
                },
                "prod": {
                    "command": "terraform plan -var-file=env/dev.tfvars -out=../../../dist/packages/infra/terraform/prod.tfplan"
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd": "{projectRoot}/src"
            },
            "dependsOn": ["init"]
        }
    }
}

Ambiente predefinito

Per default tutti i target assumono l’ambiente dev, ma puoi specificare un ambiente con:

• pnpm
• yarn
• npm
• bun

pnpm nx apply tf-infra --configuration=prod

yarn nx apply tf-infra --configuration=prod

npx nx apply tf-infra --configuration=prod

bunx nx apply tf-infra --configuration=prod

Puoi cambiare ambiente in qualsiasi momento poiché lo stato separa automaticamente il tfstate tra ambienti.

type = application

Bootstrap Stato Remoto (Solo Progetti Applicazione)

Prima di deployare l’infrastruttura devi eseguire il bootstrap del backend per lo stato remoto. Questo crea un bucket S3 per archiviare i file di stato Terraform:

pnpm

pnpm nx bootstrap tf-infra

yarn

yarn nx bootstrap tf-infra

npm

npx nx bootstrap tf-infra

bun

bunx nx bootstrap tf-infra

Configurazione del profilo AWS

Assicurati che il profilo AWS CLI sia configurato per l’account/regione in cui vuoi deployare le risorse bootstrap.

Il target bootstrap è disponibile solo per progetti di tipo applicazione. I progetti libreria non richiedono gestione stato remoto essendo moduli riutilizzabili.

Target Disponibili

I target disponibili dipendono dal tipo di progetto:

Target Comuni (Applicazione e Libreria)

Convalida della tua Infrastruttura

Puoi validare la configurazione Terraform con il target validate:

pnpm

pnpm nx validate tf-infra

yarn

yarn nx validate tf-infra

npm

npx nx validate tf-infra

bun

bunx nx validate tf-infra

Formattazione del Codice

Formatta il codice Terraform con il target fmt:

pnpm

pnpm nx fmt tf-infra

yarn

yarn nx fmt tf-infra

npm

npx nx fmt tf-infra

bun

bunx nx fmt tf-infra

Test di Sicurezza

Esegui controlli di sicurezza sull’infrastruttura con Checkov usando il target test:

pnpm

pnpm nx test tf-infra

yarn

yarn nx test tf-infra

npm

npx nx test tf-infra

bun

bunx nx test tf-infra

Troverai i risultati dei test di sicurezza nella cartella dist principale, sotto dist/packages/<my-terraform-project>/checkov.

type = application

Target Solo Applicazione

I seguenti target sono disponibili solo per progetti di tipo applicazione:

Pianificazione dell’Infrastruttura

Prima di applicare modifiche, puoi vedere cosa farà Terraform con il target plan:

pnpm

pnpm nx plan tf-infra

yarn

yarn nx plan tf-infra

npm

npx nx plan tf-infra

bun

bunx nx plan tf-infra

Questo creerà un file di plan in dist/packages/<my-terraform-project>/terraform/dev.tfplan.

Inizializzazione Terraform

Inizializza la directory di lavoro Terraform con il target init:

pnpm

pnpm nx run tf-infra:init

yarn

yarn nx run tf-infra:init

npm

npx nx run tf-infra:init

bun

bunx nx run tf-infra:init

Deploy su AWS

Dopo la pianificazione, puoi deployare l’infrastruttura su AWS con il target apply:

pnpm

pnpm nx apply tf-infra

yarn

yarn nx apply tf-infra

npm

npx nx apply tf-infra

bun

bunx nx apply tf-infra

Approvazione automatica

Il comando sopra applica il plan creato dal target plan. Assicurati di eseguire prima plan per verificare le modifiche.

Alias Deploy

Un target deploy è disponibile anche come alias per apply. Puoi usare indifferentemente

• pnpm
• yarn
• npm
• bun

pnpm nx deploy tf-infra

yarn nx deploy tf-infra

npx nx deploy tf-infra

bunx nx deploy tf-infra

o

pnpm

pnpm nx apply tf-infra

yarn

yarn nx apply tf-infra

npm

npx nx apply tf-infra

bun

bunx nx apply tf-infra

.

Ottenere Output

Recupera i valori di output dalla configurazione Terraform:

pnpm

pnpm nx output tf-infra

yarn

yarn nx output tf-infra

npm

npx nx output tf-infra

bun

bunx nx output tf-infra

Distruzione Infrastruttura

Per eliminare l’infrastruttura, usa il target destroy:

pnpm

pnpm nx destroy tf-infra

yarn

yarn nx destroy tf-infra

npm

npx nx destroy tf-infra

bun

bunx nx destroy tf-infra

Operazione distruttiva

Questo eliminerà permanentemente tutte le risorse gestite da questa configurazione Terraform. Usa con cautela!

Distruzione Risorse Bootstrap

Per eliminare le risorse bootstrap (bucket S3 per lo stato):

pnpm

pnpm nx bootstrap-destroy tf-infra

yarn

yarn nx bootstrap-destroy tf-infra

npm

npx nx bootstrap-destroy tf-infra

bun

bunx nx bootstrap-destroy tf-infra

Ulteriori Informazioni

Per maggiori informazioni su Terraform, consulta la Documentazione Terraform e la Documentazione AWS Provider.