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

Contexto de runtime

Os valores de contexto são pares de chave-valor que podem ser associados a um aplicativo, pilha ou estrutura. Eles podem ser fornecidos ao seu aplicativo a partir de um arquivo (geralmente cdk.json ou cdk.context.json no diretório do projeto) ou na linha de comando.

O CDK Toolkit usa contexto para armazenar em cache os valores recuperados da sua AWS conta durante a síntese. Os valores incluem as zonas de disponibilidade em sua conta ou os IDs da Amazon Machine Image (AMI) atualmente disponíveis para instâncias do Amazon EC2. Como esses valores são fornecidos pela sua AWS conta, eles podem mudar entre as execuções do seu aplicativo CDK. Isso os torna uma fonte potencial de mudanças não intencionais. O comportamento de armazenamento em cache do CDK Toolkit “congela” esses valores para seu aplicativo CDK até que você decida aceitar os novos valores.

Imagine o cenário a seguir sem o cache de contexto. Digamos que você especificou “Amazon Linux mais recente” como a AMI para suas instâncias do Amazon EC2 e uma nova versão dessa AMI foi lançada. Então, na próxima vez que você implantasse sua pilha de CDK, suas instâncias já implantadas usariam a AMI desatualizada (“errada”) e precisariam ser atualizadas. A atualização resultaria na substituição de todas as suas instâncias existentes por novas, o que provavelmente seria inesperado e indesejado.

Em vez disso, o CDK registra as AMIs disponíveis da sua conta no cdk.context.json arquivo do seu projeto e usa o valor armazenado para futuras operações de síntese. Dessa forma, a lista de AMIs não é mais uma fonte potencial de mudança. Você também pode ter certeza de que suas pilhas sempre serão sintetizadas nos mesmos modelos. AWS CloudFormation

Nem todos os valores de contexto são valores armazenados em cache do seu AWS ambiente. Sinalizadores de destaquetambém são valores de contexto. Você também pode criar seus próprios valores de contexto para uso por seus aplicativos ou construções.

As chaves de contexto são cadeias de caracteres. Os valores podem ser de qualquer tipo suportado pelo JSON: números, cadeias de caracteres, matrizes ou objetos.

Muitos valores de contexto estão associados a um AWS ambiente específico, e um determinado aplicativo CDK pode ser implantado em mais de um ambiente. A chave para esses valores inclui a AWS conta e a região, para que os valores de diferentes ambientes não entrem em conflito.

A chave de contexto a seguir ilustra o formato usado pelo AWS CDK, incluindo a conta e a região.

availability-zones:account=123456789012:region=eu-central-1

Fontes de valores de contexto

Os valores de contexto podem ser fornecidos ao seu AWS CDK aplicativo de seis maneiras diferentes:

O arquivo do projeto cdk.context.json é onde os valores de contexto são armazenados em AWS CDK cache recuperados da sua AWS conta. Essa prática evita mudanças inesperadas em suas implantações quando, por exemplo, uma nova zona de disponibilidade é introduzida. O AWS CDK não grava dados de contexto em nenhum dos outros arquivos listados.

Os valores de contexto têm como escopo a construção que os criou; eles são visíveis para construções infantis, mas não para pais ou irmãos. Os valores de contexto definidos pelo AWS CDK Toolkit (o cdk comando) podem ser definidos automaticamente, a partir de um arquivo ou da --context opção. Os valores de contexto dessas fontes são definidos implicitamente na App construção. Portanto, eles são visíveis para todas as construções em todas as pilhas do aplicativo.

Seu aplicativo pode ler um valor de contexto usando o construct.node.tryGetContext método. Se a entrada solicitada não for encontrada na construção atual ou em qualquer um de seus pais, o resultado seráundefined. (Como alternativa, o resultado pode ser equivalente à sua linguagem, como None em Python.)

Métodos de contexto

O AWS CDK suporta vários métodos de contexto que permitem que AWS CDK os aplicativos obtenham informações contextuais do AWS ambiente. Por exemplo, você pode obter uma lista de zonas de disponibilidade que estão disponíveis em uma determinada AWS conta e região usando o método stack.availabilityZones.

A seguir estão os métodos de contexto:

Se um valor de contexto necessário não estiver disponível, o AWS CDK aplicativo notifica o CDK Toolkit de que as informações de contexto estão ausentes. Em seguida, a CLI consulta as informações na AWS conta atual e armazena as informações de contexto resultantes no arquivo. cdk.context.json Em seguida, ele executa o AWS CDK aplicativo novamente com os valores de contexto.

