Cómo crear complementos Cómo cargar complementos con la CLI de CDK Implementar complementos de proveedores de credenciales Más información

Configurar complementos para el kit de herramientas de CDK

El kit de herramientas de AWS CDK admite complementos que agregan capacidades nuevas a sus flujos de trabajo de CDK. Los complementos están diseñados principalmente para usarse con la interfaz de línea de comandos de CDK (CLI de CDK), aunque también se pueden usar con la biblioteca del kit de herramientas de CDK mediante programación. Proporcionan una manera estandarizada de ampliar la funcionalidad, como las fuentes de credenciales alternativas.

nota

Si bien el sistema de complementos funciona tanto con la CLI de CDK como con la biblioteca del kit de herramientas de CDK, está diseñado principalmente para su uso en la CLI. Cuando se utiliza la biblioteca del kit de herramientas de CDK de forma programática, a menudo hay formas más sencillas y directas de realizar las mismas tareas sin complementos, especialmente para la administración de credenciales.

Actualmente, el kit de herramientas de CDK admite una capacidad de complemento:

Proveedores de credenciales de AWS personalizados: cree métodos alternativos para obtener credenciales de AWS más allá de los mecanismos integrados.

Cómo crear complementos

Para crear un complemento del kit de herramientas de CDK, primero debe crear un módulo de Node.js, en TypeScript o JavaScript, que se pueda cargar con el kit de herramientas de CDK. Este módulo exporta un objeto con una estructura específica que el kit de herramientas de CDK puede reconocer. Como mínimo, el objeto exportado debe incluir un identificador de versión y una función de inicialización que reciba una instancia IPluginHost, que el complemento utiliza para registrar sus capacidades.

ejemplo

TypeScript

CommonJS


// 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

CommonJS


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

nota

Los complementos del kit de herramientas de CDK se cargan como módulos CommonJS. Puede crear su complemento como un módulo ECMAScript (ESM), pero debe cumplir con algunas restricciones:

El módulo no puede contener el nivel superior await ni importar ningún módulo que contenga el nivel superior await.
El módulo debe garantizar la compatibilidad exportando el objeto del complemento con el nombre de exportación module.exports: export { plugin as 'module.exports' }.

Cómo cargar complementos con la CLI de CDK

Existen dos opciones para especificar los complementos:

Opción 1: utilice la opción de línea de comandos --plugin


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

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

El valor del argumento --plugin debe ser un archivo JavaScript que, cuando se importe mediante la función require() Node.js, devuelva un objeto que implemente la interfaz Plugin.

Opción 2: agregar entradas a los archivos de configuración

Puede añadir las especificaciones del complemento al archivo específico del proyecto cdk.json o al archivo de configuración global ~/.cdk.json:


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

Con cualquier enfoque, la CLI de CDK cargará los complementos especificados antes de ejecutar los comandos.

Cargue los complementos en código con la biblioteca del kit de herramientas de CDK

Al trabajar con la biblioteca del kit de herramientas de CDK mediante programación, puede cargar los complementos directamente en el código utilizando la instancia PluginHost del paquete @aws-cdk/toolkit-lib. PluginHost proporciona un método load() para cargar los complementos por nombre o ruta del módulo.

ejemplo

El método load() toma un único parámetro, moduleSpec, que es el nombre o la ruta del módulo del complemento que se va a cargar. Puede ser:

Un nombre de módulo Node.js instalado en el directorio node_modules.
Una ruta de archivo relativa o absoluta a un módulo de JavaScript o TypeScript.

Implementar complementos de proveedores de credenciales

El principal caso de uso actual de los complementos es crear proveedores personalizados de credenciales de AWS. Al igual que la AWS CLI, la CLI de CDK necesita credenciales de AWS para la autenticación y la autorización. Sin embargo, hay varias situaciones en las que la resolución de credenciales estándar podría fallar:

No se puede obtener el conjunto inicial de credenciales.
No se puede obtener la cuenta donde pertenecen las credenciales iniciales.
La cuenta asociada a las credenciales es diferente a la cuenta en la que la CLI está intentando operar.

Para abordar estos escenarios, el kit de herramientas de CDK admite los complementos de los proveedores de credenciales. Estos complementos implementan la interfaz CredentialProviderSource del paquete @aws-cdk/cli-plugin-contract y se registran en el kit de herramientas mediante el método registerCredentialProviderSource. Esto permite al kit de herramientas de CDK obtener credenciales de AWS de fuentes no estándar, como sistemas de autenticación especializados o almacenes de credenciales personalizados.

Para implementar un proveedor de credenciales personalizado, cree una clase que ejecute la interfaz requerida:

ejemplo

TypeScript

CommonJS


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

CommonJS


// 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' };

importante

El kit de herramientas de CDK almacena en caché las credenciales obtenidas de los proveedores. Se recomienda encarecidamente que los objetos de credenciales que el proveedor devuelve se actualicen automáticamente con el fin de evitar problemas de caducidad durante las operaciones de larga duración. Para obtener más información, consulte Credenciales en la documentación del AWS SDK para JavaScript v3.

Más información

Para obtener más información sobre los complementos del kit de herramientas de CDK, consulte el Contrato de complementos del kit de herramientas de AWS CDK en el repositorio de GitHub aws-cdk-cli.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Conserve los recursos al refactorizar el código del CDK

Utilice la biblioteca del kit de herramientas de CDK