Importar una AWS CloudFormation plantilla existente

Modo de enfoque

Importar una AWS CloudFormation plantilla existente - AWS Cloud Development Kit (AWS CDK) v2

Importar una plantilla Acceso a los recursos importados Reemplazo de los parámetros Importación de otros elementos de la plantilla Cómo importar pilas anidadas

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.

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 nivel 2 con los recursos que definen.

Básicamente, la cloudformation-include.CfnInclude construcción agrega un contenedor de AWS CDK API 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 puedes usar esta función para vender tus AWS CloudFormation plantillas a AWS CDK los desarrolladores proporcionando una API de construcción. AWS CDK

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 de cloudformation-include.CfnInclude.

Temas

Importa una AWS CloudFormation plantilla
Acceso a los recursos importados
Reemplazo de los parámetros
Importación de otros elementos de la plantilla
Cómo importar pilas anidadas

Importa una AWS CloudFormation plantilla

La siguiente es una AWS CloudFormation plantilla de ejemplo que utilizaremos para proporcionar ejemplos en este tema. Copie y guarde la plantilla como my-template.json para seguir adelante. Después de trabajar con estos ejemplos, puede explorar más a fondo utilizando cualquiera de las AWS CloudFormation plantillas implementadas existentes. Puede obtenerlas desde la consola de AWS CloudFormation .


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

Puede utilizar plantillas en formato JSON o YAML. Recomendamos usar JSON si está disponible, ya que los analizadores de YAML pueden variar ligeramente en cuanto a lo que aceptan.

A continuación, se muestra un ejemplo de cómo importar la plantilla de ejemplo a tu AWS CDK aplicación mediantecloudformation-include. Las plantillas se importan dentro del contexto de una pila de CDK.

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

anchor anchor anchor anchor anchor


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',
    });
  }
}

De forma predeterminada, al importar un recurso se conserva el identificador lógico original del recurso de la plantilla. Este comportamiento es adecuado para importar una AWS CloudFormation plantilla a 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 de AWS CDK componentes para la plantilla para que otros AWS CDK desarrolladores puedan utilizarla, utilice el recurso de AWS CDK generación de nuevos recursos IDs en su lugar. De este modo, el constructo se puede utilizar varias veces en una pila sin conflictos de nombres. Para eso, establezca la propiedad preserveLogicalIds en false al importar la plantilla. A continuación, se muestra un ejemplo:

anchor anchor anchor anchor anchor


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

Para poner los recursos importados bajo el control de tu AWS CDK aplicación, añade la pila a: App

anchor anchor anchor anchor anchor


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

const app = new cdk.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 AWS CDK CLI comando cdk deploy

Acceso 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 método del objeto getResource(). 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:

anchor anchor anchor anchor anchor


const cfnBucket = template.getResource('amzn-s3-demo-bucket') as s3.CfnBucket;

A partir de este ejemplo, cfnBucket ahora es una instancia de la clase aws-s3.CfnBucket. 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 valor de ARN con la propiedad bucket.attrArn.

Para encapsular el recurso CfnBucket de nivel 1 en una instancia de aws-s3.Bucket de nivel 2, utilice los métodos estáticos fromBucketArn(), fromBucketAttributes() o fromBucketName(). Por lo general, el método fromBucketName() es el más conveniente. A continuación, se muestra un ejemplo:

anchor anchor anchor anchor anchor


const bucket = s3.Bucket.fromBucketName(this, 'Bucket', cfnBucket.ref);

Otros constructos de nivel 2 tienen métodos similares para crear el constructo a partir de un recurso existente.

Al encapsular un constructo de nivel 1 en un constructo de nivel 2, no crea un nuevo recurso. En nuestro ejemplo, no estamos creando un segundo bucket de S3. En su lugar, la nueva instancia de Bucket encapsula el CfnBucket existente.

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

anchor anchor anchor anchor anchor


bucket.grantWrite(lambdaFunc);

Reemplazo de 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 bucket definido en otra parte de nuestro AWS CDK código.

anchor anchor anchor anchor anchor


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

Importación de otros elementos de la plantilla

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

getCondition()— AWS CloudFormation condiciones.
getHook()— AWS CloudFormation ganchos para despliegues azules/verdes.
getMapping()— mapeos. AWS CloudFormation
getOutput()— salidas AWS CloudFormation .
getParameter()— AWS CloudFormation parámetros.
getRule()— AWS CloudFormation reglas para AWS Service Catalog plantillas.

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 realice en ellos aparecerán en la plantilla que se genera a partir de la pila de AWS CDK . A continuación, se muestra un ejemplo en el que se importa un parámetro de la plantilla y se modifica su valor predeterminado:

anchor anchor anchor anchor anchor


const param = template.getParameter('MyParameter');
param.default = "AWS CDK"

Cómo importar pilas anidadas

Puede importar pilas anidadas si las especifica 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 un recurso NestedStack 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 a continuación 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'
});

anchor anchor anchor anchor anchor


// 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',
});

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

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

anchor anchor anchor anchor anchor


const nestedStack = mainTemplate.getNestedStack('NestedStack').stack;

El método getNestedStack() devuelve una instancia de IncludedNestedStack. 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.