Configuración de los entornos para usarlos con AWS CDK - AWS Cloud Development Kit (AWS CDK) v2

Esta es la guía para AWS CDK desarrolladores de la versión 2. La CDK versión anterior entró en mantenimiento el 1 de junio de 2022 y finalizó el soporte 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.

Configuración de los entornos para usarlos con AWS CDK

Puede configurar los entornos de AWS de varias formas para utilizarlos con AWS Cloud Development Kit (AWS CDK). El mejor método para administrar los entornos de AWS dependerá de sus necesidades específicas.

Todas las pilas de CDK en su aplicación deben asociarse eventualmente a un entorno para determinar dónde se implementarán.

Para obtener una introducción a los entornos de AWS, consulte Entornos para AWS CDK.

Dónde puede especificar los entornos

Puede especificar los entornos en los archivos de credenciales y configuración, o bien, mediante la propiedad env del constructo Stack de la Biblioteca de constructos de AWS.

Archivos de credenciales y configuración

Puede usar la AWS Command Line Interface (AWS CLI) para crear los archivos credentials y config que almacenan, organizan y administran la información sobre su entorno de AWS. Para obtener más información acerca de estos archivos, consulte Configuration and credential file settings en la Guía del usuario de AWS Command Line Interface.

Los valores almacenados en estos archivos se organizan por perfiles. La forma en que asigne nombres a sus perfiles y los pares clave-valor en estos archivos variarán en función del método que utilice para configurar el acceso mediante programación. Para obtener más información sobre los distintos métodos, consulte Configuración de las credenciales de seguridad para la CLI de AWS CDK.

En general, el AWS CDK resuelve la información sobre Cuenta de AWS con el archivo credentials y la información sobre Región de AWS con el archivo config.

Una vez configurados sus archivos credentials y config, puede especificar el entorno que se va a utilizar con la CLI de AWS CDK y las variables de entorno.

Propiedad env del constructo Stack

Puede especificar el entorno de cada pila mediante la propiedad env del constructo Stack. Esta propiedad define la cuenta y la región que se van a utilizar. Puede pasar valores codificados de forma rígida a esta propiedad o pasar variables de entorno que ofrece el CDK.

Para pasar las variables de entorno, utilice las variables de entorno AWS_DEFAULT_ACCOUNT y AWS_DEFAULT_REGION. Estas variables de entorno pueden pasar valores de sus archivos credentials y config. También puede utilizar lógica del código de CDK para determinar los valores de estas variables de entorno.

Prioridad del entorno con el AWS CDK

Si utiliza varios métodos para especificar entornos, el AWS CDK seguirá el siguiente orden:

  1. Valores codificados de forma rígida especificados con la propiedad env del constructo Stack

  2. Variables de entorno AWS_DEFAULT_ACCOUNT y AWS_DEFAULT_REGION especificadas con la propiedad env del constructo Stack

  3. Información sobre el entorno asociada al perfil proveniente de sus archivos credentials y config, y que se pasó a la CLI de CDK mediante la opción --profile

  4. El perfil default de sus archivos credentials y config

Cuándo especificar los entornos

Cuando el desarrollo se realiza con el CDK, se empieza por definir las pilas de CDK, que contienen constructos que representan los recursos de AWS. A continuación, sintetiza cada pila de CDK en una plantilla de AWS CloudFormation. Luego, implementa la plantilla de CloudFormation en su entorno. La forma en que especifique los entornos determina cuándo se aplica la información del entorno y puede afectar el comportamiento y los resultados del CDK.

Especificar los entornos en la síntesis de la plantilla

Al especificar la información sobre el entorno mediante la propiedad env del constructo Stack, la información se aplica en la síntesis de la plantilla. Si ejecuta cdk synth o cdk deploy, se genera una plantilla de CloudFormation específica del entorno.

Si usa variables de entorno dentro de la propiedad env, debe usar la opción --profile con comandos de la CLI de CDK para pasar el perfil que contiene la información sobre el entorno de sus archivos de credenciales y configuración. Luego, esta información se aplicará en la síntesis de la plantilla para generar una plantilla específica para el entorno.

La información sobre el entorno en la plantilla de CloudFormation se prioriza ante otros métodos. Por ejemplo, si proporciona un entorno diferente con cdk deploy --profile profile, se ignorará el perfil.

Si proporciona información sobre el entorno de esta manera, puede utilizar el código y la lógica dependientes del entorno en su aplicación de CDK. Esto también significa que la plantilla sintetizada podría ser diferente en función de la máquina, el usuario o la sesión con la que se realiza la síntesis. Esta estrategia suele ser aceptable o recomendarse durante el desarrollo, pero no se recomienda para la etapa de producción.

