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

Valores de contexto e o AWS CDK

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

O CDK kit de ferramentas 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 a Amazon Machine Image (AMI) IDs atualmente disponível para EC2 instâncias da Amazon. Como esses valores são fornecidos pela sua AWS conta, eles podem mudar entre as execuções do seu CDK aplicativo. Isso os torna uma fonte potencial de mudanças não intencionais. O comportamento de armazenamento em cache do CDK kit de ferramentas “congela” esses valores para seu CDK aplicativo até que você decida aceitar os novos valores.

Imagine o cenário a seguir sem o armazenamento em cache do contexto. Digamos que você especificou a “versão mais recente do Amazon Linux” AMI para suas EC2 instâncias da Amazon e uma nova versão AMI foi lançada. Então, na próxima vez que você implantasse sua CDK pilha, suas instâncias já implantadas usariam o desatualizado (“errado”) AMI 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, os CDK registros de sua conta estão disponíveis AMIs no cdk.context.json arquivo do seu projeto e usam o valor armazenado para futuras operações de síntese. Dessa forma, a lista de não AMIs é 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. AWS CDK bandeiras de destaquetambém são valores de contexto. Você também pode criar seus próprios valores de contexto para uso pelos suas aplicações ou constructos.

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

Muitos valores de contexto estão associados a um AWS ambiente específico, e um determinado CDK aplicativo 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 o constructo que os criou; eles são visíveis para constructos secundários, mas não para principais 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 no constructo do App. Portanto, eles são visíveis para todas os constructos em todas as pilhas da aplicação.

Seu aplicação pode ler um valor de contexto usando o método construct.node.tryGetContext. Se a entrada solicitada não for encontrada no constructo atual ou em qualquer um de seus principais, o resultado será undefined. (Como alternativa, o resultado pode ser equivalente à sua linguagem, como None no 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 a pilha. availabilityZonesmétodo.

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, CLI ele consulta as informações na AWS conta corrente e armazena as informações de contexto resultantes no cdk.context.json arquivo. Em seguida, ele executa o AWS CDK aplicativo novamente com os valores de contexto.

Visualizar e gerenciar o contexto

Use o comando cdk context para visualizar e gerenciar as informações em seu arquivo cdk.context.json. Para ver essas informações, use o comando cdk context sem nenhuma opção. A saída deve ser semelhante ao 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, execute cdk 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 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 LinuxAMI, use o exemplo anterior para fazer uma atualização controlada do valor do contexto e redefini-lo. Em seguida, sintetize e implante sua aplicação novamente.

cdk synth

Para limpar todos os valores de contexto armazenados para sua aplicação, execute cdk context --clear da seguinte maneira.

cdk context --clear

Somente os valores de contexto armazenados em 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 para cdk.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 CDK aplicativo durante a síntese ou a implantação.

cdk synth --context key=value MyStack

Para especificar vários valores de contexto, repita a opção --context quantas vezes quiser, fornecendo um par de valor-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 comandos cdk synth ou cdk deploy.

Os valores de contexto passados da linha de comando são sempre strings. 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, em cdk.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 de uso de uma Amazon existente VPC usando o 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"
    ]
  }
}