Este é o Guia do Desenvolvedor AWS CDK v2. A CDK v1 mais antiga 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á.
Introdução às AWS CDK pilhas
Uma AWS CDK pilha é a menor unidade única de implantação. Ela representa uma coleção de AWS recursos que você define usando CDK construções. Quando você implanta CDK aplicativos, os recursos em uma CDK pilha são implantados juntos como uma AWS CloudFormation pilha. Para saber mais sobre AWS CloudFormation pilhas, consulte Gerenciamento de AWS recursos 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 CDK pilha 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)
}
//...
O exemplo anterior definiu apenas uma pilha. Para criar a pilha, ela deve ser instanciada dentro do contexto do seu aplicativo. CDK Um padrão comum é definir seu CDK aplicativo e inicializar sua pilha em um arquivo separado, conhecido como arquivo de aplicativo.
Veja a seguir um exemplo que cria uma CDK pilha chamadaMyCdkStack
. Aqui, o CDK aplicativo é criado e MyCdkStack
instanciado no contexto do aplicativo:
- TypeScript
-
#!/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', {
});
- JavaScript
-
#!/usr/bin/env node
const cdk = require('aws-cdk-lib');
const { MyCdkStack } = require('../lib/my-cdk-stack');
const app = new cdk.App();
new MyCdkStack(app, 'MyCdkStack', {
});
- Python
-
Localizado em app.py
:
#!/usr/bin/env python3
import os
import aws_cdk as cdk
from my_cdk.my_cdk_stack import MyCdkStack
app = cdk.App()
MyCdkStack(app, "MyCdkStack",)
app.synth()
- Java
-
package com.myorg;
import software.amazon.awscdk.App;
import software.amazon.awscdk.Environment;
import software.amazon.awscdk.StackProps;
import java.util.Arrays;
public class MyCdkApp {
public static void main(final String[] args) {
App app = new App();
new MyCdkStack(app, "MyCdkStack", StackProps.builder()
.build());
app.synth();
}
}
- C#
-
using Amazon.CDK;
using System;
using System.Collections.Generic;
using System.Linq;
namespace MyCdk
{
sealed class Program
{
public static void Main(string[] args)
{
var app = new App();
new MyCdkStack(app, "MyCdkStack", new StackProps
{});
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"
)
// ...
func main() {
defer jsii.Close()
app := awscdk.NewApp(nil)
NewMyCdkStack(app, "MyCdkStack", &MyCdkStackProps{
awscdk.StackProps{
Env: env(),
},
})
app.Synth(nil)
}
// ...
O exemplo a seguir cria um CDK aplicativo 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();
- 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 MyFirstStackProps struct {
awscdk.StackProps
}
func NewMyFirstStack(scope constructs.Construct, id string, props *MyFirstStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
myFirstStack := awscdk.NewStack(scope, &id, &sprops)
// The code that defines your stack goes here
return myFirstStack
}
type MySecondStackProps struct {
awscdk.StackProps
}
func NewMySecondStack(scope constructs.Construct, id string, props *MySecondStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
mySecondStack := awscdk.NewStack(scope, &id, &sprops)
// The code that defines your stack goes here
return mySecondStack
}
func main() {
defer jsii.Close()
app := awscdk.NewApp(nil)
NewMyFirstStack(app, "MyFirstStack", &MyFirstStackProps{
awscdk.StackProps{
Env: env(),
},
})
NewMySecondStack(app, "MySecondStack", &MySecondStackProps{
awscdk.StackProps{
Env: env(),
},
})
app.Synth(nil)
}
// ...
Sobre a pilha API
O Stack
objeto fornece uma riquezaAPI, 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.region
e 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.stackId
Python:) e (stack.notificationArn
Python: stack_id
notification_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 JSON string 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.
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)
}
// ...
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.
- 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"
});
Trabalhar com pilhas aninhadas
Uma pilha aninhada é uma CDK pilha 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.
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.