Como a síntese e o bootstrapping funcionam juntos Configurar a síntese do CDK Como sintetizar uma pilha do CDK Como a síntese funciona por padrão Personalizar a síntese de pilhas do CDK

Configurar e realizar a síntese de pilhas do CDK

Antes de implantar uma pilha do AWS Cloud Development Kit (AWS CDK), 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 funcionam as implantações do AWS CDK.

Como a síntese e o bootstrapping funcionam juntos

Para que seus aplicativos 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 instruções sobre bootstrapping, consulte Fazer o bootstrapping em seu ambiente para uso com o AWS CDK.
Os modelos do CloudFormation produzidos durante a síntese incluem informações sobre quais recursos de bootstrap usar. Durante a síntese, o CDK CLI não sabe especificamente como seu ambiente da AWS recebeu o bootstrapping. Em vez disso, o CDK CLI produz modelos do CloudFormation com base no sintetizador que você configura para cada pilha do CDK. Para que uma implantação seja bem-sucedida, o sintetizador deve produzir modelos do CloudFormation que façam referência aos recursos de bootstrap 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 Stack. Essa propriedade especifica como suas pilhas do CDK serão sintetizadas. Você fornece uma instância de uma classe que implementa IStackSynthesizer ou IReusableStackSynthesizer. 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:

Você também pode configurar um sintetizador para todas as pilhas do CDK em seu aplicativo do CDK usando a propriedade defaultStackSynthesizer da sua instância: App

TypeScript


import { App, Stack, DefaultStackSynthesizer } from 'aws-cdk-lib';

const app = new App({
  // Configure for all stacks in this app
  defaultStackSynthesizer: new DefaultStackSynthesizer({
    /* ... */
  }),
});

JavaScript


const { App, Stack, DefaultStackSynthesizer } = require('aws-cdk-lib');

const app = new App({
  // Configure for all stacks in this app
  defaultStackSynthesizer: new DefaultStackSynthesizer({
    /* ... */
  }),
});

Python


from aws_cdk import App, Stack, DefaultStackSynthesizer

app = App(
    default_stack_synthesizer=DefaultStackSynthesizer(
        # Configure for all stacks in this app
        # ...
    )
)

Java


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

C#


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
                {
                    // ...
                })
            });
        }
    }
}

Go


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. 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 bootstrap, 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 (AWS CDK CLI). Para obter mais informações sobre esse comando, incluindo as opções que você pode usar com esse comando, consulte cdk synthesize.

Se seu aplicativo 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, o CDK CLI sintetizará suas pilhas do CDK em modelos do AWS CloudFormation. Um modelo json formatado para cada pilha é salvo no diretório cdk.out. Se seu aplicativo 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 seu aplicativo do CDK contiver várias pilhas, você poderá 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 o cdk deploy, o CDK CLI 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 seguintes fontes, formatadas como <construct-path><construct-ID><unique-hash>:

Caminho de constructo: o caminho inteiro para o constructo em seu aplicativo 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:

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#


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:

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#


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, você poderá 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 Personalizar a síntese de pilhas do CDK.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Definir permissões para constructos L2

Personalizar a síntese do CDK