Comment créer des plugins Comment charger des plugins avec la CLI CDK Implémentation de plugins pour fournisseurs d'identifiants En savoir plus

Configuration des plugins pour le kit d'outils CDK

Le kit d'outils AWS CDK prend en charge les plugins qui ajoutent de nouvelles fonctionnalités à vos flux de travail CDK. Les plugins sont principalement conçus pour être utilisés avec l'interface de ligne de commande CDK (CDK CLI), mais ils peuvent également être utilisés par programmation avec la bibliothèque du kit d'outils CDK. Ils fournissent un moyen standardisé d'étendre les fonctionnalités, par exemple en utilisant d'autres sources d'informations d'identification.

Note

Bien que le système de plugins fonctionne à la fois avec la CLI CDK et la bibliothèque CDK Toolkit, il est principalement destiné à être utilisé en CLI. Lorsque vous utilisez la bibliothèque CDK Toolkit par programmation, il existe souvent des moyens plus simples et plus directs d'accomplir les mêmes tâches sans plugins, en particulier pour la gestion des informations d'identification.

Actuellement, le kit d'outils CDK prend en charge une fonctionnalité de plugin :

Fournisseurs AWS d'informations d'identification personnalisés - Créez des méthodes alternatives pour obtenir des AWS informations d'identification au-delà des mécanismes intégrés.

Comment créer des plugins

Pour créer un plugin CDK Toolkit, vous devez d'abord créer un module Node.js, créé dans TypeScript ou JavaScript, qui peut être chargé par le CDK Toolkit. Ce module exporte un objet avec une structure spécifique que le CDK Toolkit peut reconnaître. Au minimum, l'objet exporté doit inclure un identifiant de version et une fonction d'initialisation qui reçoit une IPluginHost instance, que le plugin utilise pour enregistrer ses capacités.

TypeScript

JS commun


// Example plugin structure
import type { IPluginHost, Plugin } from '@aws-cdk/cli-plugin-contract';

const plugin: Plugin = {
    // Version of the plugin infrastructure (currently always '1')
    version: '1',

    // Initialization function called when the plugin is loaded
    init(host: IPluginHost): void {
        // Register your plugin functionality with the host
        // For example, register a custom credential provider
    }
};

export = plugin;

ESM


// Example plugin structure
import type { IPluginHost, Plugin } from '@aws-cdk/cli-plugin-contract';

const plugin: Plugin = {
    // Version of the plugin infrastructure (currently always '1')
    version: '1',

    // Initialization function called when the plugin is loaded
    init(host: IPluginHost): void {
        // Register your plugin functionality with the host
        // For example, register a custom credential provider
    }
};

export { plugin as 'module.exports' };

JavaScript

JS commun


const plugin = {
    // Version of the plugin infrastructure (currently always '1')
    version: '1',

    // Initialization function called when the plugin is loaded
    init(host) {
        // Register your plugin functionality with the host
        // For example, register a custom credential provider
    }
};

module.exports = plugin;

ESM


const plugin = {
    // Version of the plugin infrastructure (currently always '1')
    version: '1',

    // Initialization function called when the plugin is loaded
    init(host) {
        // Register your plugin functionality with the host
        // For example, register a custom credential provider
    }
};

export { plugin as 'module.exports' };

Note

Les plugins CDK Toolkit sont chargés en tant que modules CommonJS. Vous pouvez créer votre plugin en tant que ECMAScript module (ESM), mais vous devez respecter certaines contraintes :

Le module ne peut pas contenir le niveau supérieurawait, ni importer de modules contenant le niveau supérieurawait.
Le module doit garantir la compatibilité en exportant l'objet du plugin sous le nom module.exports d'export :export { plugin as 'module.exports' }.

Comment charger des plugins avec la CLI CDK

Deux options s'offrent à vous pour spécifier les plug-ins :

Option 1 : utiliser l'option de ligne de --plugin commande


# Load a single plugin
$ cdk list --plugin=my-custom-plugin

# Load multiple plugins
$ cdk deploy --plugin=custom-plugin-1 --plugin=custom-plugin-2

La valeur de l'--pluginargument doit être un JavaScript fichier qui, lorsqu'il est importé via la require() fonction Node.js, renvoie un objet implémentant l'Plugininterface.

Option 2 : ajouter des entrées aux fichiers de configuration

Vous pouvez ajouter les spécifications du plugin au cdk.json fichier spécifique au projet ou au fichier de configuration ~/.cdk.json globale :


{
  "plugin": [
    "custom-plugin-1",
    "custom-plugin-2"
  ]
}

Quelle que soit l'approche, la CLI CDK chargera les plugins spécifiés avant d'exécuter les commandes.

Chargez des plugins dans le code avec la bibliothèque CDK Toolkit

Lorsque vous utilisez la bibliothèque CDK Toolkit par programmation, vous pouvez charger des plugins directement dans votre code à l'aide de l'PluginHostinstance du package. @aws-cdk/toolkit-lib PluginHostFournit une load() méthode pour charger les plugins par nom ou chemin du module.

La load() méthode ne prend qu'un seul paramètremoduleSpec, qui est le nom ou le chemin du module du plugin à charger. Cela peut être soit :

