Las etiquetas y el AWS CDK - AWS Cloud Development Kit (AWS CDK) v2
Uso de etiquetasPrioridades de etiquetaPropiedades opcionalesEjemploEtiquetado de constructos individuales

Esta es la segunda versión de la Guía para desarrolladores de AWS CDK. La primera versión del CDK pasó a la etapa de mantenimiento el 1.° de junio de 2022 y no cuenta con soporte desde el 1.° de junio de 2023.

Las etiquetas y el AWS CDK

Las etiquetas son elementos de clave-valor de información que puede agregar a los constructos de su aplicación de AWS CDK. Una etiqueta aplicada a un constructo determinado también se aplica a todos sus elementos secundarios que se pueden etiquetar. Las etiquetas se incluyen en la plantilla de AWS CloudFormation sintetizada a partir de la aplicación y se aplican a los recursos de AWS que implementa. Puede utilizar etiquetas para identificar y clasificar los recursos con los siguientes fines:

  • Administración simplificada

  • Asignación de costos

  • Control de acceso

  • Cualquier otra finalidad que se le ocurra

sugerencia

Para obtener más información sobre cómo utilizar las etiquetas con los recursos de AWS, consulte las Prácticas recomendadas para etiquetar los recursos de AWS en el documento técnico de AWS.

Uso de etiquetas

La clase de Tags incluye el método estático of(), mediante el cual puede agregar o eliminar etiquetas del constructo especificado.

  • El código Tags.of(SCOPE).add() aplica una nueva etiqueta a un constructo determinado y a todos sus elementos secundarios.

  • El código Tags.of(SCOPE).remove() elimina una etiqueta de un constructo determinado y de cualquiera de sus elementos secundarios, incluidas las etiquetas que un constructo secundario pueda haberse aplicado a sí mismo.

nota

El etiquetado se implementa mediante Aspectos y el AWS CDK. Los aspectos son una forma de aplicar una operación (como el etiquetado) a todos los constructos de un ámbito determinado.

El siguiente ejemplo aplica la etiqueta clave con el valor valor a un constructo.

TypeScript
Tags.of(myConstruct).add('key', 'value');
JavaScript
Tags.of(myConstruct).add('key', 'value');
Python
Tags.of(my_construct).add("key", "value")
Java
Tags.of(myConstruct).add("key", "value");
C#
Tags.Of(myConstruct).Add("key", "value");
Go
awscdk.Tags_Of(myConstruct).Add(jsii.String("key"), jsii.String("value"), &awscdk.TagProps{})

En el siguiente ejemplo, se elimina la etiqueta clave de un constructo.

TypeScript
Tags.of(myConstruct).remove('key');
JavaScript
Tags.of(myConstruct).remove('key');
Python
Tags.of(my_construct).remove("key")
Java
Tags.of(myConstruct).remove("key");
C#
Tags.Of(myConstruct).Remove("key");
Go
awscdk.Tags_Of(myConstruct).Remove(jsii.String("key"), &awscdk.TagProps{})

Si utiliza constructos Stage fijos, aplique la etiqueta en el nivel Stage o debajo. Las etiquetas no se aplican a través de los límites Stage.

Prioridades de etiqueta

AWS CDK aplica y elimina las etiquetas de forma recursiva. Si hay conflictos, prevalece la operación de etiquetado con la prioridad más alta. (Las prioridades se establecen mediante la propiedad opcional priority). Si las prioridades de dos operaciones son las mismas, prevalece la operación de etiquetado que se encuentre más cerca de la parte inferior del árbol del constructo. De forma predeterminada, aplicar una etiqueta tiene una prioridad de 100 (excepto en el caso de las etiquetas que se agregan directamente a un recurso AWS CloudFormation, que tienen una prioridad de 50). La prioridad predeterminada para eliminar una etiqueta es de 200.

A continuación, se aplica una etiqueta con una prioridad de 300 a un constructo.

TypeScript
Tags.of(myConstruct).add('key', 'value', {
  priority: 300
});
JavaScript
Tags.of(myConstruct).add('key', 'value', {
  priority: 300
});
Python
Tags.of(my_construct).add("key", "value", priority=300)
Java
Tags.of(myConstruct).add("key", "value", TagProps.builder()
        .priority(300).build());
C#
Tags.Of(myConstruct).Add("key", "value", new TagProps { Priority = 300 });
Go
awscdk.Tags_Of(myConstruct).Add(jsii.String("key"), jsii.String("value"), &awscdk.TagProps{
  Priority: jsii.Number(300),
})

