Pilhas - AWS Cloud Development Kit (AWS CDK) v2
Definindo pilhasTrabalhar com pilhas do

Este é o Guia do Desenvolvedor 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á.

Pilhas

Uma AWS Cloud Development Kit (AWS CDK) pilha é uma coleção de uma ou mais construções, que definem AWS recursos. Cada pilha CDK representa uma AWS CloudFormation pilha em seu aplicativo CDK. Na implantação, as construções dentro de uma pilha são provisionadas como uma única unidade, chamada de pilha. AWS CloudFormation Para saber mais sobre AWS CloudFormation pilhas, consulte Como trabalhar com pilhas no Guia do AWS CloudFormation usuário.

Como as pilhas de CDK são implementadas por meio de AWS CloudFormation pilhas, AWS CloudFormation cotas e limitações se aplicam. Para saber mais, consulte AWS CloudFormation cotas.

Definindo pilhas

As pilhas são definidas dentro do contexto de um aplicativo. Você define uma pilha usando a Stack classe da AWS Construct Library. As pilhas podem ser definidas de qualquer uma das seguintes formas:

  • Diretamente dentro do escopo do aplicativo.

  • Indiretamente por qualquer construção dentro da árvore.

O exemplo a seguir define um aplicativo CDK que contém duas pilhas:

TypeScript
const app = new App();

new MyFirstStack(app, 'stack1');
new MySecondStack(app, 'stack2');

app.synth();
JavaScript
const app = new App();

new MyFirstStack(app, 'stack1');
new MySecondStack(app, 'stack2');

app.synth();
Python
app = App()

MyFirstStack(app, 'stack1')
MySecondStack(app, 'stack2')

app.synth()
Java
App app = new App();

new MyFirstStack(app, "stack1");
new MySecondStack(app, "stack2");

app.synth();
C#
var app = new App();

new MyFirstStack(app, "stack1");
new MySecondStack(app, "stack2");

app.Synth();

O exemplo a seguir é um padrão comum para definir uma pilha em um arquivo separado. Aqui, estendemos ou herdamos a Stack classe e definimos um construtor que aceita scopeid, e. props Em seguida, invocamos o construtor Stack da classe base usando super com o recebido scopeid, e. props

TypeScript
class HelloCdkStack extends Stack {
  constructor(scope: App, id: string, props?: StackProps) {
    super(scope, id, props);

    //...
  }
}
JavaScript
class HelloCdkStack extends Stack {
  constructor(scope, id, props) {
    super(scope, id, props);

    //...
  }
}
Python
class HelloCdkStack(Stack):

    def __init__(self, scope: Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # ...
Java
public class HelloCdkStack extends Stack {
    public HelloCdkStack(final Construct scope, final String id) {
        this(scope, id, null);
    }

    public HelloCdkStack(final Construct scope, final String id, final StackProps props) {
        super(scope, id, props);

        // ...
    }
}
C#
public class HelloCdkStack : Stack
{
    public HelloCdkStack(Construct scope, string id, IStackProps props=null) : base(scope, id, props)
    {
        //...
    }
}
Go
func HelloCdkStack(scope constructs.Construct, id string, props *HelloCdkStackProps) awscdk.Stack {
 var sprops awscdk.StackProps
 if props != nil {
  sprops = props.StackProps
 }
 stack := awscdk.NewStack(scope, &id, &sprops)

  return stack
}

O exemplo a seguir declara uma classe de pilha chamada MyFirstStack que inclui um único bucket do Amazon S3.

TypeScript
class MyFirstStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    new s3.Bucket(this, 'MyFirstBucket');
  }
}
JavaScript
class MyFirstStack extends Stack {
  constructor(scope, id, props) {
    super(scope, id, props);

    new s3.Bucket(this, 'MyFirstBucket');
  }
}
Python
class MyFirstStack(Stack):

    def __init__(self, scope: Construct, id: str, **kwargs):
        super().__init__(scope, id, **kwargs)

        s3.Bucket(self, "MyFirstBucket")
Java
public class MyFirstStack extends Stack {
    public MyFirstStack(final Construct scope, final String id) {
        this(scope, id, null);
    }

