Los valores de contexto y el AWS CDK

Los valores de contexto son pares clave-valor que pueden asociarse a una aplicación, pila o constructo. Se pueden proporcionar a la aplicación desde un archivo (generalmente, cdk.json o cdk.context.json en el directorio del proyecto) o en la línea de comandos.

El kit de herramientas CDK utiliza el contexto para almacenar en caché los valores recuperados de su AWS cuenta durante la síntesis. Los valores incluyen las zonas de disponibilidad de su cuenta o la imagen de máquina de Amazon (AMI) disponible IDs actualmente para EC2 las instancias de Amazon. Como estos valores los proporciona su AWS cuenta, pueden cambiar de una ejecución a otra de la aplicación de CDK. Esto los convierte en una posible fuente de cambios no deseados. El comportamiento de almacenamiento en memoria caché del kit de herramientas de CDK “congela” estos valores para la aplicación de CDK hasta que usted decida aceptar los valores nuevos.

Imagine el siguiente escenario sin almacenamiento en memoria caché de contexto. Supongamos que especificó la «última versión de Amazon Linux» como AMI para sus EC2 instancias de Amazon y se publicó una nueva versión de esta AMI. Entonces, la próxima vez que implemente su pila de CDK, las instancias ya implementadas utilizarán la AMI obsoleta (“incorrecta”) y deberán actualizarse. La actualización implicaría la sustitución de todas las instancias existentes por otras nuevas, lo que probablemente no sea lo deseado ni lo esperado.

En su lugar, la CDK registra la disponibilidad de su cuenta AMIs en el cdk.context.json archivo de su proyecto y utiliza el valor almacenado para futuras operaciones de síntesis. De esta forma, la lista de AMIs deja de ser una fuente potencial de cambio. También puedes estar seguro de que tus pilas siempre se sintetizarán en las mismas AWS CloudFormation plantillas.

No todos los valores de contexto son valores en caché de su entorno. AWS AWS CDK indicadores de característicastambién son valores de contexto. También puede crear sus propios valores de contexto para que sus aplicaciones o constructos los utilicen.

Las claves de contexto son cadenas. Los valores pueden ser de cualquier tipo compatible con JSON: números, cadenas, matrices u objetos.

Muchos valores de contexto están asociados a un AWS entorno concreto, y una aplicación de CDK determinada se puede implementar en más de un entorno. La clave de dichos valores incluye la AWS cuenta y la región, de modo que los valores de distintos entornos no entren en conflicto.

La siguiente clave de contexto ilustra el formato utilizado por la cuenta y la región AWS CDK, incluidas la cuenta y la región.

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

Orígenes de los valores de contexto

Los valores de contexto se pueden proporcionar a tu AWS CDK aplicación de seis maneras diferentes:

El archivo del proyecto cdk.context.json es donde se almacenan en AWS CDK caché los valores de contexto recuperados de tu AWS cuenta. Esta práctica evita cambios inesperados en las implementaciones cuando, por ejemplo, se introduce una zona de disponibilidad nueva. AWS CDK No escribe datos de contexto en ninguno de los otros archivos de la lista.

Los valores de contexto se asignan al constructo que los creó; son visibles para los constructos secundarios, pero no para los principales o del mismo nivel. Los valores de contexto que establece el AWS CDK kit de herramientas (el cdk comando) se pueden configurar automáticamente, desde un archivo o desde la --context opción. Los valores de contexto de estos orígenes se establecen de manera implícita en el constructo App. Por lo tanto, son visibles para todos los constructos de todas las pilas de la aplicación.

Su aplicación puede leer un valor de contexto mediante el método construct.node.tryGetContext. Si la entrada solicitada no se encuentra en el constructo actual ni en ninguno de los principales, el resultado será undefined. (Como alternativa, el resultado podría ser el equivalente en su lenguaje, como None en Python).

Métodos de context

AWS CDK Admite varios métodos de contexto que permiten a AWS CDK las aplicaciones obtener información contextual del AWS entorno. Por ejemplo, puede obtener una lista de las zonas de disponibilidad que están disponibles en una AWS cuenta y región determinadas mediante el método stack.AvailabilityZones.

Los métodos de contexto son los siguientes:

Si el valor de contexto obligatorio no está disponible, la AWS CDK aplicación notifica al CDK Toolkit que falta la información de contexto. A continuación, la CLI consulta la información en la AWS cuenta corriente y almacena la información de contexto resultante en el cdk.context.json archivo. A continuación, vuelve a ejecutar la AWS CDK aplicación con los valores de contexto.

Visualización y administración del contexto

Utilice el comando cdk context para ver y administrar la información del archivo cdk.context.json. Para ver esta información, utilice el comando cdk context sin ninguna opción. El resultado debería verse de la siguiente manera.

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 eliminar un valor de contexto, ejecute cdk context --reset y especifique la clave o el número correspondiente al valor. En el siguiente ejemplo, se elimina el valor que corresponde a la segunda clave del ejemplo anterior. Este valor representa la lista de zonas de disponibilidad de la región de 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.

Por lo tanto, si desea actualizar a la última versión de la AMI de Amazon Linux, utilice el ejemplo anterior para realizar una actualización controlada del valor de contexto y restablecerlo. Luego, sintetice y vuelva a implementar la aplicación.

cdk synth

Para borrar todos los valores de contexto almacenados de su aplicación, ejecute cdk context --clear, como se muestra a continuación.

cdk context --clear

Solo se pueden restablecer o borrar los valores de contexto almacenados en cdk.context.json. No AWS CDK afecta a otros valores de contexto. Por lo tanto, para evitar que un valor de contexto se restablezca mediante estos comandos, puede copiar el valor en cdk.json.

AWS CDK Bandera del kit de herramientas --context

Utilice la opción --context (-c abreviada) para pasar los valores de contexto de tiempo de ejecución a su aplicación de CDK durante la síntesis o la implementación.

cdk synth --context key=value MyStack

Para especificar varios valores de contexto, repita la opción --context tantas veces como desee y proporcione un par clave-valor cada vez que repita la acción.

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

Cuando se sintetizan varias pilas, los valores de contexto especificados se transfieren a todas las pilas. Para proporcionar diferentes valores de contexto a pilas individuales, utilice diferentes claves para los valores o utilice varios comandos cdk synth o cdk deploy.

Los valores de contexto que se pasan desde la línea de comandos son siempre cadenas. Si un valor suele ser de otro tipo, el código debe estar preparado para convertir o analizar el valor. Es posible que los valores de contexto que no sean cadenas se proporcionen de otras formas (por ejemplo, en cdk.context.json). Para asegurarse de que este tipo de valor funciona según lo esperado, confirme que el valor es una cadena antes de convertirlo.

Ejemplo

A continuación se muestra un ejemplo del uso de una Amazon VPC existente mediante AWS CDK el contexto.

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

Puede utilizar cdk diff para ver los efectos de pasar un valor de contexto en la línea de comandos:

cdk diff -c vpcid=vpc-0cb9c31031d0d3e22

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

Los valores de contexto resultantes pueden verse como se muestra a continuación.

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"
    ]
  }
}