Visualizando e gerenciando o contexto

Use o cdk context comando para visualizar e gerenciar as informações em seu cdk.context.json arquivo. Para ver essas informações, use o cdk context comando sem nenhuma opção. A saída deve ser algo parecido com o seguinte.

Context found in cdk.json:

┌───┬─────────────────────────────────────────────────────────────┬─────────────────────────────────────────────────────────┐
│ # │ Key                                                         │ Value                                                   │
├───┼─────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────┤
│ 1 │ availability-zones:account=123456789012:region=eu-central-1 │ [ "eu-central-1a", "eu-central-1b", "eu-central-1c" ]   │
├───┼─────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────┤
│ 2 │ availability-zones:account=123456789012:region=eu-west-1    │ [ "eu-west-1a", "eu-west-1b", "eu-west-1c" ]            │
└───┴─────────────────────────────────────────────────────────────┴─────────────────────────────────────────────────────────┘

Run cdk context --reset KEY_OR_NUMBER to remove a context key. If it is a cached value, it will be refreshed on the next cdk synth.

Para remover um valor de contexto, executecdk context --reset, especificando a chave ou o número correspondente do valor. O exemplo a seguir remove o valor que corresponde à segunda chave no exemplo anterior. Esse valor representa a lista de zonas de disponibilidade na região da Europa (Irlanda).

cdk context --reset 2

Context value
availability-zones:account=123456789012:region=eu-west-1
reset. It will be refreshed on the next SDK synthesis run.

Portanto, se você quiser atualizar para a versão mais recente do Amazon Linux AMI, use o exemplo anterior para fazer uma atualização controlada do valor do contexto e redefini-lo. Em seguida, sintetize e implante seu aplicativo novamente.

cdk synth

Para limpar todos os valores de contexto armazenados para seu aplicativocdk context --clear, execute da seguinte maneira.

cdk context --clear

Somente os valores de contexto armazenados cdk.context.json podem ser redefinidos ou apagados. AWS CDK Isso não afeta outros valores de contexto. Portanto, para evitar que um valor de contexto seja redefinido usando esses comandos, você pode copiar o valor paracdk.json.

AWS CDK Sinalizador do kit de ferramentas --context

Use a opção --context (abreviada) -c para passar valores de contexto de tempo de execução para seu aplicativo CDK durante a síntese ou a implantação.

cdk synth --context key=value MyStack

Para especificar vários valores de contexto, repita a --context opção quantas vezes quiser, fornecendo um par de valores-chave a cada vez.

cdk synth --context key1=value1 --context key2=value2 MyStack

Ao sintetizar várias pilhas, os valores de contexto especificados são passados para todas as pilhas. Para fornecer valores de contexto diferentes para pilhas individuais, use chaves diferentes para os valores ou use vários cdk synth cdk deploy comandos.

Os valores de contexto passados da linha de comando são sempre cadeias de caracteres. Se um valor geralmente é de algum outro tipo, seu código deve estar preparado para converter ou analisar o valor. Você pode ter valores de contexto que não sejam de string fornecidos de outras formas (por exemplo, emcdk.context.json). Para garantir que esse tipo de valor funcione conforme o esperado, confirme se o valor é uma string antes de convertê-lo.

Exemplo

Veja a seguir um exemplo do uso de uma Amazon VPC existente usando AWS CDK contexto.

TypeScript

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

export class ExistsVpcStack extends cdk.Stack {

  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
  
    super(scope, id, props);
    
    const vpcid = this.node.tryGetContext('vpcid');
    const vpc = ec2.Vpc.fromLookup(this, 'VPC', {
      vpcId: vpcid,
    });
    
    const pubsubnets = vpc.selectSubnets({subnetType: ec2.SubnetType.PUBLIC});
    
    new cdk.CfnOutput(this, 'publicsubnets', {
      value: pubsubnets.subnetIds.toString(),
    });
  }
}

JavaScript

const cdk = require('aws-cdk-lib');
const ec2 = require('aws-cdk-lib/aws-ec2');

class ExistsVpcStack extends cdk.Stack {

  constructor(scope, id, props) {
  
    super(scope, id, props);
    
    const vpcid = this.node.tryGetContext('vpcid');
    const vpc = ec2.Vpc.fromLookup(this, 'VPC', {
      vpcId: vpcid
    });
    
    const pubsubnets = vpc.selectSubnets({subnetType: ec2.SubnetType.PUBLIC});
    
    new cdk.CfnOutput(this, 'publicsubnets', {
      value: pubsubnets.subnetIds.toString()
    });
  }
}

module.exports = { ExistsVpcStack }

Python

import aws_cdk as cdk
import aws_cdk.aws_ec2 as ec2
from constructs import Construct

class ExistsVpcStack(cdk.Stack):

    def __init__(scope: Construct, id: str, **kwargs):
  
        super().__init__(scope, id, **kwargs)
    
        vpcid = self.node.try_get_context("vpcid")
        vpc = ec2.Vpc.from_lookup(self, "VPC", vpc_id=vpcid)
    
        pubsubnets = vpc.select_subnets(subnetType=ec2.SubnetType.PUBLIC)
    
        cdk.CfnOutput(self, "publicsubnets",
            value=pubsubnets.subnet_ids.to_string())

Java

import software.amazon.awscdk.CfnOutput;

import software.amazon.awscdk.services.ec2.Vpc;
import software.amazon.awscdk.services.ec2.VpcLookupOptions;
import software.amazon.awscdk.services.ec2.SelectedSubnets;
import software.amazon.awscdk.services.ec2.SubnetSelection;
import software.amazon.awscdk.services.ec2.SubnetType;
import software.constructs.Construct;

public class ExistsVpcStack extends Stack {
    public ExistsVpcStack(Construct context, String id) {
        this(context, id, null);
    }
    
    public ExistsVpcStack(Construct context, String id, StackProps props) {
        super(context, id, props);
        
        String vpcId = (String)this.getNode().tryGetContext("vpcid");
        Vpc vpc = (Vpc)Vpc.fromLookup(this, "VPC", VpcLookupOptions.builder()
                .vpcId(vpcId).build());

        SelectedSubnets pubSubNets = vpc.selectSubnets(SubnetSelection.builder()
                .subnetType(SubnetType.PUBLIC).build());
        
        CfnOutput.Builder.create(this, "publicsubnets")
                .value(pubSubNets.getSubnetIds().toString()).build();                
    }
}

C#

using Amazon.CDK;
using Amazon.CDK.AWS.EC2;
using Constructs;

class ExistsVpcStack : Stack
{
    public ExistsVpcStack(Construct scope, string id, StackProps props) : base(scope, id, props)
    {
        var vpcId = (string)this.Node.TryGetContext("vpcid");
        var vpc = Vpc.FromLookup(this, "VPC", new VpcLookupOptions
        {
            VpcId = vpcId
        });

        SelectedSubnets pubSubNets = vpc.SelectSubnets([new SubnetSelection
        {
            SubnetType = SubnetType.PUBLIC
        }]);

        new CfnOutput(this, "publicsubnets", new CfnOutputProps {
            Value = pubSubNets.SubnetIds.ToString()
        });
    }
}

Você pode usar cdk diff para ver os efeitos da transmissão de um valor de contexto na linha de comando:

cdk diff -c vpcid=vpc-0cb9c31031d0d3e22

Stack ExistsvpcStack
Outputs
[+] Output publicsubnets publicsubnets: {"Value":"subnet-06e0ea7dd302d3e8f,subnet-01fc0acfb58f3128f"}

Os valores de contexto resultantes podem ser visualizados conforme mostrado aqui.

cdk context -j

{
  "vpc-provider:account=123456789012:filter.vpc-id=vpc-0cb9c31031d0d3e22:region=us-east-1": {
    "vpcId": "vpc-0cb9c31031d0d3e22",
    "availabilityZones": [
      "us-east-1a",
      "us-east-1b"
    ],
    "privateSubnetIds": [
      "subnet-03ecfc033225be285",
      "subnet-0cded5da53180ebfa"
    ],
    "privateSubnetNames": [
      "Private"
    ],
    "privateSubnetRouteTableIds": [
      "rtb-0e955393ced0ada04",
      "rtb-05602e7b9f310e5b0"
    ],
    "publicSubnetIds": [
      "subnet-06e0ea7dd302d3e8f",
      "subnet-01fc0acfb58f3128f"
    ],
    "publicSubnetNames": [
      "Public"
    ],
    "publicSubnetRouteTableIds": [
      "rtb-00d1fdfd823c82289",
      "rtb-04bb1969b42969bcb"
    ]
  }
}