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á. # Configurar e realizar a síntese de pilhas do CDK Antes de implantar uma pilha do kit de desenvolvimento em nuvem da AWS (CDK da AWS), ela deve primeiro ser sintetizada. A *síntese de pilha* é o processo de produção de um modelo do AWS CloudFormation e artefatos de implantação a partir de uma pilha do CDK. O modelo e os artefatos são conhecidos como *conjunto de nuvem*. O conjunto de nuvem é o que é implantado para provisionar seus recursos na AWS. Para obter mais informações sobre o funcionamento das implantações, consulte [Como as implantações do AWS CDK funcionam](deploy.md#deploy-how). ## Como a síntese e o bootstrapping funcionam juntos Para que suas aplicações do CDK sejam implantados adequadamente, os modelos do CloudFormation produzidos durante a síntese devem especificar corretamente os recursos criados durante o bootstrapping. Portanto, o bootstrapping e a síntese devem se complementar para que uma implantação seja bem-sucedida: + O bootstrapping é um processo único de configuração de um ambiente da AWS para implantações do AWS CDK. Ele configura recursos da AWS específicos em seu ambiente que são usados pelo CDK para implantações. Eles são comumente chamados de *recursos de bootstrap*. Para obter instruções sobre bootstrapping, consulte [Bootstrapping do seu ambiente para uso com o AWSCDK](bootstrapping-env.md). + Os modelos do CloudFormation produzidos durante a síntese incluem informações sobre quais recursos de bootstrapping usar. Durante a síntese, a CLI do CDK não sabe especificamente como seu ambiente da AWS recebeu o bootstrapping. Em vez disso, a CLI do CDK produz modelos do CloudFormation com base no sintetizador que você configura para cada pilha do CDK. Para que uma implantação tenha êxito, o sintetizador deve produzir modelos do CloudFormation que façam referência aos recursos de bootstrapping corretos a serem usados. O CDK vem com um sintetizador padrão e uma configuração de bootstrapping projetados para funcionarem juntos. Se você personalizar um, deverá aplicar personalizações relevantes ao outro. ## Como configurar a síntese de pilhas do CDK Você configura a síntese de pilhas do CDK usando a propriedade `synthesizer` da sua instância [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html). Essa propriedade especifica como suas pilhas do CDK serão sintetizadas. Você fornece uma instância de uma classe que implementa [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.IStackSynthesizer.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.IStackSynthesizer.html) ou [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.IReusableStackSynthesizer.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.IReusableStackSynthesizer.html). Seus métodos serão invocados toda vez que um ativo for adicionado à pilha ou quando a pilha for sintetizada. Veja a seguir um exemplo básico de como usar essa propriedade na sua pilha: **Example** ``` new MyStack(this, 'MyStack', { // stack properties synthesizer: new DefaultStackSynthesizer({ // synthesizer properties }), }); ``` ``` new MyStack(this, 'MyStack', { // stack properties synthesizer: new DefaultStackSynthesizer({ // synthesizer properties }), }); ``` ``` MyStack(self, "MyStack", # stack properties synthesizer=DefaultStackSynthesizer( # synthesizer properties )) ``` ``` new MyStack(app, "MyStack", StackProps.builder() // stack properties .synthesizer(DefaultStackSynthesizer.Builder.create() // synthesizer properties .build()) .build(); ) ``` ``` new MyStack(app, "MyStack", new StackProps // stack properties { Synthesizer = new DefaultStackSynthesizer(new DefaultStackSynthesizerProps { // synthesizer properties }) }); ``` ``` func main() { app := awscdk.NewApp(nil) NewMyStack(app, "MyStack", &MyStackProps{ StackProps: awscdk.StackProps{ Synthesizer: awscdk.NewDefaultStackSynthesizer(&awscdk.DefaultStackSynthesizerProps{ // synthesizer properties }), }, }) app.Synth(nil) } ``` Você também pode configurar um sintetizador para todas as pilhas do CDK em sua aplicação do CDK usando a propriedade `defaultStackSynthesizer` da sua instância: `App` **Example** ``` import { App, Stack, DefaultStackSynthesizer } from 'aws-cdk-lib'; const app = new App({ // Configure for all stacks in this app defaultStackSynthesizer: new DefaultStackSynthesizer({ /* ... */ }), }); ``` ``` const { App, Stack, DefaultStackSynthesizer } = require('aws-cdk-lib'); const app = new App({ // Configure for all stacks in this app defaultStackSynthesizer: new DefaultStackSynthesizer({ /* ... */ }), }); ``` ``` from aws_cdk import App, Stack, DefaultStackSynthesizer app = App( default_stack_synthesizer=DefaultStackSynthesizer( # Configure for all stacks in this app # ... ) ) ``` ``` import software.amazon.awscdk.App; import software.amazon.awscdk.Stack; import software.amazon.awscdk.DefaultStackSynthesizer; public class Main { public static void main(final String[] args) { App app = new App(AppProps.builder() // Configure for all stacks in this app .defaultStackSynthesizer(DefaultStackSynthesizer.Builder.create().build()) .build() ); } } ``` ``` using Amazon.CDK; using Amazon.CDK.Synthesizers; namespace MyNamespace { sealed class Program { public static void Main(string[] args) { var app = new App(new AppProps { // Configure for all stacks in this app DefaultStackSynthesizer = new DefaultStackSynthesizer(new DefaultStackSynthesizerProps { // ... }) }); } } } ``` ``` package main import ( "github.com/aws/aws-cdk-go/awscdk/v2" "github.com/aws/constructs-go/constructs/v10" "github.com/aws/jsii-runtime-go" ) func main() { defer jsii.Close() app := awscdk.NewApp(&awscdk.AppProps{ // Configure for all stacks in this app DefaultStackSynthesizer: awscdk.NewDefaultStackSynthesizer(&awscdk.DefaultStackSynthesizerProps{ // ... }), }) } ``` Por padrão, o AWS CDK usa ` [`DefaultStackSynthesizer](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizer.html) `. Se você não configurar um sintetizador, esse sintetizador será usado. Se você não modificar o bootstrapping, como fazer alterações na pilha ou no modelo de bootstrapping, não precisará modificar a síntese da pilha. Você nem precisa fornecer um sintetizador. O CDK usará a classe `DefaultStackSynthesizer` padrão para configurar a síntese da pilha do CDK para interagir adequadamente com sua pilha de bootstrap. ## Como sintetizar uma pilha do CDK Para sintetizar uma pilha do CDK, use o comando `cdk synth` da interface de linha de comandos do AWS CDK (CLI do AWS CDK). Para obter mais informações sobre esse comando, incluindo as opções que podem ser usadas com esse comando, consulte [cdk synthesize](ref-cli-cmd-synth.md). Se a sua aplicação do CDK contiver uma única pilha, ou para sintetizar todas as pilhas, você não precisará fornecer o nome da pilha do CDK como argumento. Por padrão, a CLI do CDK sintetizará suas pilhas do CDK em modelos do AWS CloudFormation. Um modelo `json` formatado para cada pilha é salvo no diretório `cdk.out`. Se sua aplicação contiver uma única pilha, um modelo `yaml` formatado será impresso em `stdout`. Veja um exemplo a seguir: ``` $ cdk synth Resources: CDKMetadata: Type: AWS::CDK::Metadata Properties: Analytics: v2:deflate64:H4sIAAAAAAAA/unique-identifier Metadata: aws:cdk:path: CdkAppStack/CDKMetadata/Default Condition: CDKMetadataAvailable ... ``` Se sua aplicação do CDK contiver várias pilhas, será possível fornecer o ID lógico de uma pilha para sintetizar uma única pilha. Veja um exemplo a seguir: ``` $ cdk synth MyStackName ``` Se você não sintetizar uma pilha e executar `cdk deploy`, a CLI do CDK sintetizará automaticamente sua pilha antes da implantação. ## Como a síntese funciona por padrão **IDs lógicos gerados em seu modelo do AWS CloudFormation** Quando você sintetiza uma pilha do CDK para produzir um modelo do CloudFormation, IDs lógicos são gerados a partir das fontes a seguir, formatadas como `construct-pathconstruct-IDunique-hash`: + **Caminho de constructo**: o caminho inteiro para o constructo em sua aplicação do CDK. Esse caminho exclui o ID do constructo L1, que é sempre `Resource` ou `Default`, e o ID da pilha de nível superior da qual ela faz parte. + **ID do constructo**: o ID que você fornece como segundo argumento ao instanciar seu constructo. + **Hash exclusivo**: o AWS CDK gera um hash exclusivo de 8 caracteres usando um algoritmo de hash determinístico. Esse hash exclusivo ajuda a garantir que os valores lógicos de ID em seu modelo sejam exclusivos uns dos outros. O comportamento determinístico dessa geração de hash garante que o valor de ID lógico gerado para cada constructo permaneça o mesmo toda vez que você realizar a síntese. O valor de hash só mudará se você modificar valores específicos do constructo, como o ID ou o caminho do constructo. Os IDs lógicos têm um tamanho máximo de 255 caracteres. Portanto, o AWS CDK truncará o caminho do constructo e o ID do constructo, se necessário, para se manter dentro desse limite. Veja a seguir um exemplo de um constructo que define um bucket do Amazon Simple Storage Service (Amazon S3). Aqui, passamos `myBucket` como ID para o nosso constructo: **Example** ------ #### [ TypeScript ] ``` import * as cdk from 'aws-cdk-lib'; import { Construct} from 'constructs'; import * as s3 from 'aws-cdk-lib/aws-s3'; export class MyCdkAppStack extends cdk.Stack { constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); // Define the S3 bucket new s3.Bucket(this, 'myBucket', { versioned: true, removalPolicy: cdk.RemovalPolicy.DESTROY, }); } } ``` ------ #### [ JavaScript ] ``` const cdk = require('aws-cdk-lib'); const s3 = require('aws-cdk-lib/aws-s3'); class MyCdkAppStack extends cdk.Stack { constructor(scope, id, props) { super(scope, id, props); new s3.Bucket(this, 'myBucket', { versioned: true, removalPolicy: cdk.RemovalPolicy.DESTROY, }); } } module.exports = { MyCdkAppStack } ``` ------ #### [ Python ] ``` import aws_cdk as cdk from constructs import Construct from aws_cdk import Stack from aws_cdk import aws_s3 as s3 class MyCdkAppStack(Stack): def __init__(self, scope: Construct, construct_id: str, **kwargs) - None: super().__init__(scope, construct_id, **kwargs) s3.Bucket(self, 'MyBucket', versioned=True, removal_policy=cdk.RemovalPolicy.DESTROY ) ``` ------ #### [ Java ] ``` package com.myorg; import software.constructs.Construct; import software.amazon.awscdk.Stack; import software.amazon.awscdk.StackProps; import software.amazon.awscdk.services.s3.Bucket; import software.amazon.awscdk.services.s3.BucketProps; import software.amazon.awscdk.RemovalPolicy; public class MyCdkAppStack extends Stack { public MyCdkAppStack(final Construct scope, final String id) { this(scope, id, null); } public MyCdkAppStack(final Construct scope, final String id, final StackProps props) { super(scope, id, props); Bucket.Builder.create(this, "myBucket") .versioned(true) .removalPolicy(RemovalPolicy.DESTROY) .build(); } } ``` ------ #### [ C\$1 ] ``` using Amazon.CDK; using Constructs; using Amazon.CDK.AWS.S3; namespace MyCdkApp { public class MyCdkAppStack : Stack { public MyCdkAppStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props) { new Bucket(this, "myBucket", new BucketProps { Versioned = true, RemovalPolicy = RemovalPolicy.DESTROY }); } } } ``` ------ #### [ Go ] ``` package main import ( "github.com/aws/aws-cdk-go/awscdk/v2" "github.com/aws/aws-cdk-go/awscdk/v2/awss3" "github.com/aws/constructs-go/constructs/v10" "github.com/aws/jsii-runtime-go" ) type MyCdkAppStackProps struct { awscdk.StackProps } func NewMyCdkAppStack(scope constructs.Construct, id string, props *MyCdkAppStackProps) awscdk.Stack { var sprops awscdk.StackProps if props != nil { sprops = props.StackProps } stack := awscdk.NewStack(scope, id, sprops) awss3.NewBucket(stack, jsii.String("myBucket"), awss3.BucketProps{ Versioned: jsii.Bool(true), RemovalPolicy: awscdk.RemovalPolicy_DESTROY, }) return stack } // ... ``` ------ Quando executamos `cdk synth`, um ID lógico no formato de `myBucketunique-hash` é gerado. Veja a seguir um exemplo desse recurso no modelo do AWS CloudFormation gerado: ``` Resources: myBucket5AF9C99B: Type: AWS::S3::Bucket Properties: VersioningConfiguration: Status: Enabled UpdateReplacePolicy: Delete DeletionPolicy: Delete Metadata: aws:cdk:path: S3BucketAppStack/myBucket/Resource ``` Veja a seguir um exemplo de um constructo personalizado chamado `Bar` que define um bucket do Amazon S3. O constructo `Bar` inclui o constructo personalizado `Foo` em seu caminho: **Example** ------ #### [ TypeScript ] ``` import * as cdk from 'aws-cdk-lib'; import { Construct } from 'constructs'; import * as s3 from 'aws-cdk-lib/aws-s3'; // Define the Bar construct export class Bar extends Construct { constructor(scope: Construct, id: string) { super(scope, id); // Define an S3 bucket inside of Bar new s3.Bucket(this, 'Bucket', { versioned: true, removalPolicy: cdk.RemovalPolicy.DESTROY, } ); } } // Define the Foo construct export class Foo extends Construct { constructor(scope: Construct, id: string) { super(scope, id); // Create an instance of Bar inside Foo new Bar(this, 'Bar'); } } // Define the CDK stack export class MyCustomAppStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); // Instantiate Foo construct in the stack new Foo(this, 'Foo'); } } ``` ------ #### [ JavaScript ] ``` const cdk = require('aws-cdk-lib'); const s3 = require('aws-cdk-lib/aws-s3'); const { Construct } = require('constructs'); // Define the Bar construct class Bar extends Construct { constructor(scope, id) { super(scope, id); // Define an S3 bucket inside of Bar new s3.Bucket(this, 'Bucket', { versioned: true, removalPolicy: cdk.RemovalPolicy.DESTROY, }); } } // Define the Foo construct class Foo extends Construct { constructor(scope, id) { super(scope, id); // Create an instance of Bar inside Foo new Bar(this, 'Bar'); } } // Define the CDK stack class MyCustomAppStack extends cdk.Stack { constructor(scope, id, props) { super(scope, id, props); // Instantiate Foo construct in the stack new Foo(this, 'Foo'); } } module.exports = { MyCustomAppStack } ``` ------ #### [ Python ] ``` import aws_cdk as cdk from constructs import Construct from aws_cdk import ( Stack, aws_s3 as s3, RemovalPolicy, ) # Define the Bar construct class Bar(Construct): def __init__(self, scope: Construct, id: str) - None: super().__init__(scope, id) # Define an S3 bucket inside of Bar s3.Bucket(self, 'Bucket', versioned=True, removal_policy=RemovalPolicy.DESTROY ) # Define the Foo construct class Foo(Construct): def __init__(self, scope: Construct, id: str) - None: super().__init__(scope, id) # Create an instance of Bar inside Foo Bar(self, 'Bar') # Define the CDK stack class MyCustomAppStack(Stack): def __init__(self, scope: Construct, id: str, **kwargs) - None: super().__init__(scope, id, **kwargs) # Instantiate Foo construct in the stack Foo(self, 'Foo') ``` ------ #### [ Java ] Em `my-custom-app/src/main/java/com/myorg/Bar.java`: ``` package com.myorg; import software.constructs.Construct; import software.amazon.awscdk.services.s3.Bucket; import software.amazon.awscdk.services.s3.BucketProps; import software.amazon.awscdk.RemovalPolicy; public class Bar extends Construct { public Bar(final Construct scope, final String id) { super(scope, id); // Define an S3 bucket inside Bar Bucket.Builder.create(this, "Bucket") .versioned(true) .removalPolicy(RemovalPolicy.DESTROY) .build(); } } ``` Em `my-custom-app/src/main/java/com/myorg/Foo.java`: ``` package com.myorg; import software.constructs.Construct; public class Foo extends Construct { public Foo(final Construct scope, final String id) { super(scope, id); // Create an instance of Bar inside Foo new Bar(this, "Bar"); } } ``` Em `my-custom-app/src/main/java/com/myorg/MyCustomAppStack.java`: ``` package com.myorg; import software.constructs.Construct; import software.amazon.awscdk.Stack; import software.amazon.awscdk.StackProps; public class MyCustomAppStack extends Stack { public MyCustomAppStack(final Construct scope, final String id, final StackProps props) { super(scope, id, props); // Instantiate Foo construct in the stack new Foo(this, "Foo"); } // Overload constructor in case StackProps is not provided public MyCustomAppStack(final Construct scope, final String id) { this(scope, id, null); } } ``` ------ #### [ C\$1 ] ``` using Amazon.CDK; using Constructs; using Amazon.CDK.AWS.S3; namespace MyCustomApp { // Define the Bar construct public class Bar : Construct { public Bar(Construct scope, string id) : base(scope, id) { // Define an S3 bucket inside Bar new Bucket(this, "Bucket", new BucketProps { Versioned = true, RemovalPolicy = RemovalPolicy.DESTROY }); } } // Define the Foo construct public class Foo : Construct { public Foo(Construct scope, string id) : base(scope, id) { // Create an instance of Bar inside Foo new Bar(this, "Bar"); } } // Define the CDK Stack public class MyCustomAppStack : Stack { public MyCustomAppStack(Construct scope, string id, StackProps props = null) : base(scope, id, props) { // Instantiate Foo construct in the stack new Foo(this, "Foo"); } } } ``` ------ #### [ Go ] ``` package main import ( "github.com/aws/aws-cdk-go/awscdk/v2" "github.com/aws/aws-cdk-go/awscdk/v2/awss3" "github.com/aws/constructs-go/constructs/v10" "github.com/aws/jsii-runtime-go" ) // Define the Bar construct type Bar struct { constructs.Construct } func NewBar(scope constructs.Construct, id string) constructs.Construct { bar := constructs.NewConstruct(scope, id) // Define an S3 bucket inside Bar awss3.NewBucket(bar, jsii.String("Bucket"), awss3.BucketProps{ Versioned: jsii.Bool(true), RemovalPolicy: awscdk.RemovalPolicy_DESTROY, }) return bar } // Define the Foo construct type Foo struct { constructs.Construct } func NewFoo(scope constructs.Construct, id string) constructs.Construct { foo := constructs.NewConstruct(scope, id) // Create an instance of Bar inside Foo NewBar(foo, "Bar") return foo } // Define the CDK Stack type MyCustomAppStackProps struct { awscdk.StackProps } func NewMyCustomAppStack(scope constructs.Construct, id string, props *MyCustomAppStackProps) awscdk.Stack { stack := awscdk.NewStack(scope, id, props.StackProps) // Instantiate Foo construct in the stack NewFoo(stack, "Foo") return stack } // Define the CDK App func main() { app := awscdk.NewApp(nil) NewMyCustomAppStack(app, "MyCustomAppStack", MyCustomAppStackProps{ StackProps: awscdk.StackProps{}, }) app.Synth(nil) } ``` ------ Quando executamos `cdk synth`, um ID lógico no formato de `FooBarBucketunique-hash` é gerado. Veja a seguir um exemplo desse recurso no modelo do AWS CloudFormation gerado: ``` Resources: FooBarBucketBA3ED1FA: Type: AWS::S3::Bucket Properties: VersioningConfiguration: Status: Enabled UpdateReplacePolicy: Delete DeletionPolicy: Delete # ... ``` ## Personalizar a síntese de pilhas do CDK Se o comportamento padrão da síntese do CDK não atender às suas necessidades, será possível personalizar a síntese do CDK. Para fazer isso, modifique o `DefaultStackSynthesizer`, use outros sintetizadores integrados disponíveis ou crie seu próprio sintetizador. Para instruções, consulte [Personalização da síntese de pilha do CDK](customize-synth.md).