Personalización de componentes fijos de la AWS biblioteca de componentes - AWS Cloud Development Kit (AWS CDK) v2
Uso de trampillas de escapeEscotillas de escapeAnulaciones sin procesarRecursos personalizados

Esta es la guía para AWS CDK desarrolladores de la versión 2. La versión anterior del CDK v1 entró en mantenimiento el 1 de junio de 2022 y dejó de ofrecer soporte el 1 de junio de 2023.

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Personalización de componentes fijos de la AWS biblioteca de componentes

Personalice las construcciones de la biblioteca de AWS construcciones mediante trampillas de escape, anulaciones sin procesar y recursos personalizados.

Uso de trampillas de escape

La biblioteca AWS Construct proporciona construcciones con distintos niveles de abstracción.

En el nivel más alto, la AWS CDK aplicación y las pilas que contiene son en sí mismas abstracciones de toda la infraestructura de nube o de partes importantes de la misma. Se pueden parametrizar para implementarlos en diferentes entornos o para diferentes necesidades.

Las abstracciones son herramientas poderosas para diseñar e implementar aplicaciones en la nube. AWS CDK Esto le da el poder no solo de construir con sus abstracciones, sino también de crear nuevas abstracciones. Utilizando como guía los constructos L2 y L3 de código abierto existentes, puede crear sus propios constructos L2 y L3 para reflejar las mejores prácticas y opiniones de su propia organización.

Ninguna abstracción es perfecta, e incluso las buenas abstracciones no pueden cubrir todos los casos de uso posibles. Durante el desarrollo, es posible que encuentres una construcción que casi se adapte a tus necesidades y que requiera una personalización pequeña o grande.

Por esta razón, AWS CDK proporciona formas de romper con el modelo de construcción. Esto incluye pasar a una abstracción de nivel inferior o a un modelo completamente diferente. Las trampillas de escape te permiten escapar del AWS CDK paradigma y personalizarlo de forma que se adapte a tus necesidades. Luego, puedes agrupar los cambios en una nueva estructura para eliminar la complejidad subyacente y proporcionar una API limpia para otros desarrolladores.

A continuación, se muestran ejemplos de situaciones en las que puede utilizar trampillas de escape:

  • Hay una función de AWS servicio disponible a través de AWS CloudFormation ella, pero no tiene ninguna estructura de nivel 2.

  • Una función AWS de servicio está disponible a través del servicio AWS CloudFormation, y existen estructuras de nivel 2 para el servicio, pero estas aún no exponen la función. Como las construcciones de nivel 2 son seleccionadas por el equipo de CDK, es posible que no estén disponibles de forma inmediata para las nuevas funciones.

  • La función aún no está disponible en absoluto. AWS CloudFormation

    Para determinar si una función está disponible a través de ella AWS CloudFormation, consulte la Referencia de tipos de AWS recursos y propiedades.

Desarrolle trampillas de escape para las construcciones L1

Si las construcciones L2 no están disponibles para el servicio, puede usar las construcciones L1 generadas automáticamente. Estos recursos se pueden reconocer por su nombre que comience por, por ejemploCfn, o. CfnBucket CfnRole Los instancias exactamente como usarías el recurso equivalente AWS CloudFormation .

Por ejemplo, para crear una instancia de un bucket L1 de Amazon S3 de bajo nivel con la analítica habilitada, escribiría algo como lo siguiente.

TypeScript
new s3.CfnBucket(this, 'MyBucket', {
  analyticsConfigurations: [
    { 
      id: 'Config',
      // ...        
    } 
  ]
});
JavaScript
new s3.CfnBucket(this, 'MyBucket', {
  analyticsConfigurations: [
    { 
      id: 'Config'
      // ...        
    } 
  ]
});
Python
s3.CfnBucket(self, "MyBucket",
    analytics_configurations: [
        dict(id="Config",
             # ...
             )
    ]
)
Java
CfnBucket.Builder.create(this, "MyBucket")
    .analyticsConfigurations(Arrays.asList(java.util.Map.of(    // Java 9 or later
        "id", "Config", // ...
    ))).build();
C#
new CfnBucket(this, 'MyBucket', new CfnBucketProps {
    AnalyticsConfigurations = new Dictionary<string, string>
    {
        ["id"] = "Config",
        // ...
    }
});

