Infrastruttura CDK

AWS CDK è un framework per definire l’infrastruttura cloud tramite codice e provisionarla attraverso AWS CloudFormation.

Il generatore di infrastruttura TypeScript crea un’applicazione AWS CDK scritta in TypeScript. L’applicazione generata include best practice di sicurezza attraverso controlli CFN Guard.

Utilizzo

Generare un Progetto di Infrastruttura

Puoi generare un nuovo progetto di infrastruttura 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 - ts#infra
5. Compila i parametri richiesti
6. Clicca su Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#infra

yarn

yarn nx g @aws/nx-plugin:ts#infra

npm

npx nx g @aws/nx-plugin:ts#infra

bun

bunx nx g @aws/nx-plugin:ts#infra

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:ts#infra --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#infra --dry-run

npm

npx nx g @aws/nx-plugin:ts#infra --dry-run

bun

bunx nx g @aws/nx-plugin:ts#infra --dry-run

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	string	-	The name of the application.
ruleSet	string	aws_prototyping	Rule set to validate your AWS resources with.
directory	string	packages	The directory of the new application.

Output del Generatore

Il generatore creerà la seguente struttura del progetto nella directory <directory>/<name>:

• Directorysrc

  • main.ts Punto d’ingresso dell’applicazione che istanzia gli stage CDK da distribuire
  • Directorystages Definizioni degli stage CDK

    • application-stage.ts Definisce una collezione di stack da distribuire in uno stage
  • Directorystacks Definizioni degli stack CDK

    • application-stack.ts Stack applicativo principale
• cdk.json Configurazione CDK
• project.json Configurazione del progetto e target di build

Consiglio

La tua infrastruttura è un progetto TypeScript, quindi puoi consultare la documentazione sui progetti TypeScript per maggiori dettagli sull’utilizzo generale.

Implementare la tua Infrastruttura CDK

Puoi iniziare a scrivere la tua infrastruttura CDK all’interno di src/stacks/application-stack.ts, ad esempio:

src/stacks/application-stack.ts

import { Stack, StackProps } from 'aws-cdk-lib';
import { Bucket } from 'aws-cdk-lib/aws-s3'
import { Construct } from 'constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    // Dichiarare la propria infrastruttura qui
    new Bucket(this, 'MyBucket');
  }
}

Stage e Stack

Noterai che il file principale src/main.ts istanzia uno Stage CDK chiamato <namespace>-sandbox. Questo stage è pensato per il tuo sviluppo e testing personale.

src/main.ts

new ApplicationStage(app, 'project-sandbox', {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT,
    region: process.env.CDK_DEFAULT_REGION,
  },
});

Puoi aggiungere altri stage, ad esempio potresti voler definire stage beta e prod che distribuiscono in ambienti separati:

src/main.ts

new ApplicationStage(app, 'project-beta', {
  env: {
    account: '123456789012', // account beta
    region: 'us-west-2',
  },
});
new ApplicationStage(app, 'project-prod', {
  env: {
    account: '098765432109', // account prod
    region: 'us-west-2',
  },
});

Uno Stage definisce una collezione di stack che dovrebbero essere distribuiti insieme per comporre la tua applicazione. Puoi istanziare quanti stack desideri all’interno di uno stage, ad esempio:

src/stages/application-stage.ts

import { Stage, StageProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { BackendStack } from '../stacks/backend-stack.js';
import { FrontendStack } from '../stacks/frontend-stack.js';

/**
 * Definisce una collezione di stack CDK che compongono la tua applicazione
 */
export class ApplicationStage extends Stage {
  constructor(scope: Construct, id: string, props?: StageProps) {
    super(scope, id, props);

    new BackendStack(this, 'Backend', {
      crossRegionReferences: true,
    })

    new FrontendStack(this, 'Frontend', {
      crossRegionReferences: true,
    });
  }
}

Infrastruttura per API

Se hai utilizzato i generatori tRPC API o FastAPI per creare API, noterai che hai già alcuni costrutti disponibili in packages/common/constructs per distribuirle.

Se, ad esempio, hai creato un’API tRPC chiamata my-api, puoi semplicemente importare e istanziare il costrutto per aggiungere tutta l’infrastruttura necessaria alla sua distribuzione:

src/stacks/application-stack.ts

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyApi } from ':my-scope/common-constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Aggiungi l'infrastruttura per la tua API
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