Especificar los entornos en la implementación de la pila

Si no especifica un entorno mediante la propiedad env del constructo Stack, la CLI de CDK generará una plantilla de CloudFormation que se puede usar en cualquier entorno en el momento de la síntesis. Luego, usted puede especificar el entorno en el que desea realizar la implementación mediante cdk deploy --profile profile.

Si no especifica un perfil al implementar una plantilla que se puede usar en cualquier entorno, la CLI de CDK intentará utilizar los valores del entorno del perfil default de sus archivos credentials y config en el momento de la implementación.

Si la información sobre el entorno no está disponible en el momento de la implementación, AWS CloudFormation intentará resolverla mediante atributos relacionados con el entorno, como stack.account, stack.region y stack.availabilityZones.

En el caso de las pilas que se pueden usar en cualquier entorno, los constructos en la pila no pueden utilizar la información sobre el entorno, y usted no puede utilizar lógica que requiera información sobre el entorno. Por ejemplo, no puede escribir código similar a if (stack.region ==== 'us-east-1') ni utilizar métodos de constructos que requieran información sobre el entorno, como Vpc.fromLookup. Para utilizar estas características, debe especificar un entorno con la propiedad env.

En el caso de las pilas que se pueden usar en cualquier entorno, cualquier constructo que utilice zonas de disponibilidad podrá acceder a dos zonas, lo que permitirá implementar la pila en cualquier región.

Cómo especificar los entornos con el AWS CDK

Especificar entornos con codificación rígida para cada pila

Utilice la propiedad env del constructo Stack para especificar los valores de entorno de AWS de la pila. A continuación, se muestra un ejemplo:

TypeScript
const envEU = { account: '2383838383', region: 'eu-west-1' }; const envUSA = { account: '8373873873', region: 'us-west-2' }; new MyFirstStack(app, 'first-stack-us', { env: envUSA }); new MyFirstStack(app, 'first-stack-eu', { env: envEU });
JavaScript
const envEU = { account: '2383838383', region: 'eu-west-1' }; const envUSA = { account: '8373873873', region: 'us-west-2' }; new MyFirstStack(app, 'first-stack-us', { env: envUSA }); new MyFirstStack(app, 'first-stack-eu', { env: envEU });
Python
env_EU = cdk.Environment(account="8373873873", region="eu-west-1") env_USA = cdk.Environment(account="2383838383", region="us-west-2") MyFirstStack(app, "first-stack-us", env=env_USA) MyFirstStack(app, "first-stack-eu", env=env_EU)
Java
public class MyApp { // Helper method to build an environment static Environment makeEnv(String account, String region) { return Environment.builder() .account(account) .region(region) .build(); } public static void main(final String argv[]) { App app = new App(); Environment envEU = makeEnv("8373873873", "eu-west-1"); Environment envUSA = makeEnv("2383838383", "us-west-2"); new MyFirstStack(app, "first-stack-us", StackProps.builder() .env(envUSA).build()); new MyFirstStack(app, "first-stack-eu", StackProps.builder() .env(envEU).build()); app.synth(); } }
C#
Amazon.CDK.Environment makeEnv(string account, string region) { return new Amazon.CDK.Environment { Account = account, Region = region }; } var envEU = makeEnv(account: "8373873873", region: "eu-west-1"); var envUSA = makeEnv(account: "2383838383", region: "us-west-2"); new MyFirstStack(app, "first-stack-us", new StackProps { Env=envUSA }); new MyFirstStack(app, "first-stack-eu", new StackProps { Env=envEU });
Go
env_EU := awscdk.Environment{ Account: jsii.String("8373873873"), Region: jsii.String("eu-west-1"), } env_USA := awscdk.Environment{ Account: jsii.String("2383838383"), Region: jsii.String("us-west-2"), } MyFirstStack(app, "first-stack-us", &awscdk.StackProps{ Env: &env_USA, }) MyFirstStack(app, "first-stack-eu", &awscdk.StackProps{ Env: &env_EU, })

Recomendamos esta estrategia para los entornos de producción. Al especificar explícitamente el entorno de esta manera, puede asegurarse de que la pila se implemente siempre en el entorno específico.

Especificar entornos con las variables de entorno

El AWS CDK proporciona dos variables de entorno que puede usar en su código de CDK: CDK_DEFAULT_ACCOUNT y CDK_DEFAULT_REGION. Si utiliza estas variables de entorno en la propiedad env de su instancia de pila, puede transmitir la información del entorno de sus archivos de credenciales y configuración mediante la opción --profile de la CLI de CDK.

El siguiente es un ejemplo de cómo especificar estas variables de entorno:

TypeScript

Acceda a las variables de entorno a través del objeto process del nodo.

nota

Necesita el módulo DefinitelyTyped para usar process en TypeScript. cdk init instala este módulo por usted. Sin embargo, debe instalar este módulo manualmente si está trabajando con un proyecto creado antes de que se agregue o si no configuró su proyecto con cdk init.

npm install @types/node
new MyDevStack(app, 'dev', { env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION }});
JavaScript

Acceda a las variables de entorno a través del objeto process del nodo.

new MyDevStack(app, 'dev', { env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION }});
Python

Utilice el diccionario environ del módulo os para acceder a las variables de entorno.

import os MyDevStack(app, "dev", env=cdk.Environment( account=os.environ["CDK_DEFAULT_ACCOUNT"], region=os.environ["CDK_DEFAULT_REGION"]))
Java

Utilice System.getenv() para obtener el valor de una variable de entorno.

public class MyApp { // Helper method to build an environment static Environment makeEnv(String account, String region) { account = (account == null) ? System.getenv("CDK_DEFAULT_ACCOUNT") : account; region = (region == null) ? System.getenv("CDK_DEFAULT_REGION") : region; return Environment.builder() .account(account) .region(region) .build(); } public static void main(final String argv[]) { App app = new App(); Environment envEU = makeEnv(null, null); Environment envUSA = makeEnv(null, null); new MyDevStack(app, "first-stack-us", StackProps.builder() .env(envUSA).build()); new MyDevStack(app, "first-stack-eu", StackProps.builder() .env(envEU).build()); app.synth(); } }
C#

Utilice System.Environment.GetEnvironmentVariable() para obtener el valor de una variable de entorno.

Amazon.CDK.Environment makeEnv(string account=null, string region=null) { return new Amazon.CDK.Environment { Account = account ?? System.Environment.GetEnvironmentVariable("CDK_DEFAULT_ACCOUNT"), Region = region ?? System.Environment.GetEnvironmentVariable("CDK_DEFAULT_REGION") }; } new MyDevStack(app, "dev", new StackProps { Env = makeEnv() });
Go
import "os" MyDevStack(app, "dev", &awscdk.StackProps{ Env: &awscdk.Environment{ Account: jsii.String(os.Getenv("CDK_DEFAULT_ACCOUNT")), Region: jsii.String(os.Getenv("CDK_DEFAULT_REGION")), }, })

Al especificar los entornos mediante variables de entorno, puede hacer que la misma pila de CDK se sintetice en plantillas de AWS CloudFormation para diferentes entornos. Esto significa que puede implementar la misma pila de CDK en diferentes entornos de AWS sin tener que modificar el código de CDK. Solo tiene que especificar el perfil que se va a utilizar al ejecutar cdk synth.

Esta estrategia es ideal para los entornos de desarrollo cuando se implementa la misma pila en diferentes entornos. Sin embargo, no recomendamos esta estrategia para los entornos de producción, ya que el mismo código de CDK puede sintetizar diferentes plantillas según la máquina, el usuario o la sesión en la que se sintetiza.

Especificar los entornos a partir de sus archivos de credenciales y configuración con la CLI de CDK

Al implementar una plantilla que se puede usar en cualquier entorno, utilice la opción --profile con cualquier comando de la CLI de CDK para especificar el perfil que se va a utilizar. A continuación, se muestra un ejemplo en el que se implementa una pila de CDK denominada myStack con el perfil prod definido en los archivos credentials y config:

$ cdk deploy myStack --profile prod

Para obtener más información sobre la opción --profile, junto con otros comandos y opciones de la CLI de CDK, consulte AWS CDK CLI Referencia de los comandos  .

Asuntos que se deben tener en cuenta la hora de configurar los entornos con el AWS CDK

Los servicios que defina con los constructos en sus pilas deben ser compatibles con la región en la que vaya a realizar la implementación. Para ver una lista de los Servicios de AWS compatibles por región, consulte Servicios de AWS por región.

Debe tener credenciales de AWS Identity and Access Management (IAM) válidas para realizar implementaciones de pilas con el AWS CDK en los entornos especificados.

Ejemplos

Sintetizar una plantilla de CloudFormation que se puede usar en cualquier entorno a partir de una pila de CDK

En este ejemplo, creamos una plantilla de CloudFormation que se puede usar en cualquier entorno a partir de nuestra pila de CDK. A continuación, podemos implementar esta plantilla en cualquier entorno.

Este es nuestro ejemplo de pila de CDK. Esta pila define un bucket de Amazon S3 y el valor de salida de una pila de CloudFormation para la región del bucket. Para este ejemplo, env no se ha definido:

TypeScript
export class CdkAppStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); // Create the S3 bucket const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', { removalPolicy: cdk.RemovalPolicy.DESTROY, }); // Create an output for the bucket's Region new cdk.CfnOutput(this, 'BucketRegion', { value: bucket.env.region, }); } }
JavaScript
class CdkAppStack extends cdk.Stack { constructor(scope, id, props) { super(scope, id, props); // Create the S3 bucket const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', { removalPolicy: cdk.RemovalPolicy.DESTROY, }); // Create an output for the bucket's Region new cdk.CfnOutput(this, 'BucketRegion', { value: bucket.env.region, }); } }
Python
class CdkAppStack(cdk.Stack): def __init__(self, scope: cdk.Construct, id: str, **kwargs) -> None: super().__init__(scope, id, **kwargs) # Create the S3 bucket bucket = s3.Bucket(self, 'amzn-s3-demo-bucket', removal_policy=cdk.RemovalPolicy.DESTROY ) # Create an output for the bucket's Region cdk.CfnOutput(self, 'BucketRegion', value=bucket.env.region )
Java
public class CdkAppStack extends Stack { public CdkAppStack(final Construct scope, final String id, final StackProps props) { super(scope, id, props); // Create the S3 bucket Bucket bucket = Bucket.Builder.create(this, "amzn-s3-demo-bucket") .removalPolicy(RemovalPolicy.DESTROY) .build(); // Create an output for the bucket's Region CfnOutput.Builder.create(this, "BucketRegion") .value(this.getRegion()) .build(); } }
C#
namespace MyCdkApp { public class CdkAppStack : Stack { public CdkAppStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props) { // Create the S3 bucket var bucket = new Bucket(this, "amzn-s3-demo-bucket", new BucketProps { RemovalPolicy = RemovalPolicy.DESTROY }); // Create an output for the bucket's Region new CfnOutput(this, "BucketRegion", new CfnOutputProps { Value = this.Region }); } } }
Go
func NewCdkAppStack(scope constructs.Construct, id string, props *CdkAppStackProps) awscdk.Stack { stack := awscdk.NewStack(scope, &id, &props.StackProps) // Create the S3 bucket bucket := awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), &awss3.BucketProps{ RemovalPolicy: awscdk.RemovalPolicy_DESTROY, }) // Create an output for the bucket's Region awscdk.NewCfnOutput(stack, jsii.String("BucketRegion"), &awscdk.CfnOutputProps{ Value: stack.Region(), }) return stack }

Cuando ejecutamos cdk synth, la CLI de CDK genera una plantilla de CloudFormation con el pseudoparámetro AWS::Region como valor de salida para la región del bucket. Este parámetro se resolverá en el momento de la implementación:

Outputs: BucketRegion: Value: Ref: AWS::Region

Para implementar esta pila en un entorno especificado en el perfil dev de nuestros archivos de credenciales y configuración, ejecutamos lo siguiente:

$ cdk deploy CdkAppStack --profile dev

Si no especificamos un perfil, la CLI de CDK intentará utilizar la información sobre el entorno del perfil default en nuestros archivos de credenciales y configuración.

Utilizar lógica para determinar la información sobre el entorno en la síntesis de la plantilla

En este ejemplo, configuramos la propiedad env de nuestra instancia stack para usar una expresión válida. Especificamos dos variables de entorno adicionales: CDK_DEPLOY_ACCOUNT y CDK_DEPLOY_REGION. Estas variables de entorno pueden anular los valores predeterminados en el momento de la síntesis, si los hay:

TypeScript
new MyDevStack(app, 'dev', { env: { account: process.env.CDK_DEPLOY_ACCOUNT || process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEPLOY_REGION || process.env.CDK_DEFAULT_REGION }});
JavaScript
new MyDevStack(app, 'dev', { env: { account: process.env.CDK_DEPLOY_ACCOUNT || process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEPLOY_REGION || process.env.CDK_DEFAULT_REGION }});
Python
MyDevStack(app, "dev", env=cdk.Environment( account=os.environ.get("CDK_DEPLOY_ACCOUNT", os.environ["CDK_DEFAULT_ACCOUNT"]), region=os.environ.get("CDK_DEPLOY_REGION", os.environ["CDK_DEFAULT_REGION"])
Java
public class MyApp { // Helper method to build an environment static Environment makeEnv(String account, String region) { account = (account == null) ? System.getenv("CDK_DEPLOY_ACCOUNT") : account; region = (region == null) ? System.getenv("CDK_DEPLOY_REGION") : region; account = (account == null) ? System.getenv("CDK_DEFAULT_ACCOUNT") : account; region = (region == null) ? System.getenv("CDK_DEFAULT_REGION") : region; return Environment.builder() .account(account) .region(region) .build(); } public static void main(final String argv[]) { App app = new App(); Environment envEU = makeEnv(null, null); Environment envUSA = makeEnv(null, null); new MyDevStack(app, "first-stack-us", StackProps.builder() .env(envUSA).build()); new MyDevStack(app, "first-stack-eu", StackProps.builder() .env(envEU).build()); app.synth(); } }
C#
Amazon.CDK.Environment makeEnv(string account=null, string region=null) { return new Amazon.CDK.Environment { Account = account ?? System.Environment.GetEnvironmentVariable("CDK_DEPLOY_ACCOUNT") ?? System.Environment.GetEnvironmentVariable("CDK_DEFAULT_ACCOUNT"), Region = region ?? System.Environment.GetEnvironmentVariable("CDK_DEPLOY_REGION") ?? System.Environment.GetEnvironmentVariable("CDK_DEFAULT_REGION") }; } new MyDevStack(app, "dev", new StackProps { Env = makeEnv() });
Go
var account, region string var b bool if account, b = os.LookupEnv("CDK_DEPLOY_ACCOUNT"); !b || len(account) == 0 { account = os.Getenv("CDK_DEFAULT_ACCOUNT") } if region, b = os.LookupEnv("CDK_DEPLOY_REGION"); !b || len(region) == 0 { region = os.Getenv("CDK_DEFAULT_REGION") } MyDevStack(app, "dev", &awscdk.StackProps{ Env: &awscdk.Environment{ Account: &account, Region: &region, }, })

Con el entorno de nuestra pila declarado de esta manera, podemos escribir un script corto o un archivo de procesamiento por lote y establecer variables a partir de los argumentos de la línea de comandos y, luego, llamar cdk deploy. A continuación, se muestra un ejemplo. Todos los argumentos que no sean los dos primeros se pasan a cdk deploy para especificar opciones o argumentos de la línea de comandos:

macOS/Linux
#!/usr/bin/env bash if [[ $# -ge 2 ]]; then export CDK_DEPLOY_ACCOUNT=$1 export CDK_DEPLOY_REGION=$2 shift; shift npx cdk deploy "$@" exit $? else echo 1>&2 "Provide account and region as first two args." echo 1>&2 "Additional args are passed through to cdk deploy." exit 1 fi

Guarde el script como cdk-deploy-to.sh y, a continuación, ejecute chmod +x cdk-deploy-to.sh para hacerlo ejecutable.

Windows
@findstr /B /V @ %~dpnx0 > %~dpn0.ps1 && powershell -ExecutionPolicy Bypass %~dpn0.ps1 %* @exit /B %ERRORLEVEL% if ($args.length -ge 2) { $env:CDK_DEPLOY_ACCOUNT, $args = $args $env:CDK_DEPLOY_REGION, $args = $args npx cdk deploy $args exit $lastExitCode } else { [console]::error.writeline("Provide account and region as first two args.") [console]::error.writeline("Additional args are passed through to cdk deploy.") exit 1 }

La versión del script para Windows usa PowerShell para proporcionar la misma funcionalidad que la versión para macOS o Linux. También contiene instrucciones que permiten que se ejecute como un archivo de procesamiento por lotes para que pueda invocarse fácilmente desde una línea de comandos. Debe guardarse como cdk-deploy-to.bat. El archivo cdk-deploy-to.ps1 se creará cuando se invoque el archivo de procesamiento por lotes.

Luego, podemos escribir scripts adicionales que usen el script cdk-deploy-to para realizar la implementación en entornos específicos. A continuación, se muestra un ejemplo:

macOS/Linux
#!/usr/bin/env bash # cdk-deploy-to-test.sh ./cdk-deploy-to.sh 123457689 us-east-1 "$@"
Windows
@echo off rem cdk-deploy-to-test.bat cdk-deploy-to 135792469 us-east-1 %*

El siguiente es un ejemplo en el que se usa el script cdk-deploy-to para la implementación en varios entornos. Si se produce un error en la primera implementación, el proceso se detiene:

macOS/Linux
#!/usr/bin/env bash # cdk-deploy-to-prod.sh ./cdk-deploy-to.sh 135792468 us-west-1 "$@" || exit ./cdk-deploy-to.sh 246813579 eu-west-1 "$@"
Windows
@echo off rem cdk-deploy-to-prod.bat cdk-deploy-to 135792469 us-west-1 %* || exit /B cdk-deploy-to 245813579 eu-west-1 %*