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á.
# Configuração de ambientes para uso com o AWS CDK
É possível configurar ambientes da AWS de várias maneiras para usar com o kit de desenvolvimento em nuvem da AWS (CDK da AWS). O melhor método de gerenciamento de ambientes da AWS variará com base em suas necessidades específicas.
Cada pilha do CDK em sua aplicação deve eventualmente ser associada a um ambiente para determinar onde a pilha será implantada.
Para obter uma introdução aos ambientes da AWS, consulte [Ambientes para o CDK da AWS](environments.md).
## Onde você pode especificar ambientes a partir de
É possível especificar ambientes em credenciais e arquivos de configuração ou usando a propriedade ` [env](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#env) ` do constructo da `Stack` da Biblioteca de Constructos da AWS.
### Credenciais e arquivos de configuração
É possível usar a interface de linha de comandos da AWS (AWS CLI) para criar arquivos `credentials` e `config` que armazenam, organizam e gerenciam as informações do seu ambiente da AWS. Para saber mais sobre esses arquivos, consulte [Definições de arquivos de configuração e credenciais](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) no *Guia do usuário da interface de linha de comandos da AWS*.
Os valores armazenados nesses arquivos são organizados por *perfis*. A forma como você nomeia seus perfis e os pares de chave-valor nesses arquivos variará de acordo com seu método de configuração do acesso programático. Para saber mais sobre os diferentes métodos, consulte [Configuração das credenciais de segurança para a CLI do AWS CDK](configure-access.md).
Em geral, o AWS CDK resolve as informações da conta da AWS do seu arquivo `credentials` e as informações da região da AWS do seu arquivo `config`.
Depois de configurar seus arquivos `credentials` e `config`, é possível especificar o ambiente a ser usado com a CLI do AWS CDK e por meio das variáveis de ambiente.
### propriedade de ambiente do constructo da pilha
É possível especificar o ambiente para cada pilha usando a propriedade ` [env](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#env) ` do constructo da `Stack`. Essa propriedade define uma conta e uma região a serem usadas. É possível passar valores com codificação rígida para essa propriedade ou passar variáveis de ambiente que são oferecidas pelo CDK.
Para passar variáveis de ambiente, use as variáveis de ambiente `AWS_DEFAULT_ACCOUNT` e `AWS_DEFAULT_REGION`. Essas variáveis de ambiente podem passar valores de seus arquivos `credentials` e `config`. Você também pode usar a lógica em seu código do CDK para determinar os valores dessas variáveis de ambiente.
## Precedência do ambiente com o AWS CDK
Se você usa vários métodos de especificação de ambientes, o AWS CDK seguirá a precedência a seguir:
1. Valores com codificação rígida especificados com a propriedade `env` do constructo da `Stack`.
1. As variáveis de ambiente `AWS_DEFAULT_ACCOUNT` e `AWS_DEFAULT_REGION` especificadas com a propriedade `env` do constructo da `Stack`.
1. Informações do ambiente associadas ao perfil de seus arquivos `credentials` e `config` passadas para a CLI do CDK usando a opção `--profile`.
1. O perfil `default` dos seus arquivos `credentials` e `config`.
## Quando especificar ambientes
Ao desenvolver com o CDK, você começa definindo pilhas do CDK, que contêm constructos que representam recursos da AWS. Em seguida, você sintetiza cada pilha do CDK em um modelo do AWS CloudFormation. Em seguida, você implanta o modelo do CloudFormation em seu ambiente. A forma como você especifica os ambientes determina quando as informações do seu ambiente são aplicadas e pode afetar o comportamento e os resultados do CDK.
### Especifique ambientes na síntese do modelo
Quando você especifica as informações do ambiente usando a propriedade `env` do constructo da `Stack`, as informações do ambiente são aplicadas na síntese do modelo. A execução de `cdk synth` ou `cdk deploy` produz um modelo do CloudFormation específico para o ambiente.
Se você usar variáveis de ambiente na propriedade `env`, deverá usar a opção `--profile` com comandos da CLI do CDK para transmitir o perfil contendo as informações do ambiente a partir de suas credenciais e arquivos de configuração. Essas informações serão então aplicadas na síntese do modelo para produzir um modelo específico do ambiente.
As informações do ambiente no modelo do CloudFormation têm precedência sobre outros métodos. Por exemplo, se você fornecer um ambiente diferente com `cdk deploy --profile `, o perfil será ignorado.
Ao fornecer informações sobre o ambiente dessa forma, você pode usar código e lógica dependentes do ambiente em sua aplicação do CDK. Isso também significa que o modelo sintetizado pode ser diferente, com base na máquina, no usuário ou na sessão em que está sintetizado. Essa abordagem geralmente é aceitável ou desejável durante o desenvolvimento, mas não é recomendada para uso em produção.
### Especificar ambientes na implantação da pilha
Se você não especificar um ambiente usando a propriedade `env` do constructo `Stack`, a CLI do CDK produzirá um modelo do CloudFormation independente do ambiente na síntese. Em seguida, você pode especificar o ambiente no qual implantar usando `cdk deploy --profile `.
Se você não especificar um perfil ao implantar um modelo independente do ambiente, a CLI do CDK tentará usar os valores do ambiente do seu perfil `default` e dos arquivos `credentials` e `config` na implantação.
Se as informações do ambiente não estiverem disponíveis na implantação, o AWS CloudFormation tentará resolver as informações do ambiente na implantação por meio de atributos relacionados ao ambiente, como `stack.account`, `stack.region` e `stack.availabilityZones`.
Para pilhas independentes do ambiente, os constructos dentro da pilha não podem usar informações do ambiente e você não pode usar a lógica que exija informações do ambiente. Por exemplo, você não pode escrever código como `if (stack.region ==== 'us-east-1')` ou usar métodos de constructo que exijam informações do ambiente, como ` [Vpc.fromLookup](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Vpc.html#static-fromwbrlookupscope-id-options) `. Para usar esses atributos, você deve especificar um ambiente com a propriedade `env`.
Para pilhas independentes do ambiente, qualquer constructo que use zonas de disponibilidade verá duas zonas de disponibilidade, permitindo que a pilha seja implantada em qualquer região.
## Como especificar ambientes com o AWS CDK
### Especificar ambientes com codificação rígida para cada pilha
Use a propriedade `env` do constructo`Stack` para especificar valores de ambiente da AWS para sua pilha. Veja um exemplo a seguir:
**Example**
```
const envEU = { account: '2383838383', region: 'eu-west-1' };
const envUSA = { account: '8373873873', region: 'us-west-2' };
new MyFirstStack(app, 'first-stack-us', { env: envUSA });
new MyFirstStack(app, 'first-stack-eu', { env: envEU });
```
```
const envEU = { account: '2383838383', region: 'eu-west-1' };
const envUSA = { account: '8373873873', region: 'us-west-2' };
new MyFirstStack(app, 'first-stack-us', { env: envUSA });
new MyFirstStack(app, 'first-stack-eu', { env: envEU });
```
```
env_EU = cdk.Environment(account="8373873873", region="eu-west-1")
env_USA = cdk.Environment(account="2383838383", region="us-west-2")
MyFirstStack(app, "first-stack-us", env=env_USA)
MyFirstStack(app, "first-stack-eu", env=env_EU)
```
```
public class MyApp {
// Helper method to build an environment
static Environment makeEnv(String account, String region) {
return Environment.builder()
.account(account)
.region(region)
.build();
}
public static void main(final String argv[]) {
App app = new App();
Environment envEU = makeEnv("8373873873", "eu-west-1");
Environment envUSA = makeEnv("2383838383", "us-west-2");
new MyFirstStack(app, "first-stack-us", StackProps.builder()
.env(envUSA).build());
new MyFirstStack(app, "first-stack-eu", StackProps.builder()
.env(envEU).build());
app.synth();
}
}
```
```
Amazon.CDK.Environment makeEnv(string account, string region)
{
return new Amazon.CDK.Environment
{
Account = account,
Region = region
};
}
var envEU = makeEnv(account: "8373873873", region: "eu-west-1");
var envUSA = makeEnv(account: "2383838383", region: "us-west-2");
new MyFirstStack(app, "first-stack-us", new StackProps { Env=envUSA });
new MyFirstStack(app, "first-stack-eu", new StackProps { Env=envEU });
```
```
env_EU := awscdk.Environment{
Account: jsii.String("8373873873"),
Region: jsii.String("eu-west-1"),
}
env_USA := awscdk.Environment{
Account: jsii.String("2383838383"),
Region: jsii.String("us-west-2"),
}
MyFirstStack(app, "first-stack-us", &awscdk.StackProps{
Env: &env_USA,
})
MyFirstStack(app, "first-stack-eu", &awscdk.StackProps{
Env: &env_EU,
})
```
Recomendamos essa abordagem para ambientes de produção. Ao especificar explicitamente o ambiente dessa forma, você pode garantir que a pilha seja sempre implantada no ambiente específico.
### Especificar ambientes usando variáveis de ambiente
O AWS CDK fornece duas variáveis de ambiente que podem ser usadas em seu código do CDK: `CDK_DEFAULT_ACCOUNT` e `CDK_DEFAULT_REGION`. Ao usar essas variáveis de ambiente na propriedade `env` de sua instância de pilha, é possível transmitir informações do ambiente de suas credenciais e arquivos de configuração usando a opção `--profile` da CLI do CDK.
Veja a seguir um exemplo de como especificar essas variáveis de ambiente :
**Example**
Acesse variáveis de ambiente por meio do objeto `process` do Node.
Você precisa do módulo `DefinitelyTyped` para usar `process` no TypeScript. O `cdk init` instala esse módulo para você. No entanto, será necessário instalar esse módulo manualmente se estiver trabalhando com um projeto criado antes de ser adicionado ou se não tiver configurado seu projeto usando o `cdk init`.
```
npm install @types/node
```
```
new MyDevStack(app, 'dev', {
env: {
account: process.env.CDK_DEFAULT_ACCOUNT,
region: process.env.CDK_DEFAULT_REGION
}});
```
Acesse variáveis de ambiente por meio do objeto `process` do Node.
```
new MyDevStack(app, 'dev', {
env: {
account: process.env.CDK_DEFAULT_ACCOUNT,
region: process.env.CDK_DEFAULT_REGION
}});
```
Use o dicionário `environ` do módulo `os` para acessar as variáveis de ambiente.
```
import os
MyDevStack(app, "dev", env=cdk.Environment(
account=os.environ["CDK_DEFAULT_ACCOUNT"],
region=os.environ["CDK_DEFAULT_REGION"]))
```
Use `System.getenv()` para obter o valor de uma variável de ambiente.
```
public class MyApp {
// Helper method to build an environment
static Environment makeEnv(String account, String region) {
account = (account == null) ? System.getenv("CDK_DEFAULT_ACCOUNT") : account;
region = (region == null) ? System.getenv("CDK_DEFAULT_REGION") : region;
return Environment.builder()
.account(account)
.region(region)
.build();
}
public static void main(final String argv[]) {
App app = new App();
Environment envEU = makeEnv(null, null);
Environment envUSA = makeEnv(null, null);
new MyDevStack(app, "first-stack-us", StackProps.builder()
.env(envUSA).build());
new MyDevStack(app, "first-stack-eu", StackProps.builder()
.env(envEU).build());
app.synth();
}
}
```
Use `System.Environment.GetEnvironmentVariable()` para obter o valor de uma variável de ambiente.
```
Amazon.CDK.Environment makeEnv(string account=null, string region=null)
{
return new Amazon.CDK.Environment
{
Account = account ?? System.Environment.GetEnvironmentVariable("CDK_DEFAULT_ACCOUNT"),
Region = region ?? System.Environment.GetEnvironmentVariable("CDK_DEFAULT_REGION")
};
}
new MyDevStack(app, "dev", new StackProps { Env = makeEnv() });
```
```
import "os"
MyDevStack(app, "dev", &awscdk.StackProps{
Env: &awscdk.Environment{
Account: jsii.String(os.Getenv("CDK_DEFAULT_ACCOUNT")),
Region: jsii.String(os.Getenv("CDK_DEFAULT_REGION")),
},
})
```
Ao especificar ambientes usando variáveis de ambiente, é possível ter a mesma pilha do CDK sintetizada em modelos do AWS CloudFormation para ambientes diferentes. Isso significa que você pode implantar a mesma pilha do CDK em ambientes da AWS diferentes sem precisar modificar seu código do CDK. Você só precisa especificar o perfil a ser usado durante a execução do `cdk synth`.
Essa abordagem é ótima para ambientes de desenvolvimento ao implantar a mesma pilha em ambientes diferentes. No entanto, não recomendamos essa abordagem para ambientes de produção, pois o mesmo código do CDK pode sintetizar modelos diferentes, dependendo da máquina, do usuário ou da sessão em que está sintetizado.
### Especificação de ambientes a partir de suas credenciais e arquivos de configuração com a CLI do CDK
Ao implantar um modelo independente do ambiente, use a opção `--profile` com qualquer comando da CLI do CDK para especificar o perfil a ser usado. Veja a seguir um exemplo que implanta uma pilha do CDK chamada `myStack` usando o perfil `prod` definido nos arquivos `credentials` e `config`:
```
$ cdk deploy --profile
```
Para obter mais informações sobre a opção `--profile`, junto com outros comandos e opções da CLI do CDK, consulte [Referência de comandos da CLI do AWS CDK](ref-cli-cmd.md).
## Considerações ao configurar ambientes com o AWS CDK
Os serviços que você define usando constructos em suas pilhas devem oferecer suporte à região na qual você está implantando. Para obter uma lista de serviços da AWS com suporte por região, consulte [ Serviços da AWS por região](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/).
É necessário ter credenciais válidas do AWS Identity and Access Management (IAM) para realizar implantações de pilha com o AWS CDK em seus ambientes especificados.
## Exemplos
### Sintetize um modelo do CloudFormation independente do ambiente a partir de uma pilha do CDK
Neste exemplo, criamos um modelo do CloudFormation independente do ambiente a partir de nossa pilha do CDK. Em seguida, podemos implantar esse modelo em qualquer ambiente.
Veja a seguir nosso exemplo de pilha do CDK. Essa pilha define um bucket do Amazon S3 e uma saída de pilha do CloudFormation para a região do bucket. Para este exemplo, `env` não está definido:
**Example**
```
export class CdkAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Create the S3 bucket
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', {
removalPolicy: cdk.RemovalPolicy.DESTROY,
});
// Create an output for the bucket's Region
new cdk.CfnOutput(this, 'BucketRegion', {
value: bucket.env.region,
});
}
}
```
```
class CdkAppStack extends cdk.Stack {
constructor(scope, id, props) {
super(scope, id, props);
// Create the S3 bucket
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', {
removalPolicy: cdk.RemovalPolicy.DESTROY,
});
// Create an output for the bucket's Region
new cdk.CfnOutput(this, 'BucketRegion', {
value: bucket.env.region,
});
}
}
```
```
class CdkAppStack(cdk.Stack):
def __init__(self, scope: cdk.Construct, id: str, **kwargs) -> None:
super().__init__(scope, id, **kwargs)
# Create the S3 bucket
bucket = s3.Bucket(self, 'amzn-s3-demo-bucket',
removal_policy=cdk.RemovalPolicy.DESTROY
)
# Create an output for the bucket's Region
cdk.CfnOutput(self, 'BucketRegion',
value=bucket.env.region
)
```
```
public class CdkAppStack extends Stack {
public CdkAppStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
// Create the S3 bucket
Bucket bucket = Bucket.Builder.create(this, "amzn-s3-demo-bucket")
.removalPolicy(RemovalPolicy.DESTROY)
.build();
// Create an output for the bucket's Region
CfnOutput.Builder.create(this, "BucketRegion")
.value(this.getRegion())
.build();
}
}
```
```
namespace MyCdkApp
{
public class CdkAppStack : Stack
{
public CdkAppStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props)
{
// Create the S3 bucket
var bucket = new Bucket(this, "amzn-s3-demo-bucket", new BucketProps
{
RemovalPolicy = RemovalPolicy.DESTROY
});
// Create an output for the bucket's Region
new CfnOutput(this, "BucketRegion", new CfnOutputProps
{
Value = this.Region
});
}
}
}
```
```
func NewCdkAppStack(scope constructs.Construct, id string, props *CdkAppStackProps) awscdk.Stack {
stack := awscdk.NewStack(scope, &id, &props.StackProps)
// Create the S3 bucket
bucket := awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), &awss3.BucketProps{
RemovalPolicy: awscdk.RemovalPolicy_DESTROY,
})
// Create an output for the bucket's Region
awscdk.NewCfnOutput(stack, jsii.String("BucketRegion"), &awscdk.CfnOutputProps{
Value: stack.Region(),
})
return stack
}
```
Quando executamos `cdk synth`, a CLI do CDK produz um modelo do CloudFormation com o pseudoparâmetro ` AWS::Region` como valor de saída para a região do bucket. Esse parâmetro será resolvido na implantação:
```
Outputs:
BucketRegion:
Value:
Ref: AWS::Region
```
Para implantar essa pilha em um ambiente especificado no perfil `dev` de nossas credenciais e arquivos de configuração, executamos o seguinte:
```
$ cdk deploy CdkAppStack --profile dev
```
Se não especificarmos um perfil, a CLI do CDK tentará usar as informações do ambiente do perfil `default` em nossas credenciais e arquivos de configuração.
### Usar lógica para determinar as informações do ambiente na síntese do modelo
Neste exemplo, configuramos a propriedade `env` da nossa instância da `stack` para usar uma expressão válida. Especificamos duas variáveis de ambiente adicionais, `CDK_DEPLOY_ACCOUNT` e `CDK_DEPLOY_REGION`. Essas variáveis de ambiente podem substituir os padrões no momento da síntese, se existirem:
**Example**
```
new MyDevStack(app, 'dev', {
env: {
account: process.env.CDK_DEPLOY_ACCOUNT || process.env.CDK_DEFAULT_ACCOUNT,
region: process.env.CDK_DEPLOY_REGION || process.env.CDK_DEFAULT_REGION
}});
```
```
new MyDevStack(app, 'dev', {
env: {
account: process.env.CDK_DEPLOY_ACCOUNT || process.env.CDK_DEFAULT_ACCOUNT,
region: process.env.CDK_DEPLOY_REGION || process.env.CDK_DEFAULT_REGION
}});
```
```
MyDevStack(app, "dev", env=cdk.Environment(
account=os.environ.get("CDK_DEPLOY_ACCOUNT", os.environ["CDK_DEFAULT_ACCOUNT"]),
region=os.environ.get("CDK_DEPLOY_REGION", os.environ["CDK_DEFAULT_REGION"])
)
)
```
```
public class MyApp {
// Helper method to build an environment
static Environment makeEnv(String account, String region) {
account = (account == null) ? System.getenv("CDK_DEPLOY_ACCOUNT") : account;
region = (region == null) ? System.getenv("CDK_DEPLOY_REGION") : region;
account = (account == null) ? System.getenv("CDK_DEFAULT_ACCOUNT") : account;
region = (region == null) ? System.getenv("CDK_DEFAULT_REGION") : region;
return Environment.builder()
.account(account)
.region(region)
.build();
}
public static void main(final String argv[]) {
App app = new App();
Environment envEU = makeEnv(null, null);
Environment envUSA = makeEnv(null, null);
new MyDevStack(app, "first-stack-us", StackProps.builder()
.env(envUSA).build());
new MyDevStack(app, "first-stack-eu", StackProps.builder()
.env(envEU).build());
app.synth();
}
}
```
```
Amazon.CDK.Environment makeEnv(string account=null, string region=null)
{
return new Amazon.CDK.Environment
{
Account = account ??
System.Environment.GetEnvironmentVariable("CDK_DEPLOY_ACCOUNT") ??
System.Environment.GetEnvironmentVariable("CDK_DEFAULT_ACCOUNT"),
Region = region ??
System.Environment.GetEnvironmentVariable("CDK_DEPLOY_REGION") ??
System.Environment.GetEnvironmentVariable("CDK_DEFAULT_REGION")
};
}
new MyDevStack(app, "dev", new StackProps { Env = makeEnv() });
```
```
var account, region string
var b bool
if account, b = os.LookupEnv("CDK_DEPLOY_ACCOUNT"); !b || len(account) == 0 {
account = os.Getenv("CDK_DEFAULT_ACCOUNT")
}
if region, b = os.LookupEnv("CDK_DEPLOY_REGION"); !b || len(region) == 0 {
region = os.Getenv("CDK_DEFAULT_REGION")
}
MyDevStack(app, "dev", &awscdk.StackProps{
Env: &awscdk.Environment{
Account: &account,
Region: ®ion,
},
})
```
Com o ambiente da nossa pilha declarado dessa forma, podemos escrever um script curto ou arquivo em lote, definir variáveis a partir dos argumentos da linha de comando e, em seguida, chamar `cdk deploy`. Veja um exemplo a seguir. Todos os argumentos além dos dois primeiros são passados para `cdk deploy` para especificar as opções ou argumentos da linha de comando:
**Example**
```
#!/usr/bin/env bash
if [[ $# -ge 2 ]]; then
export CDK_DEPLOY_ACCOUNT=$1
export CDK_DEPLOY_REGION=$2
shift; shift
npx cdk deploy "$@"
exit $?
else
echo 1>&2 "Provide account and region as first two args."
echo 1>&2 "Additional args are passed through to cdk deploy."
exit 1
fi
```
Salve o script como `cdk-deploy-to.sh` e execute `chmod +x cdk-deploy-to.sh` para torná-lo executável.
```
@findstr /B /V @ %~dpnx0 > %~dpn0.ps1 && powershell -ExecutionPolicy Bypass %~dpn0.ps1 %*
@exit /B %ERRORLEVEL%
if ($args.length -ge 2) {
$env:CDK_DEPLOY_ACCOUNT, $args = $args
$env:CDK_DEPLOY_REGION, $args = $args
npx cdk deploy $args
exit $lastExitCode
} else {
[console]::error.writeline("Provide account and region as first two args.")
[console]::error.writeline("Additional args are passed through to cdk deploy.")
exit 1
}
```
A versão do Windows do script usa o PowerShell para fornecer a mesma funcionalidade da versão macOS/Linux. Ela também contém instruções para permitir que seja executada como um arquivo em lotes para que possa ser facilmente invocada a partir de uma linha de comando. Ela deve ser salva como `cdk-deploy-to.bat`. O arquivo `cdk-deploy-to.ps1` será criado quando o arquivo em lotes for invocado.
Em seguida, podemos escrever scripts adicionais que usam o script `cdk-deploy-to` para implantar em ambientes específicos. Veja um exemplo a seguir:
**Example**
```
#!/usr/bin/env bash
# cdk-deploy-to-test.sh
./cdk-deploy-to.sh 123457689 us-east-1 "$@"
```
```
@echo off
rem cdk-deploy-to-test.bat
cdk-deploy-to 135792469 us-east-1 %*
```
Veja a seguir um exemplo que usa o script `cdk-deploy-to` para implantar em vários ambientes. Se a primeira implantação falhar, o processo será interrompido:
**Example**
```
#!/usr/bin/env bash
# cdk-deploy-to-prod.sh
./cdk-deploy-to.sh 135792468 us-west-1 "$@" || exit
./cdk-deploy-to.sh 246813579 eu-west-1 "$@"
```
```
@echo off
rem cdk-deploy-to-prod.bat
cdk-deploy-to 135792469 us-west-1 %* || exit /B
cdk-deploy-to 245813579 eu-west-1 %*
```