Infrastruttura CDK

AWS CDK è un framework per definire infrastrutture cloud tramite codice e provisionarle 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 Checkov.

Utilizzo

Genera 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.
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 deployare
  • Directorystages Definizioni degli stage CDK

    • application-stage.ts Definisce una collezione di stack da deployare 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
• checkov.yml File di configurazione Checkov

Consiglio

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

Implementare la tua infrastruttura CDK

Puoi iniziare a scrivere la tua infrastruttura CDK in 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 sviluppo e testing.

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 definire stage beta e prod che deployano su 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 da deployare insieme. 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 l'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 usato i generatori tRPC API o FastAPI, noterai dei costrutti disponibili in packages/common/constructs per deployarli.

Ad esempio, se hai creato un’API tRPC chiamata my-api, puoi importare e istanziare il costrutto per aggiungere l’infrastruttura necessaria:

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 infrastruttura per la tua API
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

Infrastruttura per website

Se hai usato il generatore CloudScape website, troverai un costrutto in packages/common/constructs per il deploy. 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 infrastruttura per il website
    new MyWebsite(this, 'MyWebsite');
  }
}

È importante dichiarare il website dopo eventuali costrutti API per includere tutta la configurazione API nel Runtime Config del website.

Sintetizzare l’infrastruttura

Oltre ai target predefiniti di compilazione, lint e test, il target build sintetizza l’infrastruttura in CloudFormation. Puoi eseguire questa operazione separatamente con 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 l’assembly cloud sintetizzato nella cartella dist principale, sotto dist/packages/<my-infra-project>/cdk.out.

Test di sicurezza

Il target checkov esegue controlli di sicurezza sull’infrastruttura usando Checkov.

pnpm

pnpm nx run <my-infra>:checkov

yarn

yarn nx run <my-infra>:checkov

npm

npx nx run <my-infra>:checkov

bun

bunx nx run <my-infra>:checkov

I risultati dei test si trovano nella cartella dist principale, sotto dist/packages/<my-infra-project>/checkov.

Nota

Checkov viene eseguito con uvx, devi installare uv se non l’hai già fatto.

Attenzione

Alcune regole Checkov sono disabilitate di default via file checkov.yml. Si raccomanda di revisionarle in base al caso d’uso.

Disabilitare regole Checkov

Puoi disabilitare regole specifiche in due modi:

Disabilitare una regola su un costrutto

import { suppressRules } from ':my-scope/common-constructs';

// sopprime la regola CKV_AWS_XXX per il costrutto
suppressRules(construct, ['CKV_AWS_XXX'], 'Motivazione');

Disabilitare una regola su costrutti discendenti

import { suppressRules } from ':my-scope/common-constructs';

// Sopprime CKV_AWS_XXX per il costrutto o suoi discendenti se sono istanze di Bucket
suppressRules(construct, ['CKV_AWS_XXX'], 'Motivazione', (construct) => construct instanceof Bucket);

Bootstrap dell’account AWS

Per deployare un’applicazione CDK in un account AWS per la prima volta, è necessario eseguire il bootstrap.

Prima, configura le credenziali per il tuo account AWS.

Poi usa il comando cdk bootstrap:

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

Per dettagli, consulta la documentazione CDK.

Deploy su AWS

Dopo una build, puoi deployare l’infrastruttura con il target deploy.

Attenzione

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

Prima, configura le credenziali per il tuo account AWS.

Poi esegui:

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 deploya tutti gli stack dello stage <my-infra>-sandbox. Puoi specificare altri stage definiti in main.ts.

Puoi anche deployare singoli stack specificando il nome completo:

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

Deploy su AWS in pipeline CI/CD

Usa il target deploy-ci per deploy in 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 utilizza l’assembly cloud pre-sintetizzato invece di sintetizzarlo al volo, evitando problemi di non-determinismo legati alle versioni dei pacchetti.

Rimozione dell’infrastruttura AWS

Usa il target destroy per rimuovere le 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 dettagli su CDK, consulta la CDK Developer Guide e l’API Reference.