Infrastruttura Terraform

Terraform è uno strumento software open-source di infrastructure as code che consente 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 le best practice di sicurezza attraverso i controlli di sicurezza di Checkov.

Utilizzo

Generare un progetto Terraform

Puoi generare un nuovo progetto Terraform in due modi:

Esegui questo generatore@aws/nx-plugin:terraform#project

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:terraform#project

yarn

$ yarn nx g @aws/nx-plugin:terraform#project

npm

$ npx nx g @aws/nx-plugin:terraform#project

bun

$ bunx nx g @aws/nx-plugin:terraform#project

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
6. Clicca su Generate

Componi il tuo comando5

nameObbligatorio

type

applicationlibrary

directory

subDirectory

preferInstallDependencies

true

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Opzioni

Opzioni del generatore5 opzioni

nameObbligatoriostring

Il nome del progetto.

typeenumPredefinito: application

Se si tratta di una libreria terraform (moduli riutilizzabili) o di un'app (distribuibile).

applicationlibrary

directorystringPredefinito: packages

La directory del nuovo progetto.

subDirectorystring

La sottodirectory in cui viene posizionato il progetto. Per impostazione predefinita corrisponde al nome del progetto.

preferInstallDependenciesbooleanPredefinito: true

Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del generatore

Il generatore crea diverse strutture di file a seconda del tipo di progetto:

type = application

Tipo Application

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

• Directorysrc

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

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

  • main.tf Bucket S3 e policy per l’archiviazione dello stato
  • providers.tf Configurazione del provider AWS
  • variables.tf Definizioni delle variabili di bootstrap
• Directoryscripts Helper Node eseguiti dai target nx bootstrap, bootstrap-destroy e init

  • aws-config.ts Risolve account + regione tramite la catena di credenziali AWS SDK
  • bootstrap.ts Esegue pull/push del tfstate di bootstrap ed esegue terraform apply
  • bootstrap-destroy.ts Svuota il bucket di stato ed esegue terraform destroy
  • init.ts Esegue terraform init con la configurazione del backend S3
  • env.ts Punta terraform init alla cache condivisa dei provider
• checkov.yml Configurazione di Checkov, inclusi i controlli da saltare
• project.json Configurazione del progetto e target di build

Moduli Terraform condivisi

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

type = library

Tipo Library

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

• Directorysrc

  • main.tf File del modulo Terraform principale
• checkov.yml Configurazione di Checkov, inclusi i controlli da saltare
• project.json Configurazione del progetto e target di build

Application vs Library

I progetti application includono funzionalità di deployment complete con gestione dello stato remoto, mentre i progetti library sono progettati per creare moduli Terraform riutilizzabili che possono essere utilizzati da altri progetti.

Implementare la tua infrastruttura Terraform

Puoi iniziare a scrivere la tua infrastruttura Terraform all’interno di src/main.tf, per 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}'"
  }
}

# Declare your infrastructure here
resource "aws_s3_bucket" "my_bucket" {
  bucket = "my-unique-bucket-name"
}

Nota che il bucket S3 sopra fallirebbe la scansione di sicurezza Checkov, che verifica che il bucket abbia le impostazioni di sicurezza appropriate abilitate.

Dipendenze tra progetti

Se volessi eseguire un modulo da un progetto separato (lib), potresti farlo come segue:

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

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

Configurazione dell’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 per l’ambiente e aggiungi nuove voci per apply, destroy, init, plan nel project.json per la nuova configurazione dell’ambiente. Per esempio, supponiamo di voler aggiungere un ambiente prod:

src/env/prod.tfvars

# Production environment variables
environment = "prod"
aws_region  = "us-west-2"

Nomi delle variabili

Ogni nome che imposti qui deve essere dichiarato in src/variables.tf — il generatore dichiara aws_region e environment.

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/prod.tfvars -out=../../../dist/packages/infra/terraform/prod.tfplan"
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd": "{projectRoot}/src"
            },
            "dependsOn": ["init"]
        }
    }
}

Ambiente predefinito