Nom du module Node.js installé dans le node_modules répertoire.
Un chemin de fichier relatif ou absolu vers un TypeScript module JavaScript or.

Implémentation de plugins pour fournisseurs d'identifiants

Le principal cas d'utilisation actuel des plugins consiste à créer des fournisseurs AWS d'identifiants personnalisés. Comme la AWS CLI, la CLI CDK a besoin AWS d'informations d'identification pour l'authentification et l'autorisation. Cependant, il existe plusieurs scénarios dans lesquels la résolution standard des informations d'identification peut échouer :

L'ensemble initial d'informations d'identification ne peut pas être obtenu.
Le compte auquel appartiennent les informations d'identification initiales ne peut pas être obtenu.
Le compte associé aux informations d'identification est différent du compte sur lequel la CLI essaie de fonctionner.

Pour répondre à ces scénarios, le kit d'outils CDK prend en charge les plugins des fournisseurs d'informations d'identification. Ces plugins implémentent l'CredentialProviderSourceinterface à partir du @aws-cdk/cli-plugin-contract package et sont enregistrés dans le Toolkit à l'aide de la registerCredentialProviderSource méthode. Cela permet au kit d'outils CDK d'obtenir des AWS informations d'identification provenant de sources non standard telles que des systèmes d'authentification spécialisés ou des magasins d'informations d'identification personnalisés.

Pour implémenter un fournisseur d'informations d'identification personnalisé, créez une classe qui implémente l'interface requise :

TypeScript

JS commun


import type { CredentialProviderSource, ForReading, ForWriting, IPluginHost, Plugin, PluginProviderResult, SDKv3CompatibleCredentials } from '@aws-cdk/cli-plugin-contract';

class CustomCredentialProviderSource implements CredentialProviderSource {
  // Friendly name for the provider, used in error messages
  public readonly name: string = 'custom-credential-provider';

  // Check if this provider is available on the current system
  public async isAvailable(): Promise<boolean> {
    // Return false if the plugin cannot be used
    // For example, if it depends on files not present on the host
    return true;
  }

  // Check if this provider can provide credentials for a specific account
  public async canProvideCredentials(accountId: string): Promise<boolean> {
    // Return false if the plugin cannot provide credentials for this account
    // For example, if the account is not managed by this credential system
    return true;
    // You can use patterns to filter specific accounts
    // return accountId.startsWith('123456');
  }

  // Get credentials for the specified account and access mode
  // Returns PluginProviderResult which can be one of:
  // - SDKv2CompatibleCredentials (AWS SDK v2 entered maintenance on Sept 8, 2024 and will reach end-of-life on Sept 8, 2025)
  // - SDKv3CompatibleCredentialProvider
  // - SDKv3CompatibleCredentials
  public async getProvider(accountId: string, mode: ForReading | ForWriting): Promise<PluginProviderResult> {
    // The access mode can be used to provide different credential sets
    const readOnly = mode === 0 satisfies ForReading;

    // Create appropriate credentials based on your authentication mechanism
    const credentials: SDKv3CompatibleCredentials = {
      accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
      secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
      // Add sessionToken if using temporary credentials
      // sessionToken: 'AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/LTo6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3zrkuWJOgQs8IZZaIv2BXIa2R4Olgk',
      // expireTime: new Date(Date.now() + 3600 * 1000), // 1 hour from now
    };

    return credentials;
  }
}

const plugin: Plugin = {
  version: '1',
  init(host: IPluginHost): void {
    // Register the credential provider to the PluginHost.
    host.registerCredentialProviderSource(new CustomCredentialProviderSource());
  }
};

export = plugin;

ESM


import type { CredentialProviderSource, ForReading, ForWriting, IPluginHost, Plugin, PluginProviderResult, SDKv3CompatibleCredentials } from '@aws-cdk/cli-plugin-contract';

class CustomCredentialProviderSource implements CredentialProviderSource {
  // Friendly name for the provider, used in error messages
  public readonly name: string = 'custom-credential-provider';

  // Check if this provider is available on the current system
  public async isAvailable(): Promise<boolean> {
    // Return false if the plugin cannot be used
    // For example, if it depends on files not present on the host
    return true;
  }

  // Check if this provider can provide credentials for a specific account
  public async canProvideCredentials(accountId: string): Promise<boolean> {
    // Return false if the plugin cannot provide credentials for this account
    // For example, if the account is not managed by this credential system
    return true;
    // You can use patterns to filter specific accounts
    // return accountId.startsWith('123456');
  }

  // Get credentials for the specified account and access mode
  // Returns PluginProviderResult which can be one of:
  // - SDKv2CompatibleCredentials (AWS SDK v2 entered maintenance on Sept 8, 2024 and will reach end-of-life on Sept 8, 2025)
  // - SDKv3CompatibleCredentialProvider
  // - SDKv3CompatibleCredentials
  public async getProvider(accountId: string, mode: ForReading | ForWriting): Promise<PluginProviderResult> {
    // The access mode can be used to provide different credential sets
    const readOnly = mode === 0 satisfies ForReading;

    // Create appropriate credentials based on your authentication mechanism
    const credentials: SDKv3CompatibleCredentials = {
      accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
      secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
      // Add sessionToken if using temporary credentials
      // sessionToken: 'AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/LTo6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3zrkuWJOgQs8IZZaIv2BXIa2R4Olgk',
      // expireTime: new Date(Date.now() + 3600 * 1000), // 1 hour from now
    };

    return credentials;
  }
}

