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 el AWS Cloud Development Kit (AWS CDK), los símbolos son marcadores de posición para valores que no se conocen al definir construcciones o sintetizar pilas. Estos valores se resolverán por completo en el momento de la implementación, cuando se cree la infraestructura real. Al desarrollar AWS CDK aplicaciones, trabajarás con fichas para gestionar estos valores en toda la aplicación.
Ejemplo de token
A continuación, se muestra un ejemplo de una pila de CDK que define un constructo para un bucket de Amazon Simple Storage Service (Amazon S3). Como aún no se conoce el nombre de nuestro bucket, el valor de bucketName se almacena como un token:
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';
export class CdkDemoAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Define an S3 bucket
const myBucket = new s3.Bucket(this, 'myBucket');
// Store value of the S3 bucket name
const myBucketName = myBucket.bucketName;
// Print the current value for the S3 bucket name at synthesis
console.log("myBucketName: " + bucketName);
}
}Cuando ejecutamos cdk synth para sintetizar nuestra pila, el valor de myBucketName aparecerá en el formato de token como ${Token[TOKEN.. Este formato de token es el resultado de cómo AWS CDK codifica los tokens. En este ejemplo, el token está codificado como una cadena:1234]}
$cdk synth --quietmyBucketName: ${Token[TOKEN.21]}
Como el valor del nombre de nuestro bucket no se conoce en el momento de la síntesis, el token se representa como myBucket. Nuestra AWS CloudFormation plantilla utiliza la función <unique-hash>Ref intrínseca para hacer referencia a su valor, que se conocerá en el momento de la implementación:
Resources:
myBucket5AF9C99B:
# ...
Outputs:
bucketNameOutput:
Description: The name of the S3 bucket
Value:
Ref: myBucket5AF9C99BPara obtener más información sobre cómo se genera el hash único, consulte Generó lógica IDs en su plantilla AWS CloudFormation.
Transferencia de tokens
Los tokens se pueden transferir como si fueran el valor real que representan. A continuación, se muestra un ejemplo en el que se pasa el token del nombre de nuestro bucket a una construcción de una AWS Lambda función:
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as lambda from 'aws-cdk-lib/aws-lambda';
export class CdkDemoAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Define an S3 bucket
const myBucket = new s3.Bucket(this, 'myBucket');
// ...
// Define a Lambda function
const myFunction = new lambda.Function(this, "myFunction", {
runtime: lambda.Runtime.NODEJS_20_X,
handler: "index.handler",
code: lambda.Code.fromInline(`
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`),
functionName: myBucketName + "Function", // Pass token for the S3 bucket name
environment: {
BUCKET_NAME: myBucketName, // Pass token for the S3 bucket name
}
});
}
}Cuando sintetizamos nuestra plantilla, las funciones intrínsecas Ref y Fn::Join se utilizan para especificar los valores, que se conocerán en el momento de la implementación:
Resources:
myBucket5AF9C99B:
Type: AWS::S3::Bucket
# ...
myFunction884E1557:
Type: AWS::Lambda::Function
Properties:
# ...
Environment:
Variables:
BUCKET_NAME:
Ref: myBucket5AF9C99B
FunctionName:
Fn::Join:
- ""
- - Ref: myBucket5AF9C99B
- Function
# ...Cómo funcionan las codificaciones de tokens
Los tokens son objetos que implementan la interfaz IResolvable, que contiene un único método resolve. Durante la síntesis, AWS CDK utiliza este método para obtener el valor final de los símbolos de la CloudFormation plantilla.
nota
En raras ocasiones trabajará con la interfaz IResolvable. Lo más probable es que solo vea las versiones de los tokens codificadas en cadenas.
Tipos de codificación de token
Los tokens participan en el proceso de síntesis para producir valores arbitrarios de cualquier tipo. Por lo general, otras funciones solo aceptan argumentos de tipos básicos, como string o number. Para utilizar tokens en estos casos, puede codificarlos en uno de los tres tipos mediante métodos estáticos de la clase cdk.Token.
-
Token.asStringpara generar una codificación de cadena (o llamar a.toString()en el objeto token). -
Token.asListpara generar una codificación de lista. -
Token.asNumberpara generar una codificación numérica.
Estos tipos toman un valor arbitrario, que puede ser IResolvable, y lo codifican en un valor primitivo del tipo indicado.
importante
Como cualquiera de los tipos anteriores puede ser un token codificado, tenga cuidado al analizar o intentar leer su contenido. Por ejemplo, si intenta analizar una cadena para extraer un valor de ella y la cadena es un token codificado, el análisis no se realizará correctamente. Del mismo modo, si intenta consultar la longitud de una matriz o realizar operaciones matemáticas con un número, primero debe comprobar que no sean tokens codificados.
Cómo comprobar si hay tokens en la aplicación
Para comprobar si un valor contiene un token sin resolver, debe llamar al método Token.isUnresolved (Python: is_unresolved). A continuación, se muestra un ejemplo que comprueba si el valor del nombre del bucket de Amazon S3 es un token. Si no es un token, entonces se valida la longitud del nombre del bucket:
// ...
export class CdkDemoAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Define an S3 bucket
const myBucket = new s3.Bucket(this, 'myBucket');
// ...
// Check if bucket name is a token. If not, check if length is less than 10 characters
if (cdk.Token.isUnresolved(myBucketName)) {
console.log("Token identified.");
} else if (!cdk.Token.isUnresolved(myBucketName) && myBucketName.length > 10) {
throw new Error('Maximum length for name is 10 characters.');
};
// ...Cuando ejecutamos cdk synth, myBucketName se identifica como un token:
$cdk synth --quietToken identified.
nota
Puede utilizar codificaciones de token para escapar del sistema de tipos. Por ejemplo, puede codificar en cadena un token que produce un valor numérico en el momento de la síntesis. Si utiliza estas funciones, es su responsabilidad asegurarse de que la plantilla se resuelve a un estado utilizable después de la síntesis.
Cómo trabajar con tokens codificados en cadena
Así se ven los tokens codificados en cadena.
${TOKEN[Bucket.Name.1234]}
Se pueden transferir como cadenas normales y se pueden concatenar, como se muestra en el siguiente ejemplo.
const functionName = bucket.bucketName + 'Function';Si el idioma lo admite, también puede utilizar la interpolación de cadenas como se muestra en el siguiente ejemplo.
const functionName = `${bucket.bucketName}Function`;Evite manipular la cadena de otras formas. Por ejemplo, si se toma una subcadena, es probable que se rompa el token de la cadena.
Cómo trabajar con tokens codificados en lista
Así se ven los tokens codificados en lista:
["#{TOKEN[Stack.NotificationArns.1234]}"]
Lo único seguro que se puede hacer con estas listas es transferirlas directamente a otros constructos. Los tokens en lista de cadenas no se pueden concatenar, así como tampoco se puede extraer ningún elemento del token. La única forma segura de manipularlos es mediante el uso de funciones intrínsecas AWS CloudFormation como Fn.select.
Cómo trabajar con tokens codificados en números
Los tokens codificados en números son un conjunto de pequeños números negativos de coma flotante con el siguiente aspecto.
-1.8881545897087626e+289Al igual que ocurre con los tokens en lista, no se puede modificar el valor numérico, ya que es probable que se rompa el token numérico.
A continuación, se muestra un ejemplo de un constructo que contiene un token codificado como un número:
import { Stack, Duration, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as rds from 'aws-cdk-lib/aws-rds';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
export class CdkDemoAppStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
// Define a new VPC
const vpc = new ec2.Vpc(this, 'MyVpc', {
maxAzs: 3, // Maximum number of availability zones to use
});
// Define an RDS database cluster
const dbCluster = new rds.DatabaseCluster(this, 'MyRDSCluster', {
engine: rds.DatabaseClusterEngine.AURORA,
instanceProps: {
vpc,
},
});
// Get the port token (this is a token encoded as a number)
const portToken = dbCluster.clusterEndpoint.port;
// Print the value for our token at synthesis
console.log("portToken: " + portToken);
}
}Cuando ejecutamos cdk synth, el valor de portToken se muestra como un token codificado en números:
$cdk synth --quietportToken: -1.8881545897087968e+289
Transferencia de tokens codificados en números
Al transferir tokens codificados en números a otros constructos, puede que tenga sentido convertirlos primero en cadenas. Por ejemplo, si desea utilizar el valor de una cadena codificada en números como parte de una cadena concatenada, su conversión mejora la legibilidad.
En el siguiente ejemplo, portToken es un token codificado en números que queremos transferir a nuestra función de Lambda como parte de connectionString:
import { Stack, Duration, CfnOutput, StackProps } from 'aws-cdk-lib';
// ...
import * as lambda from 'aws-cdk-lib/aws-lambda';
export class CdkDemoAppStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
// Define a new VPC
// ...
// Define an RDS database cluster
// ...
// Get the port token (this is a token encoded as a number)
const portToken = dbCluster.clusterEndpoint.port;
// ...
// Example connection string with the port token as a number
const connectionString = `jdbc:mysql://mydb.cluster.amazonaws.com:${portToken}/mydatabase`;
// Use the connection string as an environment variable in a Lambda function
const myFunction = new lambda.Function(this, 'MyLambdaFunction', {
runtime: lambda.Runtime.NODEJS_20_X,
handler: 'index.handler',
code: lambda.Code.fromInline(`
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`),
environment: {
DATABASE_CONNECTION_STRING: connectionString, // Using the port token as part of the string
},
});
// Output the value of our connection string at synthesis
console.log("connectionString: " + connectionString);
// Output the connection string
new CfnOutput(this, 'ConnectionString', {
value: connectionString,
});
}
}Si transferimos este valor a connectionString, el valor de salida al ejecutar cdk synth puede resultar confuso debido a la cadena codificada en números:
$cdk synth --quietconnectionString: jdbc:mysql://mydb.cluster.amazonaws.com:-1.888154589708796e+289/mydatabase
Para convertir un token codificado en números en una cadena, utilice cdk.Tokenization.stringifyNumber(. En el siguiente ejemplo, convertimos el token codificado en números en una cadena antes de definir nuestra cadena de conexión:token)
import { Stack, Duration, Tokenization, CfnOutput, StackProps } from 'aws-cdk-lib';
// ...
export class CdkDemoAppStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
// Define a new VPC
// ...
// Define an RDS database cluster
// ...
// Get the port token (this is a token encoded as a number)
const portToken = dbCluster.clusterEndpoint.port;
// ...
// Convert the encoded number to an encoded string for use in the connection string
const portAsString = Tokenization.stringifyNumber(portToken);
// Example connection string with the port token as a string
const connectionString = `jdbc:mysql://mydb.cluster.amazonaws.com:${portAsString}/mydatabase`;
// Use the connection string as an environment variable in a Lambda function
const myFunction = new lambda.Function(this, 'MyLambdaFunction', {
// ...
environment: {
DATABASE_CONNECTION_STRING: connectionString, // Using the port token as part of the string
},
});
// Output the value of our connection string at synthesis
console.log("connectionString: " + connectionString);
// Output the connection string
new CfnOutput(this, 'ConnectionString', {
value: connectionString,
});
}
}Cuando ejecutamos cdk synth, el valor de nuestra cadena de conexión se representa en un formato más limpio y claro:
$cdk synth --quietconnectionString: jdbc:mysql://mydb.cluster.amazonaws.com:${Token[TOKEN.242]}/mydatabase
Valores diferidos
Además de representar los valores del tiempo de despliegue, como los AWS CloudFormation parámetros, los tokens también se utilizan habitualmente para representar valores perezosos en el tiempo de síntesis. Estos son valores para los que el valor final se determinará antes de que se complete la síntesis, pero no en el punto en el que se crea el valor. Utilice tokens para pasar una cadena literal o un valor numérico a otro constructo, mientras que el valor real en el momento de la síntesis podría depender de algún cálculo que aún no se ha producido.
Puede crear tokens que representen valores diferidos en el momento de la síntesis utilizando los métodos estáticos de la clase Lazy, como Lazy.string y Lazy.number. Estos métodos aceptan un objeto cuya propiedad produce es una función que acepta un argumento de contexto y devuelve el valor final cuando se llama.
El siguiente ejemplo crea un grupo de escalado automático cuya capacidad se determina después de su creación.
let actualValue: number;
new AutoScalingGroup(this, 'Group', {
desiredCapacity: Lazy.numberValue({
produce(context) {
return actualValue;
}
})
});
// At some later point
actualValue = 10;Conversión a JSON
A veces, desea generar una cadena JSON de datos arbitrarios y es posible que no sepa si los datos contienen tokens. Para codificar correctamente en JSON cualquier estructura de datos, independientemente de si contiene o no tokens, utilice el método stack.toJsonString como se muestra en el siguiente ejemplo.
const stack = Stack.of(this);
const str = stack.toJsonString({
value: bucket.bucketName
});