Importar um AWS CloudFormation modelo existente - AWS Cloud Development Kit (AWS CDK) v2
Importar um modeloAcesse recursos importadosSubstituir parâmetrosImportar outros elementos do modeloImportar pilhas aninhadas

Este é o Guia do Desenvolvedor AWS CDK v2. A versão CDK 1 mais antiga entrou em manutenção em 1º de junho de 2022 e encerrou o suporte em 1º de junho de 2023.

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Importar um AWS CloudFormation modelo existente

Importe recursos de um AWS CloudFormation modelo para seus AWS Cloud Development Kit (AWS CDK) aplicativos usando a cloudformation-include.CfnIncludeconstrução para converter recursos em construções L1.

Após a importação, você pode trabalhar com esses recursos em seu aplicativo da mesma forma que faria se eles fossem originalmente definidos em AWS CDK código. Você também pode usar essas construções L1 em construções de nível superior AWS CDK . Por exemplo, isso pode permitir que você use os métodos de concessão de permissão L2 com os recursos que eles definem.

A cloudformation-include.CfnInclude construção basicamente adiciona um AWS CDK API invólucro a qualquer recurso em seu AWS CloudFormation modelo. Use esse recurso para importar seus AWS CloudFormation modelos existentes para AWS CDK uma peça por vez. Ao fazer isso, você pode gerenciar seus recursos existentes usando AWS CDK construções para utilizar os benefícios das abstrações de alto nível. Você também pode usar esse recurso para vender seus AWS CloudFormation modelos aos AWS CDK desenvolvedores fornecendo uma AWS CDK construçãoAPI.

nota

AWS CDK A v1 também foi incluída aws-cdk-lib.CfnInclude, que era usada anteriormente para o mesmo propósito geral. No entanto, ele carece de muitas das funcionalidades docloudformation-include.CfnInclude.

Importar um AWS CloudFormation modelo

Veja a seguir um exemplo AWS CloudFormation de modelo que usaremos para fornecer exemplos neste tópico. Copie e salve o modelo my-template.json a seguir. Depois de analisar esses exemplos, você pode explorar mais usando qualquer um dos AWS CloudFormation modelos implantados existentes. Você pode obtê-los no AWS CloudFormation console.

{
  "Resources": {
    "MyBucket": {
      "Type": "AWS::S3::Bucket",
      "Properties": {
        "BucketName": "MyBucket",
      }
    }
  }
}

Você pode trabalhar com qualquer um dos JSON YAML modelos. Recomendamos, JSON se disponível, pois YAML os analisadores podem variar um pouco no que aceitam.

Veja a seguir um exemplo de como importar o modelo de amostra para seu AWS CDK aplicativo usando cloudformation-include o. Os modelos são importados dentro do contexto de uma CDK pilha.

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

Por padrão, a importação de um recurso preserva a ID lógica original do recurso no modelo. Esse comportamento é adequado para importar um AWS CloudFormation modelo para o AWS CDK, onde a lógica IDs deve ser mantida. AWS CloudFormation precisa dessas informações para reconhecer esses recursos importados como os mesmos recursos do AWS CloudFormation modelo.

Se você estiver desenvolvendo um invólucro de AWS CDK construção para o modelo para que ele possa ser usado por outros AWS CDK desenvolvedores, faça com que AWS CDK gere um novo recursoIDs. Ao fazer isso, a construção pode ser usada várias vezes em uma pilha sem conflitos de nome. Para fazer isso, defina a preserveLogicalIds propriedade como false ao importar o modelo. Veja um exemplo a seguir:

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 colocar os recursos importados sob o controle do seu AWS CDK aplicativo, adicione a pilha aoApp:

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 verificar se não haverá nenhuma alteração não intencional nos AWS recursos na pilha, você pode fazer uma comparação. Use o AWS CDK CLI cdk diff comando e omita qualquer AWS CDK metadado específico. Veja um exemplo a seguir:

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

Depois de importar um AWS CloudFormation modelo, o AWS CDK aplicativo deve se tornar a fonte confiável dos recursos importados. Para fazer alterações em seus recursos, modifique-os em seu AWS CDK aplicativo e implante com o AWS CDK CLI cdk deploy comando.

Acesse recursos importados

O nome template no código de exemplo representa o AWS CloudFormation modelo importado. Para acessar um recurso a partir dele, use o getResource()método do objeto. Para acessar o recurso retornado como um tipo específico de recurso, converta o resultado no tipo desejado. Isso não é necessário em Python ou. JavaScript Veja um exemplo a seguir:

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

A partir desse exemplo, agora cfnBucket é uma instância da aws-s3.CfnBucketclasse. Essa é uma construção L1 que representa o AWS CloudFormation recurso correspondente. Você pode tratá-lo como qualquer outro recurso desse tipo. Por exemplo, você pode obter seu ARN valor com a bucket.attrArn propriedade.

Em vez disso, para agrupar o CfnBucket recurso L1 em uma aws-s3.Bucketinstância L2, use os métodos estáticos fromBucketArn()fromBucketAttributes(), ou. fromBucketName() Normalmente, o fromBucketName() método é mais conveniente. Veja um exemplo a seguir:

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

Outras construções L2 têm métodos semelhantes para criar a construção a partir de um recurso existente.

Quando você envolve uma construção L1 em uma construção L2, ela não cria um novo recurso. No nosso exemplo, não estamos criando um segundo bucket S3;. Em vez disso, a nova Bucket instância encapsula a existente. CfnBucket

A partir do exemplo, agora bucket é uma Bucket construção L2 que se comporta como qualquer outra construção L2. Por exemplo, você pode conceder a uma AWS Lambda função acesso de gravação ao bucket usando o grantWrite()método conveniente do bucket. Você não precisa definir manualmente a política AWS Identity and Access Management (IAM) necessária. Veja um exemplo a seguir:

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

Substituir parâmetros

Se seu AWS CloudFormation modelo contiver parâmetros, você poderá substituí-los por valores de tempo de construção na importação usando a parameters propriedade. No exemplo a seguir, substituímos o UploadBucket parâmetro pelo ARN de um bucket definido em outro lugar em nosso 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 }
    }
});

Importar outros elementos do modelo

Você pode importar qualquer elemento AWS CloudFormation do modelo, não apenas recursos. Os elementos importados se tornam parte da AWS CDK pilha. Para importar esses elementos, use os seguintes métodos do CfnInclude objeto:

Cada um desses métodos retorna uma instância de uma classe que representa o tipo específico de AWS CloudFormation elemento. Esses objetos são mutáveis. As alterações que você fizer nelas aparecerão no modelo gerado a partir da AWS CDK pilha. Veja a seguir um exemplo que importa um parâmetro do modelo e modifica seu valor padrão:

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("MyBucket");
var param = template.GetParameter("MyParameter");
param.Default = "AWS CDK";

Importar pilhas aninhadas

Você pode importar pilhas aninhadas especificando-as ao importar o modelo principal ou em algum momento posterior. O modelo aninhado deve ser armazenado em um arquivo local, mas referenciado como um NestedStack recurso no modelo principal. Além disso, o nome do recurso usado no AWS CDK código deve corresponder ao nome usado para a pilha aninhada no modelo principal.

Dada essa definição de recurso no modelo principal, o código a seguir mostra como importar a pilha aninhada referenciada nos dois 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'
});

Você pode importar várias pilhas aninhadas com qualquer um dos métodos. Ao importar o modelo principal, você fornece um mapeamento entre o nome do recurso de cada pilha aninhada e seu arquivo de modelo. Esse mapeamento pode conter qualquer número de entradas. Para fazer isso após a importação inicial, chame loadNestedStack() uma vez para cada pilha aninhada.

Depois de importar uma pilha aninhada, você pode acessá-la usando o método do modelo 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;

O getNestedStack() método retorna uma IncludedNestedStackinstância. Nessa instância, você pode acessar a AWS CDK NestedStackinstância por meio da stack propriedade, conforme mostrado no exemplo. Você também pode acessar o objeto AWS CloudFormation de modelo original por meio includedTemplate do qual você pode carregar recursos e outros AWS CloudFormation elementos.