const plugin: Plugin = {
  version: '1',
  init(host: IPluginHost): void {
    // Register the credential provider to the PluginHost.
    host.registerCredentialProviderSource(new CustomCredentialProviderSource());
  }
};

export { plugin as 'module.exports' };

JavaScript

JS commun


// Implement the CredentialProviderSource interface
class CustomCredentialProviderSource {
  constructor() {
    // Friendly name for the provider, used in error messages
    this.name = 'custom-credential-provider';
  }

  // Check if this provider is available on the current system
  async isAvailable() {
    // Return false if the plugin cannot be used
    // For example, if it depends on files not present on the host
    return true;
  }

  // Check if this provider can provide credentials for a specific account
  async canProvideCredentials(accountId) {
    // Return false if the plugin cannot provide credentials for this account
    // For example, if the account is not managed by this credential system
    return true;
    // You can use patterns to filter specific accounts
    // return accountId.startsWith('123456');
  }

  // Get credentials for the specified account and access mode
  // Returns PluginProviderResult which can be one of:
  // - SDKv2CompatibleCredentials (AWS SDK v2 entered maintenance on Sept 8, 2024 and will reach end-of-life on Sept 8, 2025)
  // - SDKv3CompatibleCredentialProvider
  // - SDKv3CompatibleCredentials
  async getProvider(accountId, mode) {
    // The access mode can be used to provide different credential sets
    const readOnly = mode === 0; // 0 indicates ForReading; 1 indicates ForWriting

    // Create appropriate credentials based on your authentication mechanism
    const credentials = {
      accessKeyId: 'ASIAIOSFODNN7EXAMPLE',
      secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
      // Add sessionToken if using temporary credentials
      // sessionToken: 'AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/LTo6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3zrkuWJOgQs8IZZaIv2BXIa2R4Olgk',
      // expireTime: new Date(Date.now() + 3600 * 1000), // 1 hour from now
    };

    return credentials;
  }
}

const plugin = {
  version: '1',
  init(host) {
    // Register the credential provider to the PluginHost.
    host.registerCredentialProviderSource(new CustomCredentialProviderSource());
  }
};

module.exports = plugin;

ESM


// Implement the CredentialProviderSource interface
class CustomCredentialProviderSource {
  constructor() {
    // Friendly name for the provider, used in error messages
    this.name = 'custom-credential-provider';
  }

  // Check if this provider is available on the current system
  async isAvailable() {
    // Return false if the plugin cannot be used
    // For example, if it depends on files not present on the host
    return true;
  }

  // Check if this provider can provide credentials for a specific account
  async canProvideCredentials(accountId) {
    // Return false if the plugin cannot provide credentials for this account
    // For example, if the account is not managed by this credential system
    return true;
    // You can use patterns to filter specific accounts
    // return accountId.startsWith('123456');
  }

  // Get credentials for the specified account and access mode
  // Returns PluginProviderResult which can be one of:
  // - SDKv2CompatibleCredentials (AWS SDK v2 entered maintenance on Sept 8, 2024 and will reach end-of-life on Sept 8, 2025)
  // - SDKv3CompatibleCredentialProvider
  // - SDKv3CompatibleCredentials
  async getProvider(accountId, mode) {
    // The access mode can be used to provide different credential sets
    const readOnly = mode === 0; // 0 indicates ForReading; 1 indicates ForWriting

    // Create appropriate credentials based on your authentication mechanism
    const credentials = {
      accessKeyId: 'ASIAIOSFODNN7EXAMPLE',
      secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
      // Add sessionToken if using temporary credentials
      // sessionToken: 'AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/LTo6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3zrkuWJOgQs8IZZaIv2BXIa2R4Olgk',
      // expireTime: new Date(Date.now() + 3600 * 1000), // 1 hour from now
    };

    return credentials;
  }
}

const plugin = {
  version: '1',
  init(host) {
    // Register the credential provider to the PluginHost.
    host.registerCredentialProviderSource(new CustomCredentialProviderSource());
  }
};

export { plugin as 'module.exports' };

Important

Les informations d'identification obtenues auprès des fournisseurs sont mises en cache par le kit CDK. Il est fortement recommandé que les objets d'identification renvoyés par votre fournisseur soient automatiquement actualisés afin d'éviter les problèmes d'expiration lors d'opérations de longue durée. Pour plus d'informations, consultez la section Informations d'identification dans la AWS documentation du SDK pour la JavaScript version 3.

En savoir plus

Pour en savoir plus sur les plugins CDK Toolkit, consultez le contrat de plug-in AWS CDK Toolkit dans le aws-cdk-cli GitHub référentiel.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Configurer des constructions avec des plans CDK

Utiliser la bibliothèque du kit d'outils CDK