Importar una AWS CloudFormation plantilla existente - AWS Cloud Development Kit (AWS CDK) v2
Importar una plantillaAcceder a los recursos importadosSustituya los parámetrosImporta otros elementos de la plantillaImporta pilas anidadas

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.

Importar una AWS CloudFormation plantilla existente

Importe recursos de una AWS CloudFormation plantilla a sus AWS Cloud Development Kit (AWS CDK) aplicaciones mediante la cloudformation-include.CfnIncludeconstrucción para convertir los recursos en construcciones de nivel 1.

Tras la importación, puedes trabajar con estos recursos en tu aplicación de la misma manera que lo harías si estuvieran definidos originalmente en AWS CDK el código. También puede usar estas construcciones de L1 dentro de las construcciones de nivel superior AWS CDK . Por ejemplo, esto puede permitirle usar los métodos de concesión de permisos de nivel 2 con los recursos que definen.

Básicamente, la cloudformation-include.CfnInclude construcción agrega un AWS CDK API contenedor a cualquier recurso de la plantilla AWS CloudFormation . Usa esta capacidad para importar tus AWS CloudFormation plantillas existentes a AWS CDK una pieza a la vez. De este modo, puede administrar sus recursos existentes mediante AWS CDK componentes constructos para aprovechar las ventajas de las abstracciones de nivel superior. También puede utilizar esta función para vender sus AWS CloudFormation plantillas a AWS CDK los desarrolladores proporcionando una construcción. AWS CDK API

nota

AWS CDK También se incluye la versión 1 aws-cdk-lib.CfnInclude, que anteriormente se utilizaba con el mismo propósito general. Sin embargo, carece de gran parte de la funcionalidad decloudformation-include.CfnInclude.

Importa una AWS CloudFormation plantilla

La siguiente es una AWS CloudFormation plantilla de ejemplo que utilizaremos para proporcionar ejemplos en este tema. Copia y guarda la plantilla como se my-template.json indica a continuación. Después de trabajar con estos ejemplos, puede explorar más a fondo utilizando cualquiera de las AWS CloudFormation plantillas desplegadas existentes. Puede obtenerlas desde la AWS CloudFormation consola.

{
  "Resources": {
    "amzn-s3-demo-bucket": {
      "Type": "AWS::S3::Bucket",
      "Properties": {
        "BucketName": "amzn-s3-demo-bucket",
      }
    }
  }
}

Puede trabajar con cualquiera JSON de las dos YAML plantillas. Recomendamos que estén JSON disponibles, ya que YAML los analizadores pueden variar ligeramente en cuanto a lo que aceptan.

El siguiente es un ejemplo de cómo importar la plantilla de muestra a tu AWS CDK aplicación utilizandocloudformation-include. Las plantillas se importan en el contexto de una CDK pila.

TypeScript
import * as cdk from 'aws-cdk-lib';
import * as cfninc from 'aws-cdk-lib/cloudformation-include';
import { Construct } from 'constructs';

export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const template = new cfninc.CfnInclude(this, 'Template', { 
      templateFile: 'my-template.json',
    });
  }
}
JavaScript
const cdk = require('aws-cdk-lib');
const cfninc = require('aws-cdk-lib/cloudformation-include');

class MyStack extends cdk.Stack {
  constructor(scope, id, props) {
    super(scope, id, props);

    const template = new cfninc.CfnInclude(this, 'Template', { 
      templateFile: 'my-template.json',
    });
  }
}

module.exports = { MyStack }
Python
import aws_cdk as cdk
from aws_cdk import cloudformation_include as cfn_inc
from constructs import Construct

class MyStack(cdk.Stack):

    def __init__(self, scope: Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        template = cfn_inc.CfnInclude(self, "Template",  
            template_file="my-template.json")
Java
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.cloudformation.include.CfnInclude;
import software.constructs.Construct;

public class MyStack extends Stack {
    public MyStack(final Construct scope, final String id) {
        this(scope, id, null);
    }

    public MyStack(final Construct scope, final String id, final StackProps props) {
        super(scope, id, props);

        CfnInclude template = CfnInclude.Builder.create(this, "Template")
        	.templateFile("my-template.json")
        	.build();
    }
}
C#
using Amazon.CDK;
using Constructs;
using cfnInc = Amazon.CDK.CloudFormation.Include;

namespace MyApp
{
    public class MyStack : Stack
    {
        internal MyStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props)
        {
            var template = new cfnInc.CfnInclude(this, "Template", new cfnInc.CfnIncludeProps
            {
                TemplateFile = "my-template.json"
            });
        }
    }
}

De forma predeterminada, la importación de un recurso conserva el identificador lógico original del recurso que figura en la plantilla. Este comportamiento es adecuado para importar una AWS CloudFormation plantilla a la AWS CDK, donde se IDs debe conservar la lógica. AWS CloudFormation necesita esta información para reconocer estos recursos importados como los mismos recursos de la AWS CloudFormation plantilla.

Si está desarrollando un contenedor AWS CDK de componentes para la plantilla para que otros AWS CDK desarrolladores puedan usarlo, utilice el recurso de AWS CDK generación de nuevos recursosIDs. De este modo, la construcción se puede utilizar varias veces en una pila sin conflictos de nombres. Para ello, defina la preserveLogicalIds propiedad en false al importar la plantilla. A continuación, se muestra un ejemplo:

TypeScript
const template = new cfninc.CfnInclude(this, 'MyConstruct', {
  templateFile: 'my-template.json',
  preserveLogicalIds: false
});
JavaScript
const template = new cfninc.CfnInclude(this, 'MyConstruct', {
  templateFile: 'my-template.json',
  preserveLogicalIds: false
});
Python
template = cfn_inc.CfnInclude(self, "Template",  
    template_file="my-template.json",
    preserve_logical_ids=False)
Java
CfnInclude template = CfnInclude.Builder.create(this, "Template")
	.templateFile("my-template.json")
	.preserveLogicalIds(false)
	.build();
C#
var template = new cfnInc.CfnInclude(this, "Template", new cfn_inc.CfnIncludeProps
{
    TemplateFile = "my-template.json",
    PreserveLogicalIds = false
});

Para poner los recursos importados bajo el control de tu AWS CDK aplicación, agrega la pila aApp:

TypeScript
import * as cdk from 'aws-cdk-lib';
import { MyStack } from '../lib/my-stack';

const app = new cdk.App();
new MyStack(app, 'MyStack');
JavaScript
const cdk = require('aws-cdk-lib');
const { MyStack } = require('../lib/my-stack');

const app = new cdk.App();
new MyStack(app, 'MyStack');
Python
import aws_cdk as cdk
from mystack.my_stack import MyStack

app = cdk.App()
MyStack(app, "MyStack")
Java
import software.amazon.awscdk.App;

public class MyApp {
    public static void main(final String[] args) {
        App app = new App();

        new MyStack(app, "MyStack");
    }
}
C#
using Amazon.CDK;

namespace CdkApp
{
    sealed class Program
    {
        public static void Main(string[] args)
        {
            var app = new App();
            new MyStack(app, "MyStack");
        }
    }
}

Para comprobar que no se produzcan cambios imprevistos en los AWS recursos de la pila, puedes realizar una diferencia. Usa el AWS CDK CLI cdk diffcomando y omita cualquier metadato AWS CDK específico. A continuación, se muestra un ejemplo:

cdk diff --no-version-reporting --no-path-metadata --no-asset-metadata

Tras importar una AWS CloudFormation plantilla, la AWS CDK aplicación debería convertirse en la fuente fiable de los recursos importados. Para realizar cambios en los recursos, modifíquelos en la AWS CDK aplicación e impleméntelos con el AWS CDK CLI cdk deploycomando.

Acceder a los recursos importados

El nombre template del código de ejemplo representa la AWS CloudFormation plantilla importada. Para acceder a un recurso desde ella, utilice el getResource()método del objeto. Para acceder al recurso devuelto como un tipo de recurso específico, asigne el resultado al tipo deseado. Esto no es necesario en Python o JavaScript. A continuación, se muestra un ejemplo:

TypeScript
const cfnBucket = template.getResource('amzn-s3-demo-bucket') as s3.CfnBucket;
JavaScript
const cfnBucket = template.getResource('amzn-s3-demo-bucket');
Python
cfn_bucket = template.get_resource("amzn-s3-demo-bucket")
Java
CfnBucket cfnBucket = (CfnBucket)template.getResource("amzn-s3-demo-bucket");
C#
var cfnBucket = (CfnBucket)template.GetResource("amzn-s3-demo-bucket");

A partir de este ejemplo, ahora cfnBucket es una instancia de la aws-s3.CfnBucketclase. Se trata de una construcción L1 que representa el AWS CloudFormation recurso correspondiente. Puede tratarlo como cualquier otro recurso de su tipo. Por ejemplo, puede obtener su ARN valor con la bucket.attrArn propiedad.

Para empaquetar el CfnBucket recurso L1 en una aws-s3.Bucketinstancia L2, usa los métodos estáticos fromBucketArn()fromBucketAttributes(), o. fromBucketName() Por lo general, el fromBucketName() método es el más conveniente. A continuación, se muestra un ejemplo:

TypeScript
const bucket = s3.Bucket.fromBucketName(this, 'Bucket', cfnBucket.ref);
JavaScript
const bucket = s3.Bucket.fromBucketName(this, 'Bucket', cfnBucket.ref);
Python
bucket = s3.Bucket.from_bucket_name(self, "Bucket", cfn_bucket.ref)
Java
Bucket bucket = (Bucket)Bucket.fromBucketName(this, "Bucket", cfnBucket.getRef());
C#
var bucket = (Bucket)Bucket.FromBucketName(this, "Bucket", cfnBucket.Ref);

Otras construcciones L2 tienen métodos similares para crear la construcción a partir de un recurso existente.

Al incluir una construcción de L1 en una construcción de L2, no se crea un recurso nuevo. A partir de nuestro ejemplo, no vamos a crear un segundo bucket de S3;. En su lugar, la nueva Bucket instancia encapsula la existenteCfnBucket.

A partir del ejemplo, ahora bucket es una construcción L2 que se comporta como cualquier otra Bucket construcción L2. Por ejemplo, puedes conceder a una AWS Lambda función acceso de escritura al depósito mediante el práctico método del depósito. grantWrite() No es necesario que definas manualmente la política necesaria AWS Identity and Access Management (IAM). A continuación, se muestra un ejemplo:

TypeScript
bucket.grantWrite(lambdaFunc);
JavaScript
bucket.grantWrite(lambdaFunc);
Python
bucket.grant_write(lambda_func)
Java
bucket.grantWrite(lambdaFunc);
C#
bucket.GrantWrite(lambdaFunc);

Sustituya los parámetros

Si la AWS CloudFormation plantilla contiene parámetros, puede sustituirlos por valores de tiempo de creación en el momento de la importación mediante la parameters propiedad. En el siguiente ejemplo, sustituimos el UploadBucket parámetro por el ARN de un segmento definido en otra parte de nuestro AWS CDK código.

TypeScript
const template = new cfninc.CfnInclude(this, 'Template', {
  templateFile: 'my-template.json',
  parameters: {
    'UploadBucket': bucket.bucketArn,
  },
});
JavaScript
const template = new cfninc.CfnInclude(this, 'Template', {
  templateFile: 'my-template.json',
  parameters: {
    'UploadBucket': bucket.bucketArn,
  },
});
Python
template = cfn_inc.CfnInclude(self, "Template",  
    template_file="my-template.json",
    parameters=dict(UploadBucket=bucket.bucket_arn)
)
Java
CfnInclude template = CfnInclude.Builder.create(this, "Template")
	.templateFile("my-template.json")
	.parameters(java.util.Map.of(    // Map.of requires Java 9+
			"UploadBucket", bucket.getBucketArn()))
	.build();
C#
var template = new cfnInc.CfnInclude(this, "Template", new cfnInc.CfnIncludeProps
{
    TemplateFile = "my-template.json",
    Parameters = new Dictionary<string, string>
    {
        { "UploadBucket", bucket.BucketArn }
    }
});

Importa otros elementos de la plantilla

Puede importar cualquier elemento AWS CloudFormation de la plantilla, no solo los recursos. Los elementos importados pasan a formar parte de la AWS CDK pila. Para importar estos elementos, utilice los siguientes métodos del CfnInclude objeto:

Cada uno de estos métodos devuelve una instancia de una clase que representa el tipo específico de AWS CloudFormation elemento. Estos objetos son mutables. Los cambios que realices en ellos aparecerán en la plantilla que se genere a partir de la AWS CDK pila. A continuación se muestra un ejemplo en el que se importa un parámetro de la plantilla y se modifica su valor predeterminado:

TypeScript
const param = template.getParameter('MyParameter');
param.default = "AWS CDK"
JavaScript
const param = template.getParameter('MyParameter');
param.default = "AWS CDK"
Python
param = template.get_parameter("MyParameter")
param.default = "AWS CDK"
Java
CfnParameter param = template.getParameter("MyParameter");
param.setDefaultValue("AWS CDK")
C#
var cfnBucket = (CfnBucket)template.GetResource("amzn-s3-demo-bucket");
var param = template.GetParameter("MyParameter");
param.Default = "AWS CDK";

Importa pilas anidadas

Puede importar pilas anidadas especificándolas al importar su plantilla principal o en algún momento posterior. La plantilla anidada debe almacenarse en un archivo local, pero debe hacerse referencia a ella como NestedStack recurso en la plantilla principal. Además, el nombre del recurso utilizado en el AWS CDK código debe coincidir con el nombre utilizado para la pila anidada en la plantilla principal.

Dada esta definición de recurso en la plantilla principal, el código siguiente muestra cómo importar la pila anidada a la que se hace referencia en ambos sentidos.

"NestedStack": {
  "Type": "AWS::CloudFormation::Stack",
  "Properties": {
    "TemplateURL": "https://my-s3-template-source.s3.amazonaws.com/nested-stack.json"
  }
TypeScript
// include nested stack when importing main stack
const mainTemplate = new cfninc.CfnInclude(this, 'MainStack', {
  templateFile: 'main-template.json',
  loadNestedStacks: {
    'NestedStack': {
      templateFile: 'nested-template.json',
    },
  },
});

// or add it some time after importing the main stack
const nestedTemplate = mainTemplate.loadNestedStack('NestedTemplate', {
  templateFile: 'nested-template.json',
});
JavaScript
// include nested stack when importing main stack
const mainTemplate = new cfninc.CfnInclude(this, 'MainStack', {
  templateFile: 'main-template.json',
  loadNestedStacks: {
    'NestedStack': {
      templateFile: 'nested-template.json',
    },
  },
});

// or add it some time after importing the main stack
const nestedTemplate = mainTemplate.loadNestedStack('NestedStack', {
  templateFile: 'my-nested-template.json',
});
Python
# include nested stack when importing main stack
main_template = cfn_inc.CfnInclude(self, "MainStack",  
    template_file="main-template.json",
    load_nested_stacks=dict(NestedStack=
        cfn_inc.CfnIncludeProps(template_file="nested-template.json")))

# or add it some time after importing the main stack
nested_template = main_template.load_nested_stack("NestedStack", 
    template_file="nested-template.json")
Java
CfnInclude mainTemplate = CfnInclude.Builder.create(this, "MainStack")
	.templateFile("main-template.json")
	.loadNestedStacks(java.util.Map.of(    // Map.of requires Java 9+
	   "NestedStack", CfnIncludeProps.builder()
				.templateFile("nested-template.json").build()))
	.build();

// or add it some time after importing the main stack
IncludedNestedStack nestedTemplate = mainTemplate.loadNestedStack("NestedTemplate", CfnIncludeProps.builder()
		.templateFile("nested-template.json")
		.build());
C#
// include nested stack when importing main stack
var mainTemplate = new cfnInc.CfnInclude(this, "MainStack", new cfnInc.CfnIncludeProps
{
    TemplateFile = "main-template.json",
    LoadNestedStacks = new Dictionary<string, cfnInc.ICfnIncludeProps>
    {
        { "NestedStack", new cfnInc.CfnIncludeProps { TemplateFile = "nested-template.json" } }
    }
});

// or add it some time after importing the main stack
var nestedTemplate = mainTemplate.LoadNestedStack("NestedTemplate", new cfnInc.CfnIncludeProps {
    TemplateFile = 'nested-template.json'
});

Puede importar varias pilas anidadas con cualquiera de los dos métodos. Al importar la plantilla principal, se proporciona un mapeo entre el nombre del recurso de cada pila anidada y su archivo de plantilla. Este mapeo puede contener cualquier número de entradas. Para hacerlo después de la importación inicial, llama loadNestedStack() una vez por cada pila anidada.

Tras importar una pila anidada, puedes acceder a ella mediante el método de la plantilla principal. getNestedStack()

TypeScript
const nestedStack = mainTemplate.getNestedStack('NestedStack').stack;
JavaScript
const nestedStack = mainTemplate.getNestedStack('NestedStack').stack;
Python
nested_stack = main_template.get_nested_stack("NestedStack").stack
Java
NestedStack nestedStack = mainTemplate.getNestedStack("NestedStack").getStack();
C#
var nestedStack = mainTemplate.GetNestedStack("NestedStack").Stack;

El getNestedStack() método devuelve una IncludedNestedStackinstancia. Desde esta instancia, puede acceder a la AWS CDK NestedStackinstancia a través de la stack propiedad, como se muestra en el ejemplo. También puedes acceder al objeto de AWS CloudFormation plantilla original a través includedTemplate del cual puedes cargar recursos y otros AWS CloudFormation elementos.