En raras ocasiones, puede que desee definir un recurso que no tenga una clase correspondiente. CfnXxx Podría tratarse de un tipo de recurso nuevo que aún no se haya publicado en la especificación del AWS CloudFormation recurso. En estos casos, puede crear una instancia cdk.CfnResource directamente y especificar el tipo y las propiedades del recurso. Esto se muestra en el siguiente ejemplo.

TypeScript
new cdk.CfnResource(this, 'MyBucket', {
  type: 'AWS::S3::Bucket',
  properties: {
    // Note the PascalCase here! These are CloudFormation identifiers.
    AnalyticsConfigurations: [
      {
        Id: 'Config',
        // ...
      }
    ] 
  }
});
JavaScript
new cdk.CfnResource(this, 'MyBucket', {
  type: 'AWS::S3::Bucket',
  properties: {
    // Note the PascalCase here! These are CloudFormation identifiers.
    AnalyticsConfigurations: [
      {
        Id: 'Config'
        // ...
      }
    ] 
  }
});
Python
cdk.CfnResource(self, 'MyBucket',
  type="AWS::S3::Bucket",
  properties=dict(
    # Note the PascalCase here! These are CloudFormation identifiers.
    "AnalyticsConfigurations": [
      {
        "Id": "Config",
        # ...
      }
    ] 
  }
)
Java
CfnResource.Builder.create(this, "MyBucket")
        .type("AWS::S3::Bucket")
        .properties(java.util.Map.of(    // Map.of requires Java 9 or later
            // Note the PascalCase here! These are CloudFormation identifiers
            "AnalyticsConfigurations", Arrays.asList(
                    java.util.Map.of("Id", "Config", // ...
                    ))))
        .build();
C#
new CfnResource(this, "MyBucket", new CfnResourceProps
{
    Type = "AWS::S3::Bucket",
    Properties = new Dictionary<string, object>
    {   // Note the PascalCase here! These are CloudFormation identifiers
        ["AnalyticsConfigurations"] = new Dictionary<string, string>[]
        {
            new Dictionary<string, string> {
                ["Id"] = "Config"
            }
        }
    }
});

Desarrolle trampillas de escape para construcciones L2

Si a una construcción L2 le falta una característica o si está intentando solucionar un problema, puede modificar la construcción L1 encapsulada por la construcción L2.

Todas las construcciones L2 contienen en su interior la construcción L1 correspondiente. Por ejemplo, la construcción de alto nivel envuelve la Bucket construcción de nivel inferior. CfnBucket Como CfnBucket corresponde directamente al AWS CloudFormation recurso, expone todas las funciones que están disponibles a través de él. AWS CloudFormation

El enfoque básico para acceder a la construcción L1 es usar construct.node.defaultChild (Python:default_child), convertirla en el tipo correcto (si es necesario) y modificar sus propiedades. De nuevo, tomemos el ejemplo de unBucket.

TypeScript
// Get the CloudFormation resource
const cfnBucket = bucket.node.defaultChild as s3.CfnBucket;

// Change its properties
cfnBucket.analyticsConfiguration = [
  { 
    id: 'Config',
    // ...        
  } 
];
JavaScript
// Get the CloudFormation resource
const cfnBucket = bucket.node.defaultChild;

// Change its properties
cfnBucket.analyticsConfiguration = [
  { 
    id: 'Config'
    // ...        
  } 
];
Python
# Get the CloudFormation resource
cfn_bucket = bucket.node.default_child

# Change its properties
cfn_bucket.analytics_configuration = [
    {
        "id": "Config",
        # ...
    }
]
Java
// Get the CloudFormation resource
CfnBucket cfnBucket = (CfnBucket)bucket.getNode().getDefaultChild();

