Crea il tuo primo stack AWS CDK: un tutorial per principianti

Lavorare con i construct di CDK

Le app AWS CDK si basano sui construct come elementi strutturali essenziali. Quando padroneggi i construct, che tu usi quelli integrati dei servizi o crei pattern riutilizzabili, il tuo codice di infrastruttura diventa più modulare, manutenibile e leggibile.

Questa sezione ti insegna a usare i construct L2 (alto livello) e a sviluppare construct personalizzati che riducono i pattern ripetitivi.

Usare i construct L2

I construct L2 sono astrazioni native di CDK più semplici da usare rispetto a CloudFormation grezzo (L1). Hanno default sensati e type safety, spesso richiedono meno righe di codice per configurare una risorsa AWS.

Perché usare i construct L2?

• Meno boilerplate — meno campi obbligatori rispetto a L1
• Codice Python più leggibile e idiomatico
• Include metodi di utilità come .add_to_role_policy() o .add_event_notification()
• Gestisce automaticamente le dipendenze tra risorse

Esempio: Creare un bucket S3 usando L2

from aws_cdk import aws_s3 as s3
# Create a versioned and encrypted S3 bucket
bucket = s3.Bucket(
    self,
    "MyBucket",
    versioned=True,
    encryption=s3.BucketEncryption.S3_MANAGED
)

L'equivalente construct L1, s3.CfnBucket, richiederebbe di impostare manualmente tutte le proprietà e definire la configurazione come dict grezzi — molto meno intuitivo.

Altri comuni construct L2 includono:

• lambda_.Function() per AWS Lambda
• dynamodb.Table() per DynamoDB
• sqs.Queue() per SQS
• sns.Topic() per SNS

Creare construct personalizzati

La tua infrastruttura crescerà con pattern ricorrenti, come la creazione di funzioni Lambda con permessi specifici e bucket S3. I construct personalizzati sono la soluzione ideale in questo scenario.

I construct personalizzati ti permettono di combinare risorse correlate in un'unica unità logica, riutilizzabile tra stack o progetti.

Quando creare un construct personalizzato:

• Quando hai 3+ risorse sempre fornite insieme
• Quando vuoi incapsulare logica riutilizzabile
• Quando vuoi ridurre la duplicazione di codice tra stack

Esempio: un pattern riutilizzabile S3 + Lambda

from constructs import Construct
from aws_cdk import aws_s3 as s3, aws_lambda as lambda_
class StorageWithLambda(Construct):
    def __init__(self, scope: Construct, id: str) -> None:
        super().__init__(scope, id)
        # S3 bucket
        self.bucket = s3.Bucket(self, "MyBucket")

        # Lambda function
        self.function = lambda_.Function(
            self,
            "MyFunction",
            runtime=lambda_.Runtime.PYTHON_3_9,
            handler="index.handler",
            code=lambda_.Code.from_asset("lambda")
        )
        # Grant Lambda access to the S3 bucket
        self.bucket.grant_read_write(self.function)

Ora puoi usare questo construct in qualsiasi stack così:

from my_project.storage_with_lambda import StorageWithLambda
storage = StorageWithLambda(self, "ReusableComponent")

Prima di eseguire quanto sopra, crea una cartella chiamata lambda nella root del progetto e crea un file index.py con il seguente contenuto:

def handler(event, context):
    return {
        "statusCode": 200,
        "body": "Hello from Lambda!"
    }

Suggerimenti per la riutilizzabilità

• Prefissa i file con construct_ o inseriscili in una cartella constructs/
• Esporre output come self.bucket o self.function per flessibilità
• Mantieni ogni construct focalizzato su una sola responsabilità

Test e sintesi delle app CDK

Dopo aver scritto il codice della tua infrastruttura, è essenziale verificare cosa distribuirà CDK e, idealmente, testare che i tuoi stack si comportino come previsto. AWS CDK fornisce strumenti per sintetizzare template CloudFormation e scrivere test automatizzati per intercettare misconfigurazioni prima del deployment.

Sintetizzare i template

Il comando cdk synth genera il template CloudFormation dal tuo codice CDK.

cdk synth

Quando esegui questo comando, CDK:

• Carica la tua app (tramite app.py)
• Risolve tutti i construct e gli stack
• Produce template CloudFormation grezzi in YAML/JSON

Template CloudFormation sintetizzato 

Per impostazione predefinita, l'output va al terminale, ma puoi anche reindirizzarlo a un file se necessario:

cdk synth > template.yaml

Questo è utile quando:

• Vuoi ispezionare il template reale prima del deployment
• Stai facendo il debug della struttura di uno stack
• Condividi il template con team che non usano CDK

Testare l'infrastruttura

Anche se testare l'infrastructure as code può sembrare insolito, è molto utile, soprattutto quando i tuoi stack diventano grandi o includono logica condizionale, cicli o construct riutilizzabili.

AWS CDK offre il modulo assertions per testare gli stack sintetizzati.

Scrivere un test semplice con pytest

Ecco un test di esempio che verifica se uno specifico componente (come un bucket S3) è incluso nello stack:

# test/test_cdk_datacamp_stack.py
import aws_cdk as cdk
from aws_cdk.assertions import Template
from cdk_datacamp.cdk_datacamp_stack import CdkDatacampStack
def test_s3_bucket_created():
    app = cdk.App()
    stack = CdkDatacampStack(app, "TestStack")
    template = Template.from_stack(stack)
    # Assert that an S3 bucket exists
    template.resource_count_is("AWS::S3::Bucket", 1)

Per eseguire i test, assicurati che pytest sia installato:

pip install -U pytest

Poi esegui:

pytest

Se tutto passa, vedrai un segno di spunta verde. In caso contrario, l'output del test ti dirà cosa manca.

Output di Pytest che mostra l'esecuzione riuscita di tutti i casi di test per lo stack AWS CDK

Puoi anche includere validazioni nel tuo stack CDK. I test di validazione sono controlli a runtime all'interno del tuo codice di construct o stack che convalidano gli input prima del deployment. Aiutano a intercettare misconfigurazioni o a imporre vincoli nelle prime fasi del ciclo di sviluppo.

Poniamo di voler passare il bucket_name come variabile di contesto, ma vogliamo validare che:

• Il nome del bucket non sia vuoto
• Rispetti le regole di naming S3 (ad es., solo minuscole)

Crea un file chiamato test/test_storage_with_lambda.py e aggiungi quanto segue:

import pytest
from aws_cdk import App, Stack
from cdk_datacamp.storage_with_lambda import StorageWithLambda

def test_missing_bucket_name():
    app = App()
    stack = Stack(app, "TestStack")

    with pytest.raises(ValueError, match="bucket_name is required"):
        StorageWithLambda(stack, "FailingConstruct", bucket_name=None)

def test_bucket_name_uppercase():
    app = App()
    stack = Stack(app, "TestStack")

    with pytest.raises(ValueError, match="must be lowercase"):
        StorageWithLambda(stack, "FailingConstruct", bucket_name="InvalidName")

 Per testare la validazione, esegui il comando seguente:

test/test_storage_with_lambda.py

Output di Pytest che mostra l'esecuzione riuscita di tutti i casi di test per lo stack AWS CDK

Quando usare i test:

• Stai creando construct o pattern riutilizzabili.
• L'implementazione dei test serve a stabilire requisiti tecnici standard tra i membri del team.
• Vuoi intercettare regressioni o cambiamenti indesiderati durante il CI/CD.

Vuoi consolidare le tue conoscenze CDK in vista di un colloquio? Queste domande da colloquio su AWS DevOps possono aiutarti a prepararti.

Best practice e consigli per lavorare con AWS CDK

Dopo aver imparato a creare e distribuire stack CDK, dovresti seguire le best practice per mantenere il tuo codice di infrastruttura pulito, sicuro e scalabile. In questa sezione parleremo di come strutturare progetti grandi, gestire correttamente la sicurezza e integrare CDK nelle pipeline CI/CD.

Organizzare progetti di grandi dimensioni

Man mano che la tua app CDK cresce, diventa essenziale organizzare il codice in unità gestibili.

Usa più stack

Suddividi l'infrastruttura per ambito. Ad esempio:

• NetworkingStack: VPC, subnet, security group
• ComputeStack: EC2, Lambda
• StorageStack: S3, DynamoDB

Questo ti permette di distribuire, testare o eliminare parti della tua infrastruttura in modo indipendente. Ecco come può essere incluso in app.py:

network_stack = NetworkingStack(app, "NetworkingStack")
compute_stack = ComputeStack(app, "ComputeStack")

Puoi anche passare risorse tra stack usando output o riferimenti.

Crea construct annidati riutilizzabili

Incapsula risorse correlate (come una Lambda e i suoi permessi) in un construct personalizzato, come hai fatto con StorageWithLambda. Questo migliora la leggibilità e la riutilizzabilità tra stack o app.

Usa configurazioni specifiche per ambiente

Supporta più ambienti (dev, staging, prod) usando:

• cdk.json con valori di contesto
• Override da CLI: cdk deploy -c env=prod
• Logica condizionale nei tuoi stack

env = app.node.try_get_context("env")
if env == "prod":
    bucket_name = "mycompany-prod-logs"

Sicurezza e permessi

Qualsiasi progetto di infrastruttura deve dare priorità alla sicurezza durante i processi di distribuzione automatizzata con AWS CDK. La sezione seguente dimostra una gestione sicura delle risorse IAM attraverso i principi del privilegio minimo.

Definisci ruoli IAM invece di usare i default

I construct CDK, tra cui Lambda o i task ECS, creano automaticamente ruoli IAM. Anche se comodo, può limitare il controllo su permessi e naming.

Meglio definire i ruoli esplicitamente:

from aws_cdk import aws_iam as iam

execution_role = iam.Role(
    self,
    "LambdaExecutionRole",
    assumed_by=iam.ServicePrincipal("lambda.amazonaws.com"),
    description="Custom role for Lambda with least privilege",
    managed_policies=[
        iam.ManagedPolicy.from_aws_managed_policy_name("service-role/AWSLambdaBasicExecutionRole")
    ]
)

Questo ruolo consente solo il logging e nient'altro di default.

Applica il principio del privilegio minimo

Evita di usare "*" in actions o resources a meno che non sia strettamente necessario.

Esempio:

lambda_fn.add_to_role_policy(
    iam.PolicyStatement(
        actions=["*"],
        resources=["*"]
    )
)

Puoi anche usare grant specifici per risorsa quando disponibili:

bucket.grant_read(lambda_fn)

Questo genera automaticamente la policy necessaria con accesso limitato al bucket S3.

Usa policy gestite quando possibile

Le policy gestite da AWS semplificano la manutenzione e riducono la probabilità di errori.

iam.ManagedPolicy.from_aws_managed_policy_name("AmazonSQSReadOnlyAccess")

Puoi allegarle a ruoli personalizzati per servizi come ECS, Batch o Step Functions.

Integrazione CI/CD

AWS CDK offre una potenza notevole grazie alla sua capacità di integrarsi con pipeline CI/CD moderne. CDK supporta la consegna automatizzata dell'infrastruttura tramite distribuzione di codice sotto controllo versione, funzionando con GitHub, GitLab e servizi nativi AWS, tra cui CodePipeline. Il sistema riduce gli errori umani, accorcia i cicli di feedback e abilita il deployment su più ambienti.

GitHub Actions: automatizzare i deployment CDK

Puoi usare GitHub Actions per sintetizzare, confrontare, testare e distribuire gli stack CDK a ogni push o pull request.

Guarda questo .github/workflows/deploy.yml:

name: Deploy CDK App

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-python@v4
        with:
          python-version: 3.11

      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          npm install -g aws-cdk

      - name: Run unit tests
        run: pytest

      - name: CDK Synth
        run: cdk synth -c environment=prod

      - name: Deploy to AWS
        run: cdk deploy --require-approval never
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

Usa cdk diff nelle PR per visualizzare in anteprima le modifiche all'infrastruttura prima del merge.

CDK pipelines: CI/CD nativo CDK con CodePipeline

Per deployment completamente gestiti all'interno di AWS, CDK fornisce un modulo chiamato aws_cdk.pipelines, che ti consente di definire l'intera pipeline CI/CD come codice, proprio come l'infrastruttura.

Ecco un esempio semplificato:

from aws_cdk import pipelines, SecretValue, Stack
from constructs import Construct
from my_app_stage import MyAppStage  # replace with your actual stage import

class PipelineStack(Stack):
    def __init__(
        self,
        scope: Construct,
        construct_id: str,
        **kwargs
    ) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Define the source of the pipeline from a GitHub repository
        source = pipelines.CodePipelineSource.git_hub(
            repo_string="your-org/your-repo",  # GitHub org/repo
            branch="main",
            authentication=SecretValue.secrets_manager("GITHUB_TOKEN")
        )

        # Define the CodePipeline and its synthesis step
        pipeline = pipelines.CodePipeline(
            self,
            "MyAppPipeline",
            synth=pipelines.ShellStep(
                "Synth",
                input=source,
                commands=[
                    "pip install -r requirements.txt",
                    "npm install -g aws-cdk",
                    "cdk synth"
                ]
            )
        )

        # Add an application stage (e.g., production deployment)
        pipeline.add_stage(
            MyAppStage(self, "ProdStage")
        )

Nel codice sopra:

• SecretValue.secrets_manager("GITHUB_TOKEN") recupera in modo sicuro il tuo token GitHub da Secrets Manager.
• MyAppStage dovrebbe essere una classe che estende Stage e incapsula i tuoi stack CDK reali.

Se stai distribuendo sistemi di machine learning, l'integrazione di CDK con pratiche di continuous deployment è trattata nel nostro corso CI/CD for Machine Learning.

Conclusione

Questo tutorial ti ha mostrato come costruire e distribuire infrastruttura cloud in Python tramite le operazioni di AWS Cloud Development Kit (CDK). Hai imparato a:

• Creare il tuo primo stack CDK.
• Definire e validare bucket S3 e funzioni Lambda come risorse.
• Organizzare un progetto tramite construct personalizzati e pattern multi-stack.
• Applicare best practice di sicurezza secondo il principio del privilegio minimo.
• Automatizzare i deployment combinando GitHub Actions con CDK Pipelines.
• Scrivere test per validare la logica della tua infrastruttura.

Ora che hai distribuito la tua prima app CDK, ecco alcuni modi per fare un salto di qualità:

• Usa ambienti parametrizzati per dev/staging/prod
• Aggiungi CloudWatch Alarms, API Gateway o Step Functions
• Esplora construct CDK come aws_s3_deployment, aws_ecs_patterns e cdk.pipelines
• Converte i tuoi construct in una libreria Python interna per la riutilizzabilità

Per continuare a imparare e costruire, da' un'occhiata al corso Introduction to AWS Boto in Python!