Fontes de valores de contexto Métodos de contexto Visualizar e gerenciar o contexto Sinalizador --context do Kit de Ferramentas CDK da AWS Exemplo

Valores de contexto e o AWS CDK

Os valores de contexto são pares de chave-valor 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 Kit de Ferramentas CDK usa contexto para armazenar em cache os valores recuperados da sua conta da AWS durante a síntese. Os valores incluem as zonas de disponibilidade na sua conta ou os IDs da imagem de máquina da Amazon (AMI) atualmente disponíveis para instâncias do Amazon EC2. Como esses valores são fornecidos pela sua conta da AWS, eles podem mudar entre as execuções da sua aplicação do CDK. Isso os torna uma fonte potencial de mudanças não intencionais. O comportamento de armazenamento em cache do Kit de Ferramentas CDK "congela" esses valores em sua aplicação do CDK até que você decida aceitar os novos valores.

Imagine o cenário a seguir sem o armazenamento em cache do contexto. Digamos que você tenha especificado “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 do 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 arquivo cdk.context.json 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 do AWS CloudFormation.

Nem todos os valores de contexto são valores armazenados em cache a partir do seu ambiente da AWS. AWS Os sinalizadores de atributos do CDK també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 compatível com o JSON: números, strings, matrizes ou objetos.

dica

Se seus constructos criarem seus próprios valores de contexto, incorpore o nome do pacote da sua biblioteca em suas chaves para que não entrem em conflito com os valores de contexto de outros pacotes.

Muitos valores de contexto estão associados a um ambiente da AWS específico, e um determinada aplicação do CDK pode ser implantado em mais de um ambiente. A chave para esses valores inclui a conta e a região da AWS, 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

Importante

Os valores de contexto armazenados em cache são gerenciados pelo AWS CDK e seus constructos, incluindo constructos que você possa escrever. Não adicione nem altere valores de contexto armazenados em cache editando arquivos manualmente. No entanto, pode ser útil revisar cdk.context.json ocasionalmente para ver quais valores estão sendo armazenados em cache. Os valores de contexto que não representam valores armazenados em cache devem ser armazenados sob a chave context de cdk.json. Dessa forma, eles não serão apagados quando os valores armazenados em cache forem limpos.

Fontes de valores de contexto

Os valores de contexto podem ser fornecidos à sua aplicação do AWS CDK de seis maneiras diferentes:

Automaticamente da conta da AWS atual.
Através da opção --context para o comando cdk. (Esses valores são sempre strings.)
No arquivo cdk.context.json do projeto.
Na chave context do arquivo cdk.json do projeto.
Na chave context do seu arquivo ~/.cdk.json.
Em sua aplicação do AWS CDK usando o método construct.node.setContext().

O arquivo do projeto cdk.context.json é onde o AWS CDK armazena valores de contexto em cache recuperados da sua conta da AWS. 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.

Importante

Como eles fazem parte do estado da sua aplicação, cdk.json e cdk.context.json devem estar comprometidos com o controle da fonte junto com o restante do código-fonte da sua aplicação. Caso contrário, implantações em outros ambientes (por exemplo, um pipeline de CI) podem produzir resultados inconsistentes.

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 Kit de Ferramentas CDK da AWS (o comando cdk) podem ser definidos automaticamente, a partir de um arquivo ou da opção --context. Os valores de contexto dessas fontes são definidos implicitamente no constructo do App. Portanto, eles são visíveis para todos 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 oferece suporte a vários métodos de contexto que permitem que as aplicações do AWS CDK obtenham informações contextuais do ambiente da AWS. Por exemplo, é possível obter uma lista de zonas de disponibilidade que estão disponíveis em uma determinada conta e região da AWS usando o método stack.availabilityZones.

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

HostedZone.fromLookup: Obtém as zonas hospedadas em sua conta.
stack.availabilityZones: Obtém as zonas de disponibilidade compatíveis.
StringParameter.valueFromLookup: Obtém um valor do armazenamento do Amazon EC2 Systems Manager Parameter Store da região atual.
Vpc.fromLookup: Obtém as nuvens privadas virtuais da Amazon existentes em suas contas.
LookupMachineImage: Pesquisa uma imagem de máquina para uso com uma instância NAT na nuvem privada virtual da Amazon.

Se um valor de contexto necessário não estiver disponível, a aplicação do AWS CDK notifica o Kit de Ferramentas CDK de que as informações de contexto estão ausentes. Em seguida, a CLI consulta as informações na conta atual da AWS e armazena as informações de contexto resultantes no arquivo cdk.context.json. Em seguida, ele executa a aplicação do AWS CDK 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 Linux AMI, 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. O AWS CDK 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.

Sinalizador `--context` do Kit de Ferramentas CDK da AWS

Use a opção --context (-c abreviada) para passar valores de contexto de runtime para sua aplicação do CDK 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 chave-valor 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. É possível 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

A seguir está um exemplo de uso de uma Amazon VPC existente usando contexto do AWS CDK.

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

É possível 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"
    ]
  }
}

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Permissões

Sinalizadores de atributo