    public MyFirstStack(final Construct scope, final String id, final StackProps props) {
        super(scope, id, props);
        
        new Bucket(this, "MyFirstBucket");
    }
}
C#
public class MyFirstStack : Stack
{
    public MyFirstStack(Stack scope, string id, StackProps props = null) : base(scope, id, props)
    {
        new Bucket(this, "MyFirstBucket");
    }
}
Go
func MyFirstStack(scope constructs.Construct, id string, props *MyFirstStackProps) awscdk.Stack {
  var sprops awscdk.StackProps
  if props != nil {
    sprops = props.StackProps
  }
  stack := awscdk.NewStack(scope, &id, &sprops)
	
  s3.NewBucket(stack, jsii.String("MyFirstBucket"), &s3.BucketProps{})
  return stack
}

No entanto, esse código declarou apenas uma pilha. Para que a pilha seja realmente sintetizada em um AWS CloudFormation modelo e implantada, ela deve ser instanciada. E, como todas as construções de CDK, ela deve ser instanciada em algum contexto. Esse App é esse contexto.

Se você estiver usando o modelo de AWS CDK desenvolvimento padrão, suas pilhas serão instanciadas no mesmo arquivo em que você instancia o objeto. App

TypeScript

O arquivo com o nome do seu projeto (por exemplo,hello-cdk.ts) na bin pasta do seu projeto.

JavaScript

O arquivo com o nome do seu projeto (por exemplo,hello-cdk.js) na bin pasta do seu projeto.

Python

O arquivo app.py no diretório principal do seu projeto.

Java

O arquivo chamadoProjectNameApp.java, por exemploHelloCdkApp.java, está aninhado nas profundezas do src/main diretório.

C#

O arquivo nomeado Program.cs abaixosrc\ProjectName, por exemplosrc\HelloCdk\Program.cs.

A API de pilha

O objeto Stack fornece uma API avançada, incluindo o seguinte:

  • Stack.of(construct)— Um método estático que retorna a pilha na qual uma construção é definida. Isso é útil se você precisar interagir com uma pilha de dentro de uma construção reutilizável. A chamada falhará se uma pilha não puder ser encontrada no escopo.

  • stack.stackName(Python:stack_name) — Retorna o nome físico da pilha. Conforme mencionado anteriormente, todas as AWS CDK pilhas têm um nome físico que AWS CDK pode ser resolvido durante a síntese.

  • stack.regione stack.account — Retorne a AWS região e a conta, respectivamente, nas quais essa pilha será implantada. Essas propriedades retornam uma das seguintes:

    • A conta ou região especificada explicitamente quando a pilha foi definida

    • Um token codificado em string que segue os AWS CloudFormation pseudoparâmetros da conta e da região para indicar que essa pilha é independente do ambiente

    Para obter informações sobre como os ambientes são determinados para pilhas, consulteAmbientes do.

  • stack.addDependency(stack)(Python: stack.add_dependency(stack) — Pode ser usado para definir explicitamente a ordem de dependência entre duas pilhas. Essa ordem é respeitada pelo cdk deploy comando ao implantar várias pilhas ao mesmo tempo.

  • stack.tags— Retorna um TagManagerque você pode usar para adicionar ou remover tags no nível da pilha. Esse gerenciador de tags marca todos os recursos da pilha e também marca a própria pilha quando ela é criada por meio dela. AWS CloudFormation

  • stack.partition, stack.urlSuffix (Python:url_suffix), (stack.stackIdPython:) e (stack.notificationArnPython: stack_idnotification_arn) — Retorna tokens que se resolvem nos respectivos AWS CloudFormation pseudoparâmetros, como. { "Ref": "AWS::Partition" } Esses tokens são associados ao objeto de pilha específico para que a AWS CDK estrutura possa identificar referências de pilha cruzada.

  • stack.availabilityZones(Python:availability_zones) — Retorna o conjunto de zonas de disponibilidade disponíveis no ambiente em que essa pilha é implantada. Para pilhas independentes do ambiente, isso sempre retorna uma matriz com duas zonas de disponibilidade. Para pilhas específicas do ambiente, ele AWS CDK consulta o ambiente e retorna o conjunto exato de zonas de disponibilidade disponíveis na região que você especificou.

  • stack.parseArn(arn)e stack.formatArn(comps) (Python:parse_arn,format_arn) — Pode ser usado para trabalhar com Amazon Resource Names (ARNs).

  • stack.toJsonString(obj)(Python:to_json_string) — Pode ser usado para formatar um objeto arbitrário como uma string JSON que pode ser incorporada em um modelo. AWS CloudFormation O objeto pode incluir tokens, atributos e referências, que só são resolvidos durante a implantação.

  • stack.templateOptions(Python:template_options) — Use para especificar opções de AWS CloudFormation modelo, como Transformação, Descrição e Metadados, para sua pilha.

Trabalhar com pilhas do

Para listar todas as pilhas em um aplicativo CDK, use o cdk ls comando. O exemplo anterior produziria o seguinte:

stack1
stack2

As pilhas são implantadas como parte de uma AWS CloudFormation pilha em um ambiente. AWS O ambiente abrange uma área específica Conta da AWS Região da AWS e.

Quando você executa o cdk synth comando para um aplicativo com várias pilhas, o conjunto de nuvem inclui um modelo separado para cada instância da pilha. Mesmo que as duas pilhas sejam instâncias da mesma classe, elas são AWS CDK emitidas como dois modelos individuais.

Você pode sintetizar cada modelo especificando o nome da pilha no comando. cdk synth O exemplo a seguir sintetiza o modelo para stack1.

$ cdk synth stack1

Essa abordagem é conceitualmente diferente de como os AWS CloudFormation modelos são normalmente usados, em que um modelo pode ser implantado várias vezes e parametrizado por meio de parâmetros.AWS CloudFormation Embora AWS CloudFormation os parâmetros possam ser definidos no AWS CDK, eles geralmente são desencorajados porque AWS CloudFormation os parâmetros são resolvidos somente durante a implantação. Isso significa que você não pode determinar o valor deles em seu código.

Por exemplo, para incluir condicionalmente um recurso em seu aplicativo com base em um valor de parâmetro, você deve configurar uma AWS CloudFormation condição e marcar o recurso com ela. AWS CDK Adota uma abordagem em que modelos concretos são resolvidos no momento da síntese. Portanto, você pode usar uma instrução if para verificar o valor e determinar se um recurso deve ser definido ou se algum comportamento deve ser aplicado.

nota

Isso AWS CDK fornece o máximo de resolução possível durante o tempo de síntese para permitir o uso idiomático e natural de sua linguagem de programação.

Como qualquer outra construção, as pilhas podem ser compostas em grupos. O código a seguir mostra um exemplo de um serviço que consiste em três pilhas: um plano de controle, um plano de dados e pilhas de monitoramento. A construção do serviço é definida duas vezes: uma para o ambiente beta e outra para o ambiente de produção.

TypeScript
import { App, Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';

interface EnvProps {
  prod: boolean;
}

// imagine these stacks declare a bunch of related resources
class ControlPlane extends Stack {}
class DataPlane extends Stack {}
class Monitoring extends Stack {}

class MyService extends Construct {

  constructor(scope: Construct, id: string, props?: EnvProps) {
  
    super(scope, id);
  
    // we might use the prod argument to change how the service is configured
    new ControlPlane(this, "cp");
    new DataPlane(this, "data");
    new Monitoring(this, "mon");  }
}

const app = new App();
new MyService(app, "beta");
new MyService(app, "prod", { prod: true });

app.synth();
JavaScript
const { App, Stack } = require('aws-cdk-lib');
const { Construct } = require('constructs');

// imagine these stacks declare a bunch of related resources
class ControlPlane extends Stack {}
class DataPlane extends Stack {}
class Monitoring extends Stack {}

class MyService extends Construct {

  constructor(scope, id, props) {
  
    super(scope, id);
  
    // we might use the prod argument to change how the service is configured
    new ControlPlane(this, "cp");
    new DataPlane(this, "data");
    new Monitoring(this, "mon");
  }
}

const app = new App();
new MyService(app, "beta");
new MyService(app, "prod", { prod: true });

app.synth();
Python
from aws_cdk import App, Stack
from constructs import Construct

# imagine these stacks declare a bunch of related resources
class ControlPlane(Stack): pass
class DataPlane(Stack): pass
class Monitoring(Stack): pass

class MyService(Construct):

  def __init__(self, scope: Construct, id: str, *, prod=False):
  
    super().__init__(scope, id)
  
    # we might use the prod argument to change how the service is configured
    ControlPlane(self, "cp")
    DataPlane(self, "data")
    Monitoring(self, "mon")
    
app = App();
MyService(app, "beta")
MyService(app, "prod", prod=True)

app.synth()
Java
package com.myorg;

import software.amazon.awscdk.App;
import software.amazon.awscdk.Stack;
import software.constructs.Construct;

public class MyApp {

    // imagine these stacks declare a bunch of related resources
    static class ControlPlane extends Stack {
        ControlPlane(Construct scope, String id) {
            super(scope, id);
        }
    }

    static class DataPlane extends Stack {
        DataPlane(Construct scope, String id) {
            super(scope, id);
        }
    }

    static class Monitoring extends Stack {
        Monitoring(Construct scope, String id) {
            super(scope, id);
        }
    }

    static class MyService extends Construct {
        MyService(Construct scope, String id) {
            this(scope, id, false);
        }
        
        MyService(Construct scope, String id, boolean prod) {
            super(scope, id);
            
            // we might use the prod argument to change how the service is configured
            new ControlPlane(this, "cp");
            new DataPlane(this, "data");
            new Monitoring(this, "mon");         
        }
    }
    
    public static void main(final String argv[]) {
        App app = new App();

        new MyService(app, "beta");
        new MyService(app, "prod", true);
        
        app.synth();
    }
}
C#
using Amazon.CDK;
using Constructs;

// imagine these stacks declare a bunch of related resources
public class ControlPlane : Stack {
    public ControlPlane(Construct scope, string id=null) : base(scope, id) { }
}

public class DataPlane : Stack {
    public DataPlane(Construct scope, string id=null) : base(scope, id) { }
}

public class Monitoring : Stack
{
    public Monitoring(Construct scope, string id=null) : base(scope, id) { }
}

public class MyService : Construct
{
    public MyService(Construct scope, string id, Boolean prod=false) : base(scope, id)
    {
        // we might use the prod argument to change how the service is configured
        new ControlPlane(this, "cp");
        new DataPlane(this, "data");
        new Monitoring(this, "mon");
    }
}

class Program
{
    static void Main(string[] args)
    {

        var app = new App();
        new MyService(app, "beta");
        new MyService(app, "prod", prod: true);
        app.Synth();
    }
}

Eventualmente, esse AWS CDK aplicativo consiste em seis pilhas, três para cada ambiente:

$ cdk ls
    
betacpDA8372D3
betadataE23DB2BA
betamon632BD457
prodcp187264CE
proddataF7378CE5
prodmon631A1083

Os nomes físicos das AWS CloudFormation pilhas são determinados automaticamente AWS CDK com base no caminho de construção da pilha na árvore. Por padrão, o nome de uma pilha é derivado do ID de construção do Stack objeto. No entanto, você pode especificar um nome explícito usando a stackName prop (em Python,stack_name), da seguinte maneira.

TypeScript
new MyStack(this, 'not:a:stack:name', { stackName: 'this-is-stack-name' });
JavaScript
new MyStack(this, 'not:a:stack:name', { stackName: 'this-is-stack-name' });
Python
MyStack(self, "not:a:stack:name", stack_name="this-is-stack-name")
Java
new MyStack(this, "not:a:stack:name", StackProps.builder()
    .StackName("this-is-stack-name").build());
C#
new MyStack(this, "not:a:stack:name", new StackProps
{
    StackName = "this-is-stack-name"
});

Pilhas aninhadas

A NestedStackconstrução oferece uma maneira de contornar o limite de AWS CloudFormation 500 recursos para pilhas. Uma pilha aninhada conta como apenas um recurso na pilha que a contém. No entanto, ele pode conter até 500 recursos, incluindo pilhas aninhadas adicionais.

O escopo de uma pilha aninhada deve ser uma construção Stack ouNestedStack. A pilha aninhada não precisa ser declarada lexicamente dentro de sua pilha principal. É necessário apenas passar a pilha principal como o primeiro parâmetro (scope) ao instanciar a pilha aninhada. Além dessa restrição, definir construções em uma pilha aninhada funciona exatamente da mesma forma que em uma pilha comum.

No momento da síntese, a pilha aninhada é sintetizada em seu próprio AWS CloudFormation modelo, que é carregado no bucket de teste na implantação AWS CDK . As pilhas aninhadas são vinculadas à pilha principal e não são tratadas como artefatos de implantação independentes. Eles não estão listados por cdk list e não podem ser implantados porcdk deploy.

As referências entre pilhas principais e pilhas aninhadas são traduzidas automaticamente em parâmetros de pilha e saídas nos AWS CloudFormation modelos gerados, como acontece com qualquer referência de pilha cruzada.

Atenção

As alterações na postura de segurança não são exibidas antes da implantação das pilhas aninhadas. Essas informações são exibidas somente para pilhas de nível superior.