cfnBucket.setAnalyticsConfigurations(
        Arrays.asList(java.util.Map.of(    // Java 9 or later
            "Id", "Config", // ...
        ));
C#
// Get the CloudFormation resource
var cfnBucket = (CfnBucket)bucket.Node.DefaultChild;

cfnBucket.AnalyticsConfigurations = new List<object> {
    new Dictionary<string, string>
    {
        ["Id"] = "Config",
        // ...
    }
};

También puedes usar este objeto para cambiar AWS CloudFormation opciones como Metadata yUpdatePolicy.

TypeScript
cfnBucket.cfnOptions.metadata = {
  MetadataKey: 'MetadataValue'
};
JavaScript
cfnBucket.cfnOptions.metadata = {
  MetadataKey: 'MetadataValue'
};
Python
cfn_bucket.cfn_options.metadata = {
    "MetadataKey": "MetadataValue"
}
Java
cfnBucket.getCfnOptions().setMetadata(java.util.Map.of(    // Java 9+
    "MetadataKey", "Metadatavalue"));
C#
cfnBucket.CfnOptions.Metadata = new Dictionary<string, object>
{
    ["MetadataKey"] = "Metadatavalue"
};

Escotillas de escape

AWS CDK También proporciona la capacidad de subir un nivel de abstracción, al que podríamos denominar trampilla de «escape». Si tiene una construcción L1, por ejemploCfnBucket, puede crear una nueva construcción L2 (Bucketen este caso) para incluir la construcción L1.

Esto resulta práctico cuando se crea un recurso de L1 pero se quiere utilizar con una construcción que requiere un recurso de L2. También resulta útil cuando se quieren utilizar métodos prácticos como los .grantXxxxx() que no están disponibles en la construcción L1.

Se pasa al nivel de abstracción superior mediante un método estático en la clase L2 denominado, .fromCfnXxxxx() por ejemplo, para los buckets de Amazon Bucket.fromCfnBucket() S3. El recurso L1 es el único parámetro.

TypeScript
b1 = new s3.CfnBucket(this, "buck09", { ... });
b2 = s3.Bucket.fromCfnBucket(b1);
JavaScript
b1 = new s3.CfnBucket(this, "buck09", { ...} );
b2 = s3.Bucket.fromCfnBucket(b1);
Python
b1 = s3.CfnBucket(self, "buck09", ...)
 b2 = s3.from_cfn_bucket(b1)
Java
CfnBucket b1 = CfnBucket.Builder.create(this, "buck09")
								// ....
		                        .build();
IBucket b2 = Bucket.fromCfnBucket(b1);
C#
var b1 = new CfnBucket(this, "buck09", new CfnBucketProps { ... });
var v2 = Bucket.FromCfnBucket(b1);

Las construcciones de L2 creadas a partir de las construcciones de L1 son objetos proxy que hacen referencia al recurso de L1, similares a los que se crean a partir de nombres de recursos, ARN o búsquedas. Las modificaciones de estas construcciones no afectan a la AWS CloudFormation plantilla sintetizada final (sin embargo, dado que tiene el recurso L1, puede modificarlo en su lugar). Para obtener más información sobre los objetos proxy, consulte. Hacer referencia a los recursos de tu cuenta AWS

Para evitar confusiones, no cree varias construcciones de L2 que hagan referencia a la misma construcción de L1. Por ejemplo, si extraes el CfnBucket de un Bucket mediante la técnica de la sección anterior, no deberías crear una segunda Bucket instancia llamando Bucket.fromCfnBucket() con eso. CfnBucket De hecho, funciona como cabría esperar (solo AWS::S3::Bucket se sintetiza una), pero dificulta el mantenimiento del código.

Anulaciones sin procesar

Si faltan propiedades en la construcción L1, puede omitir todo tipo de escritura mediante anulaciones sin procesar. Esto también permite eliminar las propiedades sintetizadas.

Utilice uno de los addOverride métodos (Python:add_override), como se muestra en el siguiente ejemplo.

TypeScript
// Get the CloudFormation resource
const cfnBucket = bucket.node.defaultChild as s3.CfnBucket;

// Use dot notation to address inside the resource template fragment
cfnBucket.addOverride('Properties.VersioningConfiguration.Status', 'NewStatus');
cfnBucket.addDeletionOverride('Properties.VersioningConfiguration.Status');

// use index (0 here) to address an element of a list
cfnBucket.addOverride('Properties.Tags.0.Value', 'NewValue');
cfnBucket.addDeletionOverride('Properties.Tags.0');

// addPropertyOverride is a convenience function for paths starting with "Properties."
cfnBucket.addPropertyOverride('VersioningConfiguration.Status', 'NewStatus');
cfnBucket.addPropertyDeletionOverride('VersioningConfiguration.Status');
cfnBucket.addPropertyOverride('Tags.0.Value', 'NewValue');
cfnBucket.addPropertyDeletionOverride('Tags.0');
JavaScript
// Get the CloudFormation resource
const cfnBucket = bucket.node.defaultChild ;

// Use dot notation to address inside the resource template fragment
cfnBucket.addOverride('Properties.VersioningConfiguration.Status', 'NewStatus');
cfnBucket.addDeletionOverride('Properties.VersioningConfiguration.Status');

// use index (0 here) to address an element of a list
cfnBucket.addOverride('Properties.Tags.0.Value', 'NewValue');
cfnBucket.addDeletionOverride('Properties.Tags.0');

// addPropertyOverride is a convenience function for paths starting with "Properties."
cfnBucket.addPropertyOverride('VersioningConfiguration.Status', 'NewStatus');
cfnBucket.addPropertyDeletionOverride('VersioningConfiguration.Status');
cfnBucket.addPropertyOverride('Tags.0.Value', 'NewValue');
cfnBucket.addPropertyDeletionOverride('Tags.0');
Python
# Get the CloudFormation resource
cfn_bucket = bucket.node.default_child

# Use dot notation to address inside the resource template fragment
cfn_bucket.add_override("Properties.VersioningConfiguration.Status", "NewStatus")
cfn_bucket.add_deletion_override("Properties.VersioningConfiguration.Status")

# use index (0 here) to address an element of a list
cfn_bucket.add_override("Properties.Tags.0.Value", "NewValue")
cfn_bucket.add_deletion_override("Properties.Tags.0")

# addPropertyOverride is a convenience function for paths starting with "Properties."
cfn_bucket.add_property_override("VersioningConfiguration.Status", "NewStatus")
cfn_bucket.add_property_deletion_override("VersioningConfiguration.Status")
cfn_bucket.add_property_override("Tags.0.Value", "NewValue")
cfn_bucket.add_property_deletion_override("Tags.0")
Java
// Get the CloudFormation resource
CfnBucket cfnBucket = (CfnBucket)bucket.getNode().getDefaultChild();

// Use dot notation to address inside the resource template fragment
cfnBucket.addOverride("Properties.VersioningConfiguration.Status", "NewStatus");
cfnBucket.addDeletionOverride("Properties.VersioningConfiguration.Status");

// use index (0 here) to address an element of a list
cfnBucket.addOverride("Properties.Tags.0.Value", "NewValue");
cfnBucket.addDeletionOverride("Properties.Tags.0");

// addPropertyOverride is a convenience function for paths starting with "Properties."
cfnBucket.addPropertyOverride("VersioningConfiguration.Status", "NewStatus");
cfnBucket.addPropertyDeletionOverride("VersioningConfiguration.Status");
cfnBucket.addPropertyOverride("Tags.0.Value", "NewValue");
cfnBucket.addPropertyDeletionOverride("Tags.0");
C#
// Get the CloudFormation resource
var cfnBucket = (CfnBucket)bucket.node.defaultChild;

// Use dot notation to address inside the resource template fragment
cfnBucket.AddOverride("Properties.VersioningConfiguration.Status", "NewStatus");
cfnBucket.AddDeletionOverride("Properties.VersioningConfiguration.Status");

// use index (0 here) to address an element of a list
cfnBucket.AddOverride("Properties.Tags.0.Value", "NewValue");
cfnBucket.AddDeletionOverride("Properties.Tags.0");

// addPropertyOverride is a convenience function for paths starting with "Properties."
cfnBucket.AddPropertyOverride("VersioningConfiguration.Status", "NewStatus");
cfnBucket.AddPropertyDeletionOverride("VersioningConfiguration.Status");
cfnBucket.AddPropertyOverride("Tags.0.Value", "NewValue");
cfnBucket.AddPropertyDeletionOverride("Tags.0");

Recursos personalizados

Si la función no está disponible mediante una llamada directa a la API AWS CloudFormation, sino solo a través de ella, debes escribir un recurso AWS CloudFormation personalizado para realizar la llamada a la API que necesitas. Puedes usarlo AWS CDK para escribir recursos personalizados y agruparlos en una interfaz de construcción normal. Desde la perspectiva de un consumidor de tu estilo, la experiencia parecerá nativa.

La creación de un recurso personalizado implica escribir una función Lambda que responda a los eventos del recurso y del CREATE DELETE ciclo de vida. UPDATE Si su recurso personalizado solo necesita realizar una única llamada a la API, considere la posibilidad de utilizar la AwsCustomResource. Esto permite realizar llamadas arbitrarias al SDK durante una AWS CloudFormation implementación. De lo contrario, debe escribir su propia función Lambda para realizar el trabajo que necesita realizar.

El tema es demasiado amplio para tratarlo por completo aquí, pero los siguientes enlaces deberían ayudarte a empezar: