Introdução às AWS CDK pilhas

Modo de foco

Introdução às AWS CDK pilhas - AWS Cloud Development Kit (AWS CDK) v2

Sobre a API da pilha Trabalhar 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á.

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á.

Uma AWS CDK pilha é a menor unidade única de implantação. Ela representa uma coleção de AWS recursos que você define usando construções de CDK. Quando você implanta aplicativos CDK, os recursos em uma pilha de CDK são implantados juntos como uma pilha. AWS CloudFormation Para saber mais sobre AWS CloudFormation pilhas, consulte Gerenciamento de recursos da AWS como uma única unidade com AWS CloudFormation pilhas no Guia do AWS CloudFormation usuário.

Você define uma pilha estendendo ou herdando do constructo Stack. O exemplo a seguir é um padrão comum para definir uma pilha do CDK em um arquivo separado, conhecido como arquivo de pilha. Aqui, estendemos ou herdamos a classe de Stack e definimos um construtor que aceita scope, id e props. Em seguida, invocamos o construtor da classe de base da Stack usando super com o recebido scope, id e props:

TypeScript


import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';

export class MyCdkStack extends cdk.Stack { 
  constructor(scope: Construct, id: string, props?: cdk.StackProps) { 
    super(scope, id, props); 
    
    // Define your constructs here

  }
}

JavaScript


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

class MyCdkStack extends Stack {
  constructor(scope, id, props) {
    super(scope, id, props);

    // Define your constructs here

  }
}

module.exports = { MyCdkStack }

Python


from aws_cdk import (
  Stack,
)
from constructs import Construct

class MyCdkStack(Stack):

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

    # Define your constructs here

Java


package com.myorg;

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

public class MyCdkStack extends Stack {
  public MyCdkStack(final Construct scope, final String id) {  
    this(scope, id, null);
  }
  
  public MyCdkStack(final Construct scope, final String id, final StackProps props) {
    super(scope, id, props);

    // Define your constructs here
  }
}

C#


using Amazon.CDK; 
using Constructs;

namespace MyCdk
{
  public class MyCdkStack : Stack
  {
    internal MyCdkStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props)
    {
      // Define your constructs here
    }
  }
}

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

type CdkDemoAppStackProps struct {
	awscdk.StackProps
}

func NewCdkDemoAppStack(scope constructs.Construct, id string, props *CdkDemoAppStackProps) awscdk.Stack {
	var sprops awscdk.StackProps
	if props != nil {
		sprops = props.StackProps
	}
	stack := awscdk.NewStack(scope, &id, &sprops)

	// The code that defines your stack goes here

	return stack
}

func main() {
	defer jsii.Close()

	app := awscdk.NewApp(nil)

	NewCdkDemoAppStack(app, "CdkDemoAppStack", &CdkDemoAppStackProps{
		awscdk.StackProps{
			Env: env(),
		},
	})

	app.Synth(nil)
} 

//...

anchor anchor anchor anchor anchor anchor


import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';

export class MyCdkStack extends cdk.Stack { 
  constructor(scope: Construct, id: string, props?: cdk.StackProps) { 
    super(scope, id, props); 
    
    // Define your constructs here

  }
}

O exemplo anterior definiu apenas uma pilha. Para criar a pilha, ela deve ser instanciada dentro do contexto da sua aplicação do CDK. Um padrão comum é definir sua aplicação do CDK e inicializar sua pilha em um arquivo separado, conhecido como arquivo de aplicação.

Veja a seguir um exemplo de criação de uma pilha do CDK chamada MyCdkStack. Aqui, a aplicação do CDK é criado e MyCdkStack é instanciado no contexto da aplicação:

anchor anchor anchor anchor anchor anchor


#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from 'aws-cdk-lib';
import { MyCdkStack } from '../lib/my-cdk-stack';

const app = new cdk.App();
new MyCdkStack(app, 'MyCdkStack', {
});

O exemplo a seguir cria uma aplicação do CDK que contém duas pilhas:

anchor anchor anchor anchor anchor anchor


const app = new App();

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

app.synth();

Sobre a API da 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 um constructo é definido. Isso é útil se você precisar interagir com uma pilha de dentro de um constructo 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 opções a seguir:
- 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 informações sobre como os ambientes são determinados para pilhas, consulte Ambientes para o AWS CDK.
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 comando cdk deploy 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, 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 modelo do AWS CloudFormation , como Transformação, Descrição e Metadados, para sua pilha.

Trabalhar com pilhas do

As pilhas são implantadas como 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 comando cdk synth para uma aplicação 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 de 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 no seu código.

Por exemplo, para incluir condicionalmente um recurso em sua aplicação com base em um valor de parâmetro, você deve configurar uma condição do AWS CloudFormation 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 outro constructo, 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 ambiente de gerenciamento, um plano de dados e pilhas de monitoramento. O constructo do serviço é definido 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();
    }
}

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

type ControlPlaneStackProps struct {
	awscdk.StackProps
}

func NewControlPlaneStack(scope constructs.Construct, id string, props *ControlPlaneStackProps) awscdk.Stack {
	var sprops awscdk.StackProps
	if props != nil {
		sprops = props.StackProps
	}
	ControlPlaneStack := awscdk.NewStack(scope, jsii.String(id), &sprops)

	// The code that defines your stack goes here

	return ControlPlaneStack
}

type DataPlaneStackProps struct {
	awscdk.StackProps
}

func NewDataPlaneStack(scope constructs.Construct, id string, props *DataPlaneStackProps) awscdk.Stack {
	var sprops awscdk.StackProps
	if props != nil {
		sprops = props.StackProps
	}
	DataPlaneStack := awscdk.NewStack(scope, jsii.String(id), &sprops)

	// The code that defines your stack goes here

	return DataPlaneStack
}

type MonitoringStackProps struct {
	awscdk.StackProps
}

func NewMonitoringStack(scope constructs.Construct, id string, props *MonitoringStackProps) awscdk.Stack {
	var sprops awscdk.StackProps
	if props != nil {
		sprops = props.StackProps
	}
	MonitoringStack := awscdk.NewStack(scope, jsii.String(id), &sprops)

	// The code that defines your stack goes here

	return MonitoringStack
}

type MyServiceStackProps struct {
	awscdk.StackProps
	Prod bool
}

func NewMyServiceStack(scope constructs.Construct, id string, props *MyServiceStackProps) awscdk.Stack {
	var sprops awscdk.StackProps
	if props != nil {
		sprops = props.StackProps
	}
	MyServiceStack := awscdk.NewStack(scope, jsii.String(id), &sprops)

	NewControlPlaneStack(MyServiceStack, "cp", &ControlPlaneStackProps{
		StackProps: sprops,
	})
	NewDataPlaneStack(MyServiceStack, "data", &DataPlaneStackProps{
		StackProps: sprops,
	})
	NewMonitoringStack(MyServiceStack, "mon", &MonitoringStackProps{
		StackProps: sprops,
	})

	return MyServiceStack
}

func main() {
	defer jsii.Close()

	app := awscdk.NewApp(nil)

	betaProps := MyServiceStackProps{
		StackProps: awscdk.StackProps{
			Env: env(),
		},
		Prod: false,
	}

	NewMyServiceStack(app, "beta", &betaProps)

	prodProps := MyServiceStackProps{
		StackProps: awscdk.StackProps{
			Env: env(),
		},
		Prod: true,
	}

	NewMyServiceStack(app, "prod", &prodProps)

	app.Synth(nil)
}

// ...

anchor anchor anchor anchor anchor anchor


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

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 constructo do objeto da Stack. No entanto, você pode especificar um nome explícito usando a prop stackName (no Python, stack_name), da seguinte maneira.

anchor anchor anchor anchor anchor


new MyStack(this, 'not:a:stack:name', { stackName: 'this-is-stack-name' });

Trabalhar com pilhas aninhadas

Uma pilha aninhada é uma pilha do CDK que você cria dentro de outra pilha, conhecida como pilha principal. Você cria pilhas aninhadas usando o constructo NestedStack.

Ao usar pilhas aninhadas, você pode organizar recursos em várias pilhas. As pilhas aninhadas também oferecem 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 um constructo a Stack ou NestedStack. 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 constructos 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 por cdk 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.