Propiedades opcionales

Las etiquetas admiten las properties que permiten afinar cómo se aplican las etiquetas a los recursos o se eliminan de ellos. Todas las propiedades son opcionales.

applyToLaunchedInstances (Python: apply_to_launched_instances)

Disponible solo para add(). De forma predeterminada, las etiquetas se aplican a las instancias lanzadas en un grupo de escalado automático. Establezca esta propiedad como falsa para ignorar las instancias lanzadas en un grupo de escalado automático.

includeResourceTypes/excludeResourceTypes (Python: include_resource_types/exclude_resource_types)

Úselas para manipular las etiquetas solo en un subconjunto de recursos, en función de los tipos de recursos de AWS CloudFormation. De forma predeterminada, la operación se aplica a todos los recursos del subárbol de constructos, pero esto se puede cambiar si se incluyen o excluyen determinados tipos de recursos. La exclusión tiene prioridad sobre la inclusión, si se especifican ambas opciones.

priority

Utilice esta opción para establecer la prioridad de esta operación con respecto a otras Tags.add() y operaciones Tags.remove(). Los valores más altos tienen prioridad sobre los valores más bajos. El valor predeterminado es 100 para las operaciones de adición (50 para las etiquetas aplicadas directamente a los recursos AWS CloudFormation) y 200 para las operaciones de eliminación.

En el siguiente ejemplo, se aplica la etiqueta tagname con el valor valor y la prioridad 100 a los recursos del tipo AWS::Xxx::Yyy del constructo. No aplica la etiqueta a las instancias lanzadas en un grupo de Amazon EC2 Auto Scaling ni a recursos del tipo AWS::Xxx::Zzz. (Estos son marcadores de posición para dos tipos de recursos AWS CloudFormation arbitrarios, pero diferentes).

TypeScript
Tags.of(myConstruct).add('tagname', 'value', {
  applyToLaunchedInstances: false,
  includeResourceTypes: ['AWS::Xxx::Yyy'],
  excludeResourceTypes: ['AWS::Xxx::Zzz'],
  priority: 100,
});
JavaScript
Tags.of(myConstruct).add('tagname', 'value', {
  applyToLaunchedInstances: false,
  includeResourceTypes: ['AWS::Xxx::Yyy'],
  excludeResourceTypes: ['AWS::Xxx::Zzz'],
  priority: 100
});
Python
Tags.of(my_construct).add("tagname", "value",
    apply_to_launched_instances=False,
    include_resource_types=["AWS::Xxx::Yyy"],
    exclude_resource_types=["AWS::Xxx::Zzz"],
    priority=100)
Java
Tags.of(myConstruct).add("tagname", "value", TagProps.builder()
                .applyToLaunchedInstances(false)
                .includeResourceTypes(Arrays.asList("AWS::Xxx::Yyy"))
                .excludeResourceTypes(Arrays.asList("AWS::Xxx::Zzz"))
                .priority(100).build());
C#
Tags.Of(myConstruct).Add("tagname", "value", new TagProps
{
    ApplyToLaunchedInstances = false,
    IncludeResourceTypes = ["AWS::Xxx::Yyy"],
    ExcludeResourceTypes = ["AWS::Xxx::Zzz"],
    Priority = 100
});
Go
awscdk.Tags_Of(myConstruct).Add(jsii.String("tagname"), jsii.String("value"), &awscdk.TagProps{
  ApplyToLaunchedInstances: jsii.Bool(false),
  IncludeResourceTypes:     &[]*string{jsii.String("AWS::Xxx:Yyy")},
  ExcludeResourceTypes:     &[]*string{jsii.String("AWS::Xxx:Zzz")},
  Priority:                 jsii.Number(100),
})

En el siguiente ejemplo, se elimina la etiqueta tagname con prioridad 200 de los recursos de tipo AWS::Xxx::Yyy del constructo, pero no de los recursos de tipo AWS::Xxx::Zzz.

TypeScript
Tags.of(myConstruct).remove('tagname', {
  includeResourceTypes: ['AWS::Xxx::Yyy'],
  excludeResourceTypes: ['AWS::Xxx::Zzz'],
  priority: 200,
});
JavaScript
Tags.of(myConstruct).remove('tagname', {
  includeResourceTypes: ['AWS::Xxx::Yyy'],
  excludeResourceTypes: ['AWS::Xxx::Zzz'],
  priority: 200
});
Python
Tags.of(my_construct).remove("tagname",
    include_resource_types=["AWS::Xxx::Yyy"],
    exclude_resource_types=["AWS::Xxx::Zzz"],
    priority=200,)