Infrastruttura per Siti Web

Se hai utilizzato il generatore CloudScape website, noterai che hai già un costrutto in packages/common/constructs per distribuirlo. Ad esempio:

src/stacks/application-stack.ts

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite } from ':my-scope/common-constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Aggiungi l'infrastruttura per il tuo sito web
    new MyWebsite(this, 'MyWebsite');
  }
}

È importante assicurarsi che il sito web sia dichiarato dopo eventuali costrutti API affinché la Configurazione Runtime del sito includa tutte le configurazioni delle API.

Sintetizzare la tua Infrastruttura

Come parte del target build, oltre ad eseguire i target predefiniti di compilazione, lint e test, il tuo progetto di infrastruttura viene sintetizzato in CloudFormation. Questo può essere eseguito anche in modo autonomo, lanciando il target synth:

pnpm

pnpm nx run <my-infra>:synth

yarn

yarn nx run <my-infra>:synth

npm

npx nx run <my-infra>:synth

bun

bunx nx run <my-infra>:synth

Troverai la tua cloud assembly sintetizzata nella cartella root dist, sotto dist/packages/<my-infra-project>/cdk.out.

Bootstrap del tuo Account AWS

Se stai distribuendo un’applicazione CDK in un account AWS per la prima volta, sarà necessario eseguire il bootstrap.

Prima, assicurati di aver configurato le credenziali per il tuo account AWS.

Successivamente, puoi usare il comando cdk bootstrap:

npx cdk bootstrap aws://<account-id>/<region>

Per maggiori dettagli, consulta la documentazione CDK.

Distribuire su AWS

Dopo una build, puoi distribuire la tua infrastruttura su AWS usando il target deploy.

Attenzione

Usa il target deploy-ci se distribuisci in una pipeline CI/CD. Vedi sotto per dettagli.

Prima, assicurati di aver configurato le credenziali per il tuo account AWS.

Successivamente, esegui il target deploy:

pnpm

pnpm nx run <my-infra>:deploy <my-infra>-sandbox/*

yarn

yarn nx run <my-infra>:deploy <my-infra>-sandbox/*

npm

npx nx run <my-infra>:deploy <my-infra>-sandbox/*

bun

bunx nx run <my-infra>:deploy <my-infra>-sandbox/*

Consiglio

Il comando sopra distribuisce tutti gli stack per lo stage <my-infra>-sandbox. Puoi specificare altri stage purché siano definiti in main.ts.

Puoi anche distribuire singoli stack specificando il nome completo dello stack, ad esempio:

pnpm

pnpm nx run <my-infra>:deploy <my-infra>-sandbox/Application

yarn

yarn nx run <my-infra>:deploy <my-infra>-sandbox/Application

npm

npx nx run <my-infra>:deploy <my-infra>-sandbox/Application

bun

bunx nx run <my-infra>:deploy <my-infra>-sandbox/Application

Distribuire su AWS in una Pipeline CI/CD

Usa il target deploy-ci se stai distribuendo su AWS come parte di una pipeline CI/CD.

pnpm

pnpm nx run <my-infra>:deploy-ci my-stage/*

yarn

yarn nx run <my-infra>:deploy-ci my-stage/*

npm

npx nx run <my-infra>:deploy-ci my-stage/*

bun

bunx nx run <my-infra>:deploy-ci my-stage/*

Questo target differisce leggermente dal normale target deploy in quanto garantisce la distribuzione di una cloud-assembly pre-sintetizzata, invece di sintetizzarla al volo. Questo aiuta a evitare potenziali problemi di non-determinismo dovuti a cambiamenti nelle versioni dei pacchetti, assicurando che ogni fase della pipeline distribuisca usando la stessa cloud-assembly.

Rimuovere l’Infrastruttura AWS

Usa il target destroy per rimuovere le tue risorse:

pnpm

pnpm nx run <my-infra>:destroy <my-infra>-sandbox/*

yarn

yarn nx run <my-infra>:destroy <my-infra>-sandbox/*

npm

npx nx run <my-infra>:destroy <my-infra>-sandbox/*

bun

bunx nx run <my-infra>:destroy <my-infra>-sandbox/*

Ulteriori Informazioni

Per maggiori informazioni su CDK, consulta la Guida per Sviluppatori CDK e il Riferimento API.