Esta es la guía para AWS CDK desarrolladores de la versión 2. La primera versión del CDK pasó a la etapa de mantenimiento el 1.° de junio de 2022 y no cuenta con soporte desde el 1.° de junio de 2023.
Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
En este tutorial, utilizarás el AWS Cloud Development Kit (AWS CDK) para crear un servidor sencillo Hello World aplicación que implementa un backend de API básico compuesto por lo siguiente:
-
Amazon API Gateway REST API— Proporciona un punto final HTTP que se utiliza para invocar su función a través de un HTTP GET solicitud.
-
AWS Lambda función: función que devuelve un
Hello World!
mensaje cuando se invoca con HTTP punto final. -
Integraciones y permisos: detalles de configuración y permisos para que tus recursos interactúen entre sí y realicen acciones, como escribir registros en Amazon CloudWatch.
El siguiente diagrama muestra los componentes de esta aplicación:

Para este tutorial, creará e interactuará con su aplicación en los siguientes pasos:
-
Crea un AWS CDK proyecto.
-
Defina una función Lambda y una API REST de API Gateway mediante construcciones L2 de la biblioteca Construct. AWS
-
Implemente su aplicación en. Nube de AWS
-
Interactúe con su aplicación en el Nube de AWS.
-
Elimina la aplicación de muestra de la Nube de AWS.
Temas
Requisitos previos
Antes de comenzar este tutorial, debe completar lo siguiente:
-
Cree un Cuenta de AWS e instale y configure el AWS Command Line Interface (AWS CLI).
-
Instalación Node.js y npm.
-
Instale el kit de herramientas de CDK a nivel mundial, utilizando
npm install -g aws-cdk
.
Para obtener más información, consulte Empezando con la AWS CDK.
Se recomienda tener conocimientos básicos sobre:
-
¿Qué es el AWS CDK?para obtener una introducción básica a AWS CDK.
-
Aprenda los conceptos AWS CDK básicos para obtener una descripción general de los conceptos básicos del AWS CDK.
Paso 1: cómo crear un proyecto
En este paso, se crea un nuevo proyecto de CDK mediante el AWS CDK CLI comando cdk init
Crear un proyecto CDK
-
Desde un directorio inicial de su elección, cree y navegue a un directorio de proyecto llamado
cdk-hello-world
en su máquina:$
mkdir cdk-hello-world && cd cdk-hello-world
-
Para crear un nuevo proyecto en su lenguaje de programación preferido, use el comando
cdk init
:$
cdk init --language typescript
Instale las AWS CDK bibliotecas:
$
npm install aws-cdk-lib constructs
El CDK. CLI crea un proyecto con la siguiente estructura:
cdk-hello-world ├── .git ├── .gitignore ├── .npmignore ├── README.md ├── bin │ └── cdk-hello-world.ts ├── cdk.json ├── jest.config.js ├── lib │ └── cdk-hello-world-stack.ts ├── node_modules ├── package-lock.json ├── package.json ├── test │ └── cdk-hello-world.test.ts └── tsconfig.json
El CDK. CLI crea automáticamente una aplicación CDK que contiene una sola pila. La instancia de la aplicación de CDK se crea a partir de la clase App
. La siguiente es una parte del archivo de la aplicación de CDK:
Se encuentra en bin/cdk-hello-world.ts
:
#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from 'aws-cdk-lib';
import { CdkHelloWorldStack } from '../lib/cdk-hello-world-stack';
const app = new cdk.App();
new CdkHelloWorldStack(app, 'CdkHelloWorldStack', {
});
Paso 2: cómo crear su función de Lambda
Dentro de su proyecto de CDK, cree un directorio lambda
que incluya un archivo nuevo hello.js
. A continuación, se muestra un ejemplo:
Desde la raíz del proyecto, ejecute lo siguiente:
$
mkdir lambda && cd lambda
$
touch hello.js
Ahora debería agregarse lo siguiente a su proyecto de CDK:
cdk-hello-world
└── lambda
└── hello.js
nota
Para que este tutorial sea sencillo, utilizamos un JavaScript Función Lambda para todos los lenguajes de programación CDK.
Para definir la función de Lambda, agregue lo siguiente al archivo recién creado:
exports.handler = async (event) => {
return {
statusCode: 200,
headers: { "Content-Type": "text/plain" },
body: JSON.stringify({ message: "Hello, World!" }),
};
};
Paso 3: cómo definir las construcciones
En este paso, definirá sus recursos de Lambda y API Gateway mediante construcciones AWS CDK L2.
Abra el archivo del proyecto que define su pila CDK. Modificará este archivo para definir sus constructos fijos. A continuación se muestra un ejemplo del archivo de pila inicial:
Se encuentra en lib/cdk-hello-world-stack.ts
:
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
export class CdkHelloWorldStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Your constructs will go here
}
}
En este archivo, hace AWS CDK lo siguiente:
-
Su instancia de pila CDK se crea a partir de la clase
Stack
. -
La clase
Constructs
base se importa y se proporciona como ámbito o elemento principal de la instancia de la pila.
Defina activos de la función de Lambda
Para definir su activo de la función de Lambda, importe y utilice el constructo L2 aws-lambda
de la Biblioteca de constructos de AWS .
Modifique el archivo de pila de la siguiente manera:
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
// Import Lambda L2 construct
import * as lambda from 'aws-cdk-lib/aws-lambda';
export class CdkHelloWorldStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Define the Lambda function resource
const helloWorldFunction = new lambda.Function(this, 'HelloWorldFunction', {
runtime: lambda.Runtime.NODEJS_20_X, // Choose any supported Node.js runtime
code: lambda.Code.fromAsset('lambda'), // Points to the lambda directory
handler: 'hello.handler', // Points to the 'hello' file in the lambda directory
});
}
}
A continuación, se crea un activo de función de Lambda y se definen las siguientes propiedades:
-
runtime
– El entorno en el que se ejecuta la función. En este caso, utilizamos Node.js versión 20.x. -
code
– La ruta del código de la función en su máquina local. -
handler
– El nombre del archivo que contiene el código de la función.
Defina su API Gateway REST API recurso
Para definir su API Gateway REST API recurso, se importa y se utiliza la construcción aws-apigateway
L2 de la biblioteca AWS Construct.
Modifique el archivo de pila de la siguiente manera:
// ...
//Import API Gateway L2 construct
import * as apigateway from 'aws-cdk-lib/aws-apigateway';
export class CdkHelloWorldStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// ...
// Define the API Gateway resource
const api = new apigateway.LambdaRestApi(this, 'HelloWorldApi', {
handler: helloWorldFunction,
proxy: false,
});
// Define the '/hello' resource with a GET method
const helloResource = api.root.addResource('hello');
helloResource.addMethod('GET');
}
}
Aquí, se crea una API Gateway REST API recurso, junto con lo siguiente:
-
Una integración entre REST API y su función Lambda, lo que permite a la API invocar su función. Esto incluye la creación de un activo de permisos de Lambda.
-
Un nuevo nombre de activo o ruta
hello
que se agrega a la raíz del punto de conexión de la API. Esto crea un nuevo punto final que se suma/hello
a su base URL. -
Un método GET para el recurso
hello
. Cuando se envía una solicitud GET al punto de conexión/hello
de Lambda, se invoca la función de Lambda y se devuelve su respuesta.
Paso 4: cómo preparar la aplicación para su implementación
En este paso, debe preparar la aplicación para su implementación mediante la creación, si es necesario, y la validación básica con el AWS CDK CLI comando cdk synth
Si es necesario, cree la aplicación:
Desde la raíz del proyecto, ejecute lo siguiente:
$
npm run build
Ejecute cdk synth
para sintetizar una AWS CloudFormation plantilla a partir de su código CDK. Al utilizar construcciones de nivel 2, muchos de los detalles de configuración necesarios AWS CloudFormation para facilitar la interacción entre la función Lambda y REST API los aprovisiona para usted el. AWS CDK
Desde la raíz del proyecto, ejecute lo siguiente:
$
cdk synth
nota
Si recibe un error como el siguiente, verifique que se encuentra en el directorio cdk-hello-world
e inténtelo de nuevo:
--app is required either in command-line, in cdk.json or in ~/.cdk.json
Si tiene éxito, el AWS CDK CLI generará la AWS CloudFormation plantilla en YAML formatear en la línea de comandos. A JSON la plantilla formateada también se guarda en el cdk.out
directorio.
A continuación se muestra un ejemplo de salida de la AWS CloudFormation plantilla:
Resources:
HelloWorldFunctionServiceRoleunique-identifier
:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Statement:
- Action: sts:AssumeRole
Effect: Allow
Principal:
Service: lambda.amazonaws.com
Version: "2012-10-17"
ManagedPolicyArns:
- Fn::Join:
- ""
- - "arn:"
- Ref: AWS::Partition
- :iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldFunction/ServiceRole/Resource
HelloWorldFunctionunique-identifier
:
Type: AWS::Lambda::Function
Properties:
Code:
S3Bucket:
Fn::Sub: cdk-unique-identifier
-assets-${AWS::AccountId}-${AWS::Region}
S3Key: unique-identifier
.zip
Handler: hello.handler
Role:
Fn::GetAtt:
- HelloWorldFunctionServiceRoleunique-identifier
- Arn
Runtime: nodejs20.x
DependsOn:
- HelloWorldFunctionServiceRoleunique-identifier
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldFunction/Resource
aws:asset:path: asset.unique-identifier
aws:asset:is-bundled: false
aws:asset:property: Code
HelloWorldApiunique-identifier
:
Type: AWS::ApiGateway::RestApi
Properties:
Name: HelloWorldApi
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldApi/Resource
HelloWorldApiDeploymentunique-identifier
:
Type: AWS::ApiGateway::Deployment
Properties:
Description: Automatically created by the RestApi construct
RestApiId:
Ref: HelloWorldApiunique-identifier
DependsOn:
- HelloWorldApihelloGETunique-identifier
- HelloWorldApihellounique-identifier
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldApi/Deployment/Resource
HelloWorldApiDeploymentStageprod012345ABC
:
Type: AWS::ApiGateway::Stage
Properties:
DeploymentId:
Ref: HelloWorldApiDeploymentunique-identifier
RestApiId:
Ref: HelloWorldApiunique-identifier
StageName: prod
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldApi/DeploymentStage.prod/Resource
HelloWorldApihellounique-identifier
:
Type: AWS::ApiGateway::Resource
Properties:
ParentId:
Fn::GetAtt:
- HelloWorldApiunique-identifier
- RootResourceId
PathPart: hello
RestApiId:
Ref: HelloWorldApiunique-identifier
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldApi/Default/hello/Resource
HelloWorldApihelloGETApiPermissionCdkHelloWorldStackHelloWorldApiunique-identifier
:
Type: AWS::Lambda::Permission
Properties:
Action: lambda:InvokeFunction
FunctionName:
Fn::GetAtt:
- HelloWorldFunctionunique-identifier
- Arn
Principal: apigateway.amazonaws.com
SourceArn:
Fn::Join:
- ""
- - "arn:"
- Ref: AWS::Partition
- ":execute-api:"
- Ref: AWS::Region
- ":"
- Ref: AWS::AccountId
- ":"
- Ref: HelloWorldApi9E278160
- /
- Ref: HelloWorldApiDeploymentStageprodunique-identifier
- /GET/hello
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldApi/Default/hello/GET/ApiPermission.CdkHelloWorldStackHelloWorldApiunique-identifier
.GET..hello
HelloWorldApihelloGETApiPermissionTestCdkHelloWorldStackHelloWorldApiunique-identifier
:
Type: AWS::Lambda::Permission
Properties:
Action: lambda:InvokeFunction
FunctionName:
Fn::GetAtt:
- HelloWorldFunctionunique-identifier
- Arn
Principal: apigateway.amazonaws.com
SourceArn:
Fn::Join:
- ""
- - "arn:"
- Ref: AWS::Partition
- ":execute-api:"
- Ref: AWS::Region
- ":"
- Ref: AWS::AccountId
- ":"
- Ref: HelloWorldApiunique-identifier
- /test-invoke-stage/GET/hello
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldApi/Default/hello/GET/ApiPermission.Test.CdkHelloWorldStackHelloWorldApiunique-identifier
.GET..hello
HelloWorldApihelloGETunique-identifier
:
Type: AWS::ApiGateway::Method
Properties:
AuthorizationType: NONE
HttpMethod: GET
Integration:
IntegrationHttpMethod: POST
Type: AWS_PROXY
Uri:
Fn::Join:
- ""
- - "arn:"
- Ref: AWS::Partition
- ":apigateway:"
- Ref: AWS::Region
- :lambda:path/2015-03-31/functions/
- Fn::GetAtt:
- HelloWorldFunctionunique-identifier
- Arn
- /invocations
ResourceId:
Ref: HelloWorldApihellounique-identifier
RestApiId:
Ref: HelloWorldApiunique-identifier
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldApi/Default/hello/GET/Resource
CDKMetadata:
Type: AWS::CDK::Metadata
Properties:
Analytics: v2:deflate64:unique-identifier
Metadata:
aws:cdk:path: CdkHelloWorldStack/CDKMetadata/Default
Condition: CDKMetadataAvailable
Outputs:
HelloWorldApiEndpointunique-identifier
:
Value:
Fn::Join:
- ""
- - https://
- Ref: HelloWorldApiunique-identifier
- .execute-api.
- Ref: AWS::Region
- "."
- Ref: AWS::URLSuffix
- /
- Ref: HelloWorldApiDeploymentStageprodunique-identifier
- /
Conditions:
CDKMetadataAvailable:
Fn::Or:
- Fn::Or:
- Fn::Equals:
- Ref: AWS::Region
- af-south-1
- Fn::Equals:
- Ref: AWS::Region
- ap-east-1
- Fn::Equals:
- Ref: AWS::Region
- ap-northeast-1
- Fn::Equals:
- Ref: AWS::Region
- ap-northeast-2
- Fn::Equals:
- Ref: AWS::Region
- ap-south-1
- Fn::Equals:
- Ref: AWS::Region
- ap-southeast-1
- Fn::Equals:
- Ref: AWS::Region
- ap-southeast-2
- Fn::Equals:
- Ref: AWS::Region
- ca-central-1
- Fn::Equals:
- Ref: AWS::Region
- cn-north-1
- Fn::Equals:
- Ref: AWS::Region
- cn-northwest-1
- Fn::Or:
- Fn::Equals:
- Ref: AWS::Region
- eu-central-1
- Fn::Equals:
- Ref: AWS::Region
- eu-north-1
- Fn::Equals:
- Ref: AWS::Region
- eu-south-1
- Fn::Equals:
- Ref: AWS::Region
- eu-west-1
- Fn::Equals:
- Ref: AWS::Region
- eu-west-2
- Fn::Equals:
- Ref: AWS::Region
- eu-west-3
- Fn::Equals:
- Ref: AWS::Region
- il-central-1
- Fn::Equals:
- Ref: AWS::Region
- me-central-1
- Fn::Equals:
- Ref: AWS::Region
- me-south-1
- Fn::Equals:
- Ref: AWS::Region
- sa-east-1
- Fn::Or:
- Fn::Equals:
- Ref: AWS::Region
- us-east-1
- Fn::Equals:
- Ref: AWS::Region
- us-east-2
- Fn::Equals:
- Ref: AWS::Region
- us-west-1
- Fn::Equals:
- Ref: AWS::Region
- us-west-2
Parameters:
BootstrapVersion:
Type: AWS::SSM::Parameter::Value<String>
Default: /cdk-bootstrap/hnb659fds/version
Description: Version of the CDK Bootstrap resources in this environment, automatically retrieved from SSM Parameter Store. [cdk:skip]
Rules:
CheckBootstrapVersion:
Assertions:
- Assert:
Fn::Not:
- Fn::Contains:
- - "1"
- "2"
- "3"
- "4"
- "5"
- Ref: BootstrapVersion
AssertDescription: CDK bootstrap stack version 6 required. Please run 'cdk bootstrap' with a recent version of the CDK CLI.
Al utilizar constructos L2, se definen algunas propiedades para configurar los activos y se utilizan métodos auxiliares para integrarlos entre sí. AWS CDK configura la mayoría de los AWS CloudFormation recursos y propiedades necesarios para aprovisionar la aplicación.
Paso 5: implementar la aplicación
En este paso, se utiliza el AWS CDK CLI cdk deploy
comando para implementar la aplicación. AWS CDK Funciona con el AWS CloudFormation servicio para aprovisionar sus recursos.
importante
Debe realizar un arranque único de su AWS entorno antes de la implementación. Para obtener instrucciones, consulte Inicie su entorno para usarlo con AWS CDK.
Desde la raíz del proyecto, ejecute lo siguiente. Confirme los cambios, si se le solicita:
$
cdk deploy
✨ Synthesis time: 2.44s ... Do you wish to deploy these changes (y/n)?y
Cuando se complete la implementación, el AWS CDK CLI generará la URL de su punto final. Copie esta URL para el siguiente paso. A continuación, se muestra un ejemplo:
... ✅ HelloWorldStack ✨ Deployment time: 45.37s Outputs: HelloWorldStack.HelloWorldApiEndpoint
unique-identifier
= https://<api-id>
.execute-api.<region>
.amazonaws.com/prod/ Stack ARN: arn:aws:cloudformation:region
:account-id
:stack/HelloWorldStack/unique-identifier
...
Paso 6: cómo interactuar con su aplicación
En este paso, inicie una solicitud GET al punto de conexión de la API y verá el resultado de la función de Lambda.
Localice la URL del punto de conexión del paso anterior y agregue la ruta /hello
. Luego, mediante el navegador o la línea de comandos, envíe una solicitud GET al punto de conexión. A continuación, se muestra un ejemplo:
$
curl https://
{"message":"Hello World!"}%<api-id>
.execute-api.<region>
.amazonaws.com/prod/hello
¡Felicitaciones! ¡Ha creado, implementado e interactuado correctamente con su aplicación a través de la AWS CDK!
Paso 7: cómo eliminar la aplicación
En este paso, utiliza la AWS CDK CLI para eliminar la aplicación del Nube de AWS.
Para eliminar la aplicación, ejecute cdk destroy
. Cuando se le indique, confirme su solicitud para eliminar la aplicación:
$
cdk destroy
Are you sure you want to delete: CdkHelloWorldStack (y/n)?y
CdkHelloWorldStack: destroying... [1/1] ... ✅ CdkHelloWorldStack: destroyed
Solución de problemas
Error: {“message”: “Internal server error”}%
Al invocar la función de Lambda implementada, recibe este error. Este puede producirse por varios motivos.
Para la resolución de más problemas
Utilice el AWS CLI para invocar la función Lambda.
-
Modifique el archivo de pila para capturar el valor de salida del nombre de la función de Lambda implementada. A continuación, se muestra un ejemplo:
... class CdkHelloWorldStack extends Stack { constructor(scope, id, props) { super(scope, id, props); // Define the Lambda function resource // ... new CfnOutput(this, 'HelloWorldFunctionName', { value: helloWorldFunction.functionName, description: 'JavaScript Lambda function' }); // Define the API Gateway resource // ...
-
Implemente nuevamente la aplicación. El AWS CDK CLI mostrará el valor del nombre de la función Lambda implementada:
$
cdk deploy
✨ Synthesis time: 0.29s ... ✅ CdkHelloWorldStack ✨ Deployment time: 20.36s Outputs: ... CdkHelloWorldStack.HelloWorldFunctionName = CdkHelloWorldStack-HelloWorldFunctionunique-identifier
... -
Utilice el AWS CLI para invocar la función Lambda en y enviar Nube de AWS la respuesta a un archivo de texto:
$
aws lambda invoke --function-name CdkHelloWorldStack-HelloWorldFunction
unique-identifier
output.txt -
Verifique
output.txt
para ver los resultados.
- Posible causa: el activo API Gateway está definido de forma incorrecta en el archivo de pila.
-
Si
output.txt
muestra una respuesta correcta de la función de Lambda, el problema podría estar relacionado con la forma en que definió la API de REST de API Gateway. AWS CLI Invoca su Lambda directamente, no a través de su punto final. Verifique su código para asegurarse de que coincide con este tutorial. A continuación, vuelva a realizar la implementación. - Posible causa: el activo Lambda está definido incorrectamente en el archivo de pila.
-
Si
output.txt
devuelve un error, el problema podría estar relacionado con la forma en que definió la función de Lambda. Verifique su código para asegurarse de que coincide con este tutorial. A continuación, vuelva a realizar la implementación.