Java
Tags.of((myConstruct).remove("tagname", TagProps.builder()
        .includeResourceTypes(Arrays.asList("AWS::Xxx::Yyy"))
        .excludeResourceTypes(Arrays.asList("AWS::Xxx::Zzz"))
        .priority(100).build());
C#
Tags.Of(myConstruct).Remove("tagname", new TagProps
{
    IncludeResourceTypes = ["AWS::Xxx::Yyy"],
    ExcludeResourceTypes = ["AWS::Xxx::Zzz"],
    Priority = 100
});
Go
awscdk.Tags_Of(myConstruct).Remove(jsii.String("tagname"), &awscdk.TagProps{
  IncludeResourceTypes: &[]*string{jsii.String("AWS::Xxx:Yyy")},
  ExcludeResourceTypes: &[]*string{jsii.String("AWS::Xxx:Zzz")},
  Priority:             jsii.Number(200),
})

Ejemplo

En el siguiente ejemplo, se agrega la clave de etiqueta StackType con el valor TheBest a cualquier recurso creado dentro del Stack denominado MarketingSystem. A continuación, lo vuelve a eliminar de todos los recursos, excepto de las subredes de VPC de Amazon EC2. El resultado es que la etiqueta solo se aplica a las subredes.

TypeScript
import { App, Stack, Tags } from 'aws-cdk-lib';

const app = new App();
const theBestStack = new Stack(app, 'MarketingSystem');

// Add a tag to all constructs in the stack
Tags.of(theBestStack).add('StackType', 'TheBest');

// Remove the tag from all resources except subnet resources
Tags.of(theBestStack).remove('StackType', {
  excludeResourceTypes: ['AWS::EC2::Subnet']
});
JavaScript
const { App, Stack, Tags } = require('aws-cdk-lib');

const app = new App();
const theBestStack = new Stack(app, 'MarketingSystem');

// Add a tag to all constructs in the stack
Tags.of(theBestStack).add('StackType', 'TheBest');

// Remove the tag from all resources except subnet resources
Tags.of(theBestStack).remove('StackType', {
  excludeResourceTypes: ['AWS::EC2::Subnet']
});
Python
from aws_cdk import App, Stack, Tags

app = App();
the_best_stack = Stack(app, 'MarketingSystem')

# Add a tag to all constructs in the stack
Tags.of(the_best_stack).add("StackType", "TheBest")

# Remove the tag from all resources except subnet resources
Tags.of(the_best_stack).remove("StackType",
    exclude_resource_types=["AWS::EC2::Subnet"])
Java
import software.amazon.awscdk.App;
import software.amazon.awscdk.Tags;

// Add a tag to all constructs in the stack
Tags.of(theBestStack).add("StackType", "TheBest");

// Remove the tag from all resources except subnet resources
Tags.of(theBestStack).remove("StackType", TagProps.builder()
        .excludeResourceTypes(Arrays.asList("AWS::EC2::Subnet"))
        .build());
C#
using Amazon.CDK;

var app = new App();
var theBestStack = new Stack(app, 'MarketingSystem');

// Add a tag to all constructs in the stack
Tags.Of(theBestStack).Add("StackType", "TheBest");

// Remove the tag from all resources except subnet resources
Tags.Of(theBestStack).Remove("StackType", new TagProps
{
    ExcludeResourceTypes = ["AWS::EC2::Subnet"]
});
Go
import "github.com/aws/aws-cdk-go/awscdk/v2"
app := awscdk.NewApp(nil)
theBestStack := awscdk.NewStack(app, jsii.String("MarketingSystem"), &awscdk.StackProps{})

// Add a tag to all constructs in the stack
awscdk.Tags_Of(theBestStack).Add(jsii.String("StackType"), jsii.String("TheBest"), &awscdk.TagProps{})

// Remove the tag from all resources except subnet resources
awscdk.Tags_Of(theBestStack).Add(jsii.String("StackType"), jsii.String("TheBest"), &awscdk.TagProps{
  ExcludeResourceTypes: &[]*string{jsii.String("AWS::EC2::Subnet")},
})

Con el siguiente código se obtiene el mismo resultado. Considere qué enfoque (inclusión o exclusión) deja más en claro su intención.

TypeScript
Tags.of(theBestStack).add('StackType', 'TheBest',
  { includeResourceTypes: ['AWS::EC2::Subnet']});
JavaScript
Tags.of(theBestStack).add('StackType', 'TheBest',
  { includeResourceTypes: ['AWS::EC2::Subnet']});
Python
Tags.of(the_best_stack).add("StackType", "TheBest",
    include_resource_types=["AWS::EC2::Subnet"])
Java
Tags.of(theBestStack).add("StackType", "TheBest", TagProps.builder()
        .includeResourceTypes(Arrays.asList("AWS::EC2::Subnet"))
        .build());
C#
Tags.Of(theBestStack).Add("StackType", "TheBest", new TagProps {
    IncludeResourceTypes = ["AWS::EC2::Subnet"]
});
Go
awscdk.Tags_Of(theBestStack).Add(jsii.String("StackType"), jsii.String("TheBest"), &awscdk.TagProps{
  IncludeResourceTypes: &[]*string{jsii.String("AWS::EC2::Subnet")},
})

Etiquetado de constructos individuales

Tags.of(scope).add(key, value) es la forma estándar de agregar etiquetas a los componentes fijos del AWS CDK. Su comportamiento de tree-walking, que etiqueta de forma recursiva todos los recursos etiquetables dentro de un ámbito determinado, que casi siempre es lo que se busca. Sin embargo, a veces es necesario etiquetar un constructo (o constructos) arbitrarios específicos.

Uno de estos casos implica la aplicación de etiquetas cuyo valor se deriva de alguna propiedad del constructo que se etiqueta. El enfoque de etiquetado estándar aplica de forma recursiva la misma clave y valor a todos los recursos coincidentes del ámbito. Sin embargo, en este caso el valor podría ser diferente para cada constructo etiquetado.

Las etiquetas se implementan mediante aspectos, y el CDK llama al método visit() de la etiqueta para cada constructo dentro del ámbito especificado mediante Tags.of(scope). Podemos llamar a Tag.visit() directamente para aplicar una etiqueta a un solo constructo.

TypeScript
new cdk.Tag(key, value).visit(scope);
JavaScript
new cdk.Tag(key, value).visit(scope);
Python
cdk.Tag(key, value).visit(scope)
Java
Tag.Builder.create(key, value).build().visit(scope);
C#
new Tag(key, value).Visit(scope);
Go
awscdk.NewTag(key, value, &awscdk.TagProps{}).Visit(scope)

Puede etiquetar todos los constructos fijos incluidos en un ámbito, pero dejar que los valores de las etiquetas se deriven de las propiedades de cada constructo. Para ello, escriba un aspecto y aplique la etiqueta en el método del aspecto visit(), tal y como se muestra en el ejemplo anterior. A continuación, agregue el aspecto al ámbito deseado mediante Aspects.of(scope).add(aspect).

En el siguiente ejemplo se aplica una etiqueta a cada recurso de una pila que contiene la ruta del recurso.

TypeScript
class PathTagger implements cdk.IAspect {
  visit(node: IConstruct) {
    new cdk.Tag("aws-cdk-path", node.node.path).visit(node);
  }
}
 
stack = new MyStack(app);
cdk.Aspects.of(stack).add(new PathTagger())
JavaScript
class PathTagger {
  visit(node) {
    new cdk.Tag("aws-cdk-path", node.node.path).visit(node);
  }
}

stack = new MyStack(app);
cdk.Aspects.of(stack).add(new PathTagger())
Python
@jsii.implements(cdk.IAspect)
class PathTagger:
    def visit(self, node: IConstruct):
        cdk.Tag("aws-cdk-path", node.node.path).visit(node)

stack = MyStack(app) 
cdk.Aspects.of(stack).add(PathTagger())
Java
final class PathTagger implements IAspect {
	public void visit(IConstruct node) {
		Tag.Builder.create("aws-cdk-path", node.getNode().getPath()).build().visit(node);
	}
}

stack stack = new MyStack(app);
Aspects.of(stack).add(new PathTagger());
C#
public class PathTagger : IAspect
{
    public void Visit(IConstruct node)
    {
        new Tag("aws-cdk-path", node.Node.Path).Visit(node);
    }
}

var stack = new MyStack(app);
Aspects.Of(stack).Add(new PathTagger);
sugerencia

La lógica del etiquetado condicional, que incluye las prioridades, los tipos de recursos, etc., está integrada en la clase de la Tag. Puede utilizar estas características cuando aplica etiquetas a recursos arbitrarios; la etiqueta no se aplica si no se cumplen las condiciones. Además, la clase de Tag solo etiqueta los recursos etiquetables, por lo que no es necesario comprobar si un constructo es etiquetable antes de aplicar una etiqueta.