Construye tu primera pila CDK de AWS: Un tutorial para principiantes

Trabajar con constructos CDK

Las aplicaciones AWS CDK se basan en construcciones como elementos estructurales esenciales. El código de tu infraestructura será más modular, mantenible y legible cuando domines las construcciones, tanto si utilizas construcciones de servicio incorporadas como si creas tus propios patrones reutilizables.

Esta sección te enseña a utilizar construcciones L2 (de alto nivel) y a desarrollar construcciones personalizadas que reduzcan los patrones repetitivos.

Utilizar constructos L2

Las construcciones L2 son abstracciones nativas de CDK más fáciles de usar que CloudFormation en bruto (L1). Tienen valores predeterminados sensatos y seguridad de tipos, y a menudo requieren menos líneas de código para configurar un recurso de AWS.

¿Por qué utilizar construcciones L2?

• Menos repeticiones: menos campos obligatorios en comparación con la L1
• Código Python más legible e idiomático
• Incluye métodos de utilidad como .add_to_role_policy() o .add_event_notification()
• Gestiona automáticamente las dependencias entre recursos

Ejemplo: Crear un bucket S3 utilizando 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
)

La construcción L1 equivalente, s3.CfnBucket, necesitaría que todas las propiedades se establecieran manualmente y que la configuración se definiera como dictos sin procesar, lo que es mucho menos intuitivo.

Otras construcciones comunes de L2 son

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

Crear construcciones personalizadas

Tu infraestructura se ampliará con patrones recurrentes, como la creación de funciones Lambda con permisos y buckets S3 particulares. Las construcciones personalizadas son la solución ideal para este escenario concreto.

Las construcciones personalizadas te permiten combinar recursos relacionados en una única unidad lógica, que puede reutilizarse en pilas o proyectos.

Cuándo crear una construcción personalizada:

• Cuando tienes más de 3 recursos que siempre se aprovisionan juntos
• Cuando quieras encapsular lógica reutilizable
• Cuando quieras reducir la duplicación de código entre pilas

Ejemplo: Un patrón reutilizable 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)

Ahora puedes utilizar esta construcción dentro de cualquier pila como ésta:

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

Antes de ejecutar lo anterior, crea una carpeta llamada lambda en la raíz del proyecto y crea un archivo index.py con el siguiente contenido:

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

Consejos de reutilización

• Prefija los archivos con construct_ o colócalos dentro de una carpeta constructs/
• Exponer salidas como self.bucket o self.function para mayor flexibilidad
• Mantén cada construcción centrada en una responsabilidad

Probar y sintetizar aplicaciones CDK

Después de escribir el código de tu infraestructura, es esencial comprobar qué desplegará el CDK e idealmente probar que tus pilas se comportan como se espera. El CDK de AWS proporciona herramientas para sintetizar plantillas de CloudFormation y escribir pruebas automatizadas para detectar errores de configuración antes del despliegue.

Plantillas de síntesis

El comando cdk synth genera la plantilla de CloudFormation a partir de tu código CDK.

cdk synth

Cuando ejecutes esto, el CDK:

• Carga tu aplicación (a través de app.py)
• Resuelve todas las construcciones y pilas
• Genera plantillas de CloudFormation YAML/JSON sin procesar

Plantilla CloudFormation sintetizada 

Por defecto, la salida va a tu terminal, pero también puedes enviarla a un archivo si es necesario:

cdk synth > template.yaml

Esto es útil cuando:

• Quieres inspeccionar la plantilla real antes de desplegarla
• Estás depurando la estructura de una pila
• Estás compartiendo la plantilla con equipos que no utilizan CDK

Infraestructura de pruebas

Aunque probar la infraestructura como código puede sonar inusual, es beneficioso, especialmente cuando tus pilas son grandes o incluyen lógica condicional, bucles o construcciones reutilizables.

El CDK de AWS ofrece el módulo de aserciones para probar las pilas sintetizadas.

Escribir una prueba sencilla con pytest

Aquí tienes un ejemplo de prueba que comprueba si un recurso específico (como un bucket S3) está incluido en la pila:

# 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)

Para realizar las pruebas, asegúrate de que pytest está instalado:

pip install -U pytest

Entonces corre:

pytest

Si todo pasa, verás una marca de verificación verde. Si no es así, el resultado de la prueba te dirá lo que falta.

Salida de Pytest que muestra la ejecución correcta de todos los casos de prueba para la pila CDK de AWS

También puedes incluir la validación en tu pila CDK. Las pruebas de validación son comprobaciones en tiempo de ejecución dentro de tu código de construcción o apilamiento que validan las entradas antes de que se produzca el despliegue. Ayudan a detectar errores de configuración o a imponer restricciones en las primeras fases del ciclo de vida del desarrollo.

Digamos que queremos pasar el bucket_name como variable de contexto, pero queremos validarlo:

• El nombre del cubo no está vacío
• Cumple las normas de denominación del S3 (por ejemplo, sólo en minúsculas)

Crea un archivo llamado test/test_storage_with_lambda.py y añade lo siguiente:

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

 Para probar la validación, ejecuta el siguiente comando:

test/test_storage_with_lambda.py

Salida de Pytest que muestra la ejecución correcta de todos los casos de prueba para la pila CDK de AWS

Cuándo utilizar las pruebas:

• Estás creando construcciones o patrones reutilizables.
• La realización de pruebas sirve para establecer requisitos técnicos estándar entre los miembros del equipo.
• Quieres detectar regresiones o cambios no intencionados durante el CI/CD.

¿Quieres reforzar tus conocimientos sobre CDK en una entrevista? Estas preguntas de entrevista sobre AWS DevOps pueden ayudarte a prepararte.

Buenas prácticas y consejos para trabajar con el CDK de AWS

Después de dominar la creación y despliegue de la pila CDK, debes seguir las mejores prácticas para mantener el código de tu infraestructura limpio, seguro y escalable. Esta sección tratará sobre cómo estructurar grandes proyectos, gestionar correctamente la seguridad e integrar CDK en las canalizaciones CI/CD.

Organizar grandes proyectos

A medida que crece tu aplicación CDK, resulta esencial organizar el código en unidades manejables.

Utiliza pilas múltiples

Divide tu infraestructura por intereses. Por ejemplo:

• RedStack: VPCs, subredes, grupos de seguridad
• ComputeStack: EC2, Lambda
• StorageStack: S3, DynamoDB

Esto te permite desplegar, probar o destruir partes de tu infraestructura de forma independiente. He aquí cómo se puede incluir en app.py:

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

También puedes pasar recursos entre pilas utilizando salidas o referencias.

Crear construcciones anidadas reutilizables

Encapsula los recursos relacionados (como una Lambda y sus permisos) en una construcción personalizada, como hiciste con StorageWithLambda. Esto mejora la legibilidad y la reutilización entre pilas o aplicaciones.

Utilizar la configuración específica del entorno

Soporta múltiples entornos (dev, staging, prod) utilizando:

• cdk.json con valores de contexto
• Anulaciones CLI: cdk deploy -c env=prod
• Lógica condicional en tus pilas

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

Seguridad y permisos

Cualquier proyecto de infraestructura debe dar prioridad a la seguridad durante los procesos de despliegue automatizado del CDK de AWS. La siguiente sección demuestra la gestión segura de recursos IAM a través de los principios del mínimo privilegio.

Definir roles IAM en lugar de utilizar los predeterminados

Las construcciones CDK, que incluyen tareas Lambda o ECS, crearán automáticamente roles IAM. Aunque es cómodo, puede limitar tu control sobre los permisos y los nombres.

En lugar de eso, define las funciones explícitamente:

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

Este rol sólo permite el registro y nada más por defecto.

Aplicar el principio del menor privilegio

Evita utilizar "*" en actions o resources a menos que sea absolutamente necesario.

Ejemplo:

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

También puedes utilizar subvenciones para recursos específicos cuando estén disponibles:

bucket.grant_read(lambda_fn)

Esto genera automáticamente la política necesaria con acceso de alcance al bucket S3.

Utiliza políticas gestionadas cuando sea posible

Las políticas gestionadas por AWS simplifican el mantenimiento y reducen la posibilidad de errores.

iam.ManagedPolicy.from_aws_managed_policy_name("AmazonSQSReadOnlyAccess")

Puedes adjuntarlas a roles personalizados para servicios como ECS, Lote o Funciones por Pasos.

Integración CI/CD

El CDK de AWS ofrece una potencia excepcional gracias a su capacidad para integrarse con las canalizaciones CI/CD contemporáneas. CDK admite la entrega automatizada de infraestructura mediante el despliegue de código controlado por versiones, que funciona con GitHub, GitLab y servicios nativos de AWS, incluido CodePipeline. El sistema disminuye los errores humanos al tiempo que acorta los ciclos de retroalimentación y permite el despliegue en múltiples entornos.

Acciones en GitHub: Automatizar las implantaciones de CDK

Puedes utilizar las Acciones de GitHub para sintetizar, diferenciar, probar y desplegar pilas CDK en cada push o pull request.

Echa un vistazo a este .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 }}

Utiliza cdk diff en los PR para previsualizar los cambios infra antes de fusionarlos.

Canalizaciones CDK: CDK nativo CI/CD con CodePipeline

Para despliegues totalmente gestionados en AWS, CDK proporciona un módulo llamado aws_cdk.pipelines, que te permite definir toda tu canalización CI/CD como código, igual que la infraestructura.

He aquí un ejemplo simplificado:

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

En el código anterior:

• SecretValue.secrets_manager("GITHUB_TOKEN") extrae de forma segura tu token de GitHub del Gestor de Secretos.
• MyAppStage debe ser una clase que extienda Stage y envuelva tus pilas CDK reales.

Si estás desplegando sistemas de machine learning, la integración de CDK con las prácticas de despliegue continuo se trata en nuestro curso CI/CD para machine learning.

Conclusión

Este tutorial te ha enseñado a construir y desplegar infraestructuras en la nube en Python a través de las operaciones del Kit de Desarrollo en la Nube (CDK) de AWS. Aprendiste a hacerlo:

• Crea tu primera pila CDK.
• Define y valida los buckets de S3 y las funciones Lambda como recursos.
• Organiza un proyecto mediante construcciones personalizadas y patrones multipila.
• Aplica las mejores prácticas de seguridad mediante el principio del mínimo privilegio.
• Automatiza los despliegues combinando GitHub Actions con CDK Pipelines.
• Escribe pruebas para validar la lógica de tu infraestructura.

Ahora que ya has desplegado tu primera aplicación CDK, aquí tienes algunas formas de subir de nivel:

• Utilizar entornos parametrizados para dev/staging/prod
• Añade alarmas CloudWatch, API Gateway o funciones de paso
• Explora construcciones CDK como aws_s3_deployment, aws_ecs_patterns, y cdk.pipelines
• Convierte tus construcciones en una biblioteca interna de Python para reutilizarlas

Para seguir aprendiendo y construyendo¡el curso Introducción a AWS Boto en Python!