Per impostazione predefinita, tutti i target assumono l’ambiente dev, tuttavia puoi indirizzare un ambiente specifico come segue:

• 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 anche cambiare ambiente in qualsiasi momento poiché lo stato segmenta automaticamente il tfstate tra gli ambienti.

type = application

Bootstrap dello stato remoto (solo progetti Application)

Prima di distribuire la tua infrastruttura, dovrai eseguire il bootstrap del backend dello stato remoto. Questo crea un bucket S3 per archiviare i tuoi 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 tuo profilo AWS CLI sia configurato per l’account/regione in cui desideri distribuire le risorse di bootstrap.

Il target bootstrap è disponibile solo per i progetti di tipo application. I progetti library non richiedono la gestione dello stato remoto poiché sono progettati per essere moduli riutilizzabili.

Target disponibili

I target disponibili dipendono dal tipo di progetto:

Target comuni (sia Application che Library)

Validare la tua infrastruttura

Puoi validare la tua configurazione Terraform utilizzando 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

Linting

I progetti Terraform utilizzano terraform fmt per verificare la formattazione.

Eseguire il Linter

Per invocare il linter per controllare il tuo progetto, puoi eseguire il target lint.

pnpm

pnpm nx lint tf-infra

yarn

yarn nx lint tf-infra

npm

npx nx lint tf-infra

bun

bunx nx lint tf-infra

Correggere i problemi di Lint

La maggior parte dei problemi di linting o formattazione può essere corretta automaticamente eseguendo con l’argomento --configuration=fix.

pnpm

pnpm nx lint tf-infra --configuration=fix

yarn

yarn nx lint tf-infra --configuration=fix

npm

npx nx lint tf-infra --configuration=fix

bun

bunx nx lint tf-infra --configuration=fix

Allo stesso modo, se desideri correggere tutti i problemi di lint in tutti i pacchetti nel tuo workspace, puoi eseguire:

pnpm

pnpm nx run-many --target lint --all --configuration=fix

yarn

yarn nx run-many --target lint --all --configuration=fix

npm

npx nx run-many --target lint --all --configuration=fix

bun

bunx nx run-many --target lint --all --configuration=fix

Comando abbreviato

Questo ha un comando abbreviato dalla radice del tuo workspace:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Saltare i problemi di Lint

Per evitare che i problemi di linting ti rallentino durante lo sviluppo (in particolare se hai problemi non correggibili automaticamente nel tuo progetto), puoi eseguire una build con la configurazione skip-lint:

pnpm

pnpm nx run-many --target build --configuration=skip-lint

yarn

yarn nx run-many --target build --configuration=skip-lint

npm

npx nx run-many --target build --configuration=skip-lint

bun

bunx nx run-many --target build --configuration=skip-lint

Questo salta completamente il controllo di formattazione durante la build.

Comando abbreviato

Questo ha un comando abbreviato dalla radice del tuo workspace:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint

Test di sicurezza

Esegui controlli di sicurezza sulla tua infrastruttura utilizzando Checkov con il target checkov:

pnpm

pnpm nx checkov tf-infra

yarn

yarn nx checkov tf-infra

npm

npx nx checkov tf-infra

bun

bunx nx checkov tf-infra

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

Checkov viene eseguito come parte di build.

I controlli sono configurati nel file checkov.yml del progetto. Aggiungi un id di controllo a skip-check per sopprimerlo nell’intero progetto:

checkov.yml

skip-check:
  - CKV_AWS_115 # Concurrent execution limit
  - CKV_AWS_116 # Dead Letter Queue

Per sopprimere un controllo per una singola risorsa invece, aggiungi un commento #checkov:skip=<id>:<reason> all’interno del blocco della risorsa:

resource "aws_s3_bucket" "example" {
  #checkov:skip=CKV_AWS_18:Access logging not required for this bucket
  bucket = "example"
}

Eseguire i test Terraform

Il target test esegue il framework di test nativo di Terraform su qualsiasi file .tftest.hcl nel tuo progetto:

pnpm

pnpm nx test tf-infra

yarn

yarn nx test tf-infra

npm

npx nx test tf-infra

bun

bunx nx test tf-infra

Un progetto senza file di test è un successo senza operazioni, quindi puoi aggiungere test quando ne hai bisogno. build esegue questo target, quindi i tuoi test vengono eseguiti come parte di una build normale.

Ogni blocco run valuta la tua configurazione. Usa command = plan per verificare cosa farebbe Terraform (questo espande l’intero grafo dei moduli, quindi cattura errori in fase di pianificazione che validate non può rilevare), oppure command = apply per creare risorse reali e fare asserzioni sui loro output. Dichiarare mock_provider significa che non vengono effettuate chiamate API e non sono necessarie credenziali AWS, il che mantiene i test plan veloci e sicuri da eseguire in CI:

src/main.tftest.hcl

mock_provider "aws" {
  mock_data "aws_caller_identity" {
    defaults = { account_id = "123456789012" }
  }
  mock_data "aws_region" {
    defaults = { region = "us-east-1" }
  }
}

variables {
  aws_region  = "us-east-1"
  environment = "dev"
}

run "plan_is_valid" {
  command = plan

  assert {
    condition     = data.aws_caller_identity.current.account_id == "123456789012"
    error_message = "Unexpected account id"
  }
}

Imposta ogni variabile richiesta dalla tua configurazione nel blocco variables, altrimenti l’esecuzione fallisce con “has a required variable … with no set value”.

Ogni target che esegue terraform init riutilizza una cache dei provider in .terraform/plugin-cache nella radice del tuo workspace, quindi i provider vengono scaricati una sola volta anziché ad ogni esecuzione. Ogni progetto ottiene la propria directory lì: due esecuzioni di terraform init che riempiono una cache contemporaneamente possono ciascuna calcolare un hash diverso per lo stesso provider, che terraform poi rifiuta confrontandolo con il tuo .terraform.lock.hcl. Consulta la documentazione Terraform per ulteriori informazioni.

Imposta TF_PLUGIN_CACHE_DIR nel tuo ambiente per puntare lo script init fornito a una cache che gestisci tu stesso — ad esempio un volume condiviso tra workspace. Nota che il target test legge il suo percorso da project.json, quindi modificalo anche lì.

type = application

Target solo per Application

I seguenti target sono disponibili solo per i progetti di tipo application:

Pianificare la tua infrastruttura

Prima di applicare le modifiche, puoi vedere cosa farà Terraform eseguendo 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 piano in dist/packages/<my-terraform-project>/terraform/dev.tfplan.

plan dipende da assemble, quindi produce gli artefatti a cui fanno riferimento i tuoi moduli, come i bundle Lambda e i metadati delle operazioni generate, senza eseguire i gate di lint, test e type-check.

Usa build nella tua pipeline

assemble viene utilizzato per un’iterazione più rapida durante lo sviluppo. Esegui build nella tua pipeline CI per assicurarti che il tuo progetto superi i gate di qualità prima di un deployment in produzione.

Inizializzare Terraform

Inizializza la tua 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

Distribuire su AWS

Dopo la pianificazione, puoi distribuire la tua infrastruttura su AWS utilizzando 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

Auto-Approve

Il comando sopra applica il piano creato dal target plan. Assicurati di eseguire prima plan per rivedere 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 gli output

Recupera i valori di output dalla tua 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

Distruggere l’infrastruttura

Quando devi smantellare la tua 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!

Distruggere le risorse di bootstrap

Per pulire le risorse di bootstrap (bucket S3 per l’archiviazione dello 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

Questo svuota il bucket di stato prima di distruggerlo e risolve la regione dalla catena di credenziali AWS SDK, quindi viene eseguito in modo automatico in CI.

Distruggi prima la tua infrastruttura

Il bucket di stato contiene lo stato per ogni ambiente, quindi esegui destroy per ogni ambiente prima di questo. Una volta che il bucket è stato eliminato, Terraform non conosce più le risorse che ha creato.

Ulteriori informazioni

Per ulteriori informazioni su Terraform, consulta la Documentazione Terraform e la Documentazione del provider AWS.