Personalizzazione dei costrutti dalla Construct Library AWS - AWS Cloud Development Kit (AWS CDK) v2
Usare le botole di fugaPortelli Un-escapeRaw sovrascriveRisorse personalizzate

Questa è la guida per sviluppatori AWS CDK v2. Il vecchio CDK v1 è entrato in manutenzione il 1° giugno 2022 e ha terminato il supporto il 1° giugno 2023.

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Personalizzazione dei costrutti dalla Construct Library AWS

Personalizza i costrutti della AWS Construct Library tramite escape hatch, sostituzioni raw e risorse personalizzate.

Usare le botole di fuga

La AWS Construct Library fornisce costrutti con diversi livelli di astrazione.

Al livello più alto, l' AWS CDK applicazione e gli stack in essa contenuti sono essi stessi astrazioni dell'intera infrastruttura cloud o parti significative di essa. Possono essere parametrizzati per distribuirli in ambienti diversi o per esigenze diverse.

Le astrazioni sono strumenti potenti per la progettazione e l'implementazione di applicazioni cloud. Ti AWS CDK dà il potere non solo di costruire con le sue astrazioni, ma anche di creare nuove astrazioni. Utilizzando i costrutti open source L2 e L3 esistenti come guida, è possibile creare costrutti L2 e L3 personalizzati che riflettano le migliori pratiche e le opinioni della propria organizzazione.

Nessuna astrazione è perfetta e anche le buone astrazioni non possono coprire tutti i possibili casi d'uso. Durante lo sviluppo, potresti trovare un costrutto che si adatta quasi alle tue esigenze, che richieda una personalizzazione piccola o grande.

Per questo motivo, AWS CDK fornisce modi per uscire dal modello di costruzione. Ciò include il passaggio a un'astrazione di livello inferiore o a un modello completamente diverso. Gli escape hatches ti consentono di sfuggire al AWS CDK paradigma e di personalizzarlo in base alle tue esigenze. Quindi, puoi racchiudere le modifiche in un nuovo costrutto per astrarre la complessità sottostante e fornire un'API pulita per altri sviluppatori.

Di seguito sono riportati alcuni esempi di situazioni in cui è possibile utilizzare le botole di fuga:

  • Una funzionalità AWS di servizio è disponibile tramite AWS CloudFormation, ma non esistono costrutti L2 corrispondenti.

  • Una funzionalità AWS di servizio è disponibile tramite AWS CloudFormation e sono presenti costrutti L2 per il servizio, ma questi non espongono ancora la funzionalità. Poiché i costrutti L2 sono curati dal team CDK, potrebbero non essere immediatamente disponibili per le nuove funzionalità.

  • La funzionalità non è ancora disponibile affatto. AWS CloudFormation

    Per determinare se una funzionalità è disponibile tramite AWS CloudFormation, consulta AWS Resource and Property Types Reference.

Sviluppa portelli di fuga per i costrutti L1

Se i costrutti L2 non sono disponibili per il servizio, è possibile utilizzare i costrutti L1 generati automaticamente. Queste risorse possono essere riconosciute dal nome che inizia conCfn, ad esempio o. CfnBucket CfnRole Le istanziate esattamente come usereste la risorsa equivalente AWS CloudFormation .

Ad esempio, per creare un'istanza di un bucket Amazon S3 di basso livello L1 con analisi abilitata, dovresti scrivere qualcosa come segue.

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",
        // ...
    }
});

Potrebbero esserci rari casi in cui desideri definire una risorsa che non ha una classe corrispondente. CfnXxx Potrebbe trattarsi di un nuovo tipo di risorsa che non è ancora stato pubblicato nelle specifiche delle AWS CloudFormation risorse. In casi come questo, è possibile creare cdk.CfnResource direttamente un'istanza e specificare il tipo e le proprietà della risorsa. Questo viene mostrato nell'esempio seguente.

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

Sviluppa portelli di fuga per costrutti L2

Se in un costrutto L2 manca una funzionalità o stai cercando di risolvere un problema, puoi modificare il costrutto L1 che è incapsulato dal costrutto L2.

Tutti i costrutti L2 contengono al loro interno il costrutto L1 corrispondente. Ad esempio, il costrutto di alto livello racchiude il Bucket costrutto di basso livello. CfnBucket Poiché CfnBucket corrisponde direttamente alla AWS CloudFormation risorsa, espone tutte le funzionalità disponibili tramite. AWS CloudFormation

L'approccio di base per accedere al costrutto L1 consiste nell'utilizzare (construct.node.defaultChildPython:default_child), convertirlo nel tipo corretto (se necessario) e modificarne le proprietà. Ancora una volta, prendiamo l'esempio di a. Bucket

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",
        // ...
    }
};

È inoltre possibile utilizzare questo oggetto per modificare AWS CloudFormation opzioni come Metadata eUpdatePolicy.

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

Portelli Un-escape

Fornisce AWS CDK anche la possibilità di salire a un livello di astrazione, che potremmo chiamare un portello «un-escape». Se si dispone di un costrutto L1, ad esempio, è possibile creare un nuovo costrutto L2 (Bucketin questo caso) per avvolgere il costrutto L1. CfnBucket

Ciò è utile quando si crea una risorsa L1 ma si desidera utilizzarla con un costrutto che richiede una risorsa L2. È utile anche quando si desidera utilizzare metodi di praticità come .grantXxxxx() quelli non disponibili nel costrutto L1.

Si passa al livello di astrazione superiore utilizzando un metodo statico sulla classe L2 chiamato, ad esempio, .fromCfnXxxxx() per i bucket Amazon Bucket.fromCfnBucket() S3. La risorsa L1 è l'unico parametro.

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

I costrutti L2 creati dai costrutti L1 sono oggetti proxy che fanno riferimento alla risorsa L1, simili a quelli creati dai nomi delle risorse, dagli ARN o dalle ricerche. Le modifiche a questi costrutti non influiscono sul AWS CloudFormation modello sintetizzato finale (poiché si dispone della risorsa L1, tuttavia, è possibile modificarla). Per ulteriori informazioni sugli oggetti proxy, vedere. Riferimento alle risorse presenti nel tuo account AWS

Per evitare confusione, non create più costrutti L2 che facciano riferimento allo stesso costrutto L1. Ad esempio, se estraete il CfnBucket da a Bucket usando la tecnica della sezione precedente, non dovreste creare una seconda Bucket istanza chiamando con quella. Bucket.fromCfnBucket() CfnBucket In realtà funziona come previsto (ne AWS::S3::Bucket viene sintetizzata solo una) ma rende il codice più difficile da mantenere.

Raw sovrascrive

Se mancano delle proprietà nel costrutto L1, potete ignorare tutte le digitazioni utilizzando le sostituzioni non elaborate. Ciò consente anche di eliminare le proprietà sintetizzate.

Utilizzate uno dei addOverride metodi (Python:add_override), come mostrato nell'esempio seguente.

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");

Risorse personalizzate

Se la funzionalità non è disponibile tramite AWS CloudFormation, ma solo tramite una chiamata API diretta, devi scrivere una risorsa AWS CloudFormation personalizzata per effettuare la chiamata API necessaria. Puoi utilizzarlo AWS CDK per scrivere risorse personalizzate e inserirle in una normale interfaccia di costruzione. Dal punto di vista di un consumatore del tuo prodotto, l'esperienza sembrerà nativa.

La creazione di una risorsa personalizzata implica la scrittura di una funzione Lambda che risponde agli eventi della risorsa e DELETE del CREATE ciclo di UPDATE vita. Se la tua risorsa personalizzata deve effettuare solo una singola chiamata API, prendi in considerazione l'utilizzo di. AwsCustomResource In questo modo è possibile eseguire chiamate SDK arbitrarie durante una AWS CloudFormation distribuzione. Altrimenti, dovresti scrivere la tua funzione Lambda per eseguire il lavoro che devi fare.

L'argomento è troppo ampio per essere trattato completamente in questa sede, ma i seguenti link dovrebbero aiutarti a iniziare: