Importar um AWS CloudFormation modelo existente - AWS Kit de desenvolvimento em nuvem (AWS CDK) v2
Importar um AWS CloudFormation modeloAcessar recursos importadosSubstituir parâmetrosImportar outros elementos do modeloImportar pilhas aninhadas

Este é o Guia do desenvolvedor do AWS CDK v2. O CDK v1 antigo 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 aplicativos do AWS Cloud Development Kit (AWS CDK) 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 no código AWS CDK. Você também pode usar essas construções L1 em construções CDK de nível superior AWS . Por exemplo, isso pode permitir que você use os métodos de concessão de permissão L2 com os recursos que definem.

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

nota

AWS O CDK v1 também foi incluído aws-cdk-lib.CfnInclude, que era usado anteriormente para o mesmo propósito geral. No entanto, carece de muitas das funcionalidades de cloudformation-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 como my-template.json para acompanhar. 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": {
    "amzn-s3-demo-bucket": {
      "Type": "AWS::S3::Bucket",
      "Properties": {
        "BucketName": "amzn-s3-demo-bucket",
      }
    }
  }
}

É possível trabalhar com modelos JSON ou YAML. Recomendamos JSON, se disponível, pois os analisadores YAML podem variar um pouco no que aceitam.

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

exemplo
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 o ID lógico 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 wrapper de construção de AWS CDK para o modelo para que ele possa ser usado por outros desenvolvedores de AWS CDK, faça com que o AWS CDK gere um novo recurso. IDs Ao fazer isso, o constructo pode ser usado várias vezes em uma pilha sem conflitos de nome. Para fazer isso, defina a propriedade preserveLogicalIds como false ao importar o modelo. Veja um exemplo a seguir:

exemplo
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 aplicativo AWS CDK, adicione a pilha ao: App

exemplo
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 comando AWS CDK cdk diff CLI e omita todos os metadados específicos do CDK. AWS Este é um exemplo:

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

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

Acessar 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 método getResource() 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 Este é um exemplo:

exemplo
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 desse exemplo, cfnBucket agora é uma instância da classe aws-s3.CfnBucket. Essa é uma construção L1 que representa o AWS CloudFormation recurso correspondente. É possível tratá-lo como qualquer outro recurso desse tipo. Por exemplo, você pode obter seu valor ARN com a propriedade bucket.attrArn.

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

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

Outros constructos L2 têm métodos semelhantes para criar o constructo a partir de um recurso existente.

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

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

exemplo
TypeScript
bucket.grants.write(lambdaFunc);
JavaScript
bucket.grants.write(lambdaFunc);
Python
bucket.grants.write(lambda_func)
Java
bucket.getGrants().write(lambdaFunc);
C#
bucket.Grants.Write(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 código AWS CDK.

exemplo
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 pilha CDK. Para importar esses elementos, use os seguintes métodos do objeto CfnInclude:

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 pilha do CDK. Veja a seguir um exemplo que importa um parâmetro do modelo e modifica seu valor padrão:

exemplo
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";

Importar pilhas aninhadas

É possível 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 recurso NestedStack no modelo principal. Além disso, o nome do recurso usado no código AWS CDK 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"
  }
}
exemplo
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'
});

É possível 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 um número qualquer 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, é possível acessá-la usando o método getNestedStack() do modelo principal.

exemplo
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 método getNestedStack() retorna uma instância IncludedNestedStack. Nessa instância, você pode acessar a NestedStackinstância AWS CDK 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.