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:

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

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

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	string	-	Il nome del progetto.
type	application | library	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.
preferInstallDependencies	boolean	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 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
  • init.ts Esegue terraform init con la configurazione del backend S3
• 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
• 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"
}

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"
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 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

Formattare il tuo codice

Formatta il tuo codice Terraform utilizzando 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 sulla tua infrastruttura utilizzando Checkov con 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 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.

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

Ulteriori informazioni

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