Uso de extensiones privadas en CloudFormation - AWS CloudFormation
Registro de extensiones privadasConfiguración de extensiones de cuentaEspecificación de una versión de una extensión privada que se va a utilizar mediante la AWS CLIPara especificar la versión de enlace por defecto

Uso de extensiones privadas en CloudFormation

Las extensiones privadas son extensiones que ha registrado explícitamente para su uso en su Cuenta de AWS.

Existen dos tipos de extensiones privadas:

  • Extensiones privadas activadas: son copias locales de extensiones de terceros que ha activado para su cuenta y región. Cuando activa una extensión pública de terceros, CloudFormation crea una copia local de esa extensión en el registro de su cuenta.

  • Extensiones privadas registradas: también puede activar extensiones privadas que no se muestran en el registro público de CloudFormation. Estas pueden ser extensiones que haya creado usted o las que se le hayan compartido a través de la organización u otro tercero. Para utilizar dicha extensión privada en la cuenta, primero debe registrarla. Al registrar la extensión, se carga una copia de la extensión en el registro de CloudFormation de su cuenta y se activa.

Cualquier uso de extensiones privadas en su cuenta es análogo a su uso en un entorno aislado. Esto se debe a que las extensiones están controladas por versiones y el comportamiento de aprovisionamiento es específico de la versión, lo que significa que las extensiones privadas se comportan igual que si se hicieran públicas.

nota

Las extensiones privadas y las extensiones públicas activadas de terceros pueden implementar controladores de eventos que se ejecutan durante las operaciones de creación, lectura, actualización, publicación y eliminación. Por eso, el uso de estas extensiones en las pilas de CloudFormation incurre en cargos a su cuenta. Estos se suman a los cargos generados por los recursos creados. Para más información, consulte Precios de AWS CloudFormation.

Para obtener información sobre el desarrollo de extensiones privadas propias, consulte la Guía del usuario de la interfaz de la línea de comandos de CloudFormation.

Registro de extensiones privadas

Para utilizar extensiones privadas que no se muestran en el registro de CloudFormation, tanto si las desarrolla como si se las comparten, antes debe registrarlas con CloudFormation, en las cuentas y regiones donde desea utilizarlas. Al registrar la extensión, se carga una copia de la extensión en el registro de CloudFormation de su cuenta y se activa. Una vez que haya registrado una extensión privada, aparecerá en el registro de CloudFormation para esa cuenta y región, y podrá usarla en las plantillas de su pila.

Puede registrar una extensión mediante el comando register-type de la AWS CLI o el comando submit de la CLI de CloudFormation.

Para registrar una extensión privada mediante la CLI de CloudFormation, consulte Registering extensions (Registro de extensiones) en la Guía del usuario de la CLI de CloudFormation.

Permisos de IAM para registrar una extensión privada.

Como parte del registro de una extensión privada, se especifica un bucket de Amazon S3 que contiene el paquete de proyecto de la extensión. Este paquete contiene todos los archivos fuente necesarios para la extensión que desea registrar. El usuario que registra la extensión debe poder acceder al paquete del proyecto en el bucket de Amazon S3. Es decir, el usuario debe tener permisos GetObject para el paquete de extensión.

Esto se cumple si utiliza el comando register-type de AWS CLI o el comando submit de la CLI de CloudFormation.

Para obtener más información, consulte Acciones, recursos y claves de condición de Amazon S3 en la Guía del usuario de AWS Identity and Access Management.

Registro de extensiones

Registre su extensión en el registro de AWS CloudFormation para que esté disponible para su uso.

Para registrar un enlace mediante AWS CLI

Registre su enlace con CloudFormation para que esté disponible para su uso en el registro de AWS CloudFormation.

  1. (Opcional) Configure el nombre predeterminado de Región de AWS como us-west-2, mediante el envío de la operación configure.

    aws configure
AWS Access Key ID [None]: <Your Access Key ID>
AWS Secret Access Key [None]: <Your Secret Key>
Default region name [None]: us-west-2
Default output format [None]: json

  2. (Opcional) El siguiente comando crea y empaqueta el proyecto de enlace sin registrarlo.

    $ cfn submit --dry-run

  3. Registre su enlace mediante la CLI de CloudFormation cfn submit.

    cfn submit --set-default

    El comando devuelve el siguiente comando:

    {‘ProgressStatus’: ‘COMPLETE’}

    Resultados: ha registrado correctamente su enlace.

Para registrar un tipo de recurso mediante la AWS CLI

Registre su tipo de recurso en CloudFormation para que esté disponible para su uso en el registro de AWS CloudFormation.

  1. Busque el bucket de Amazon S3 que contiene el paquete de proyecto para la extensión privada que desea registrar en la cuenta.

  2. Utilice el comando register-type para registrar la extensión en su cuenta:

    RegisterType es una operación asíncrona y devuelve un token de registro que puede utilizar para hacer un seguimiento del progreso de la solicitud de registro.

    nota

    Si su extensión llama a las API de AWS como parte de su funcionalidad, debe crear un rol de ejecución de IAM que incluya los permisos necesarios para llamar a esas API de AWS y aprovisionar ese rol de ejecución en la cuenta. A continuación, puede especificar este rol de ejecución mediante el parámetro --execution-role-arn. CloudFormation asume entonces ese rol de ejecución para proporcionar las credenciales adecuadas a su tipo de recurso.

    Por ejemplo, el siguiente comando registra el tipo de recurso My::Resource::Example en la Cuenta de AWS actual:

    aws cloudformation register-type --type-name My::Resource::Example --schema-handler-package [s3 object path] --type RESOURCE                
{
    "RegistrationToken": "f5525280-104e-4d35-bef5-8f1fexample"
}

  3. De modo opcional, puede utilizar el token de registro con el comando describe-type-registration para realizar un seguimiento del progreso de su solicitud de registro.

    Cuando CloudFormation completa la solicitud de registro, establece el estado de progreso de la solicitud en COMPLETE.

    En el siguiente ejemplo, se utiliza el token de registro devuelto por el comando describe-type-registration anterior para devolver información de estado de registro.

    aws cloudformation describe-type-registration --registration-token f5525280-104e-4d35-bef5-8f1fexample
{
    "ProgressStatus": "COMPLETE",
    "TypeArn": "arn:aws:cloudformation:us-east-1:012345678910:type/resource/My-Resource-Example",
    "Description": "Deployment is currently in DEPLOY_STAGE of status COMPLETED; ",
    "TypeVersionArn": "arn:aws:cloudformation:us-east-1:111122223333:type/resource/My-Resource-Example/00000001"
}

Configuración de extensiones de cuenta

Una extensión puede incluir propiedades de configuración destinadas a aplicarse a todas las instancias de la extensión para una cuenta y región determinadas. El autor de la extensión las define en la configuración de definición de la extensión. Si hay propiedades obligatorias en la definición de configuración de la extensión, debe especificarlas antes de poder usar la extensión en su cuenta y región.

nota

Si la configuración de tipos incluye referencias dinámicas a valores almacenados en AWS Systems Manager o AWS Secrets Manager, cualquier rol que se use para aprovisionar el tipo (por ejemplo, al crear o actualizar una pila) debe tener los permisos adecuados para recuperar ese valor. En concreto:

  • Si la configuración de tipos contiene un parámetro almacenado en el almacén de parámetros de AWS Systems Manager, el usuario o rol que se use para aprovisionar el tipo debe tener permisos para llamar a GetParameter.

  • Si la configuración de tipos contiene un secreto almacenado en AWS Secrets Manager, el rol o usuario que se use para aprovisionar el tipo debe tener permisos para llamar a GetSecretValue.

Para más información sobre las referencias dinámicas, consulte Uso de referencias dinámicas para especificar valores de plantillas.

Para obtener más información sobre cómo se definen las opciones al desarrollar una extensión, consulte Defining the account-level configuration of an extension (Definición de la configuración de cuenta de una extensión) en la Guía del usuario de CloudFormation para el desarrollo de extensiones.

Para ver los datos de configuración actuales de una extensión en la consola de CloudFormation

  1. Use el registro de CloudFormation para buscar la extensión.

  2. Elija la extensión para ver sus detalles.

  3. En la página de detalles de la extensión, elija la pestaña Configuration (Configuración).

  4. Expanda la pestaña Configuration schema (Esquema de configuración) para ver el esquema de configuración definido para la extensión.

  5. Expanda la pestaña Configuration (Configuración) para ver la configuración actual que ha establecido para esta extensión.

Para ver los datos de configuración actuales de una extensión en AWS CLI

  • Use el comando describe-type para devolver información detallada acerca de la extensión. El elemento ConfigurationSchema de la salida contiene la definición de configuración actual de la extensión en una región determinada.

    Como alternativa, consulte el comando batch-describe-type-configurations para devolver datos de configuración sobre varias extensiones.

Para especificar las propiedades de configuración de los tipos de extensión

Para actualizar las propiedades de configuración para una extensión en la consola de CloudFormation

  1. Use el registro de CloudFormation para buscar la extensión en las extensiones activadas de su cuenta.

  2. Seleccione la extensión para ver sus detalles.

  3. En la página de detalles de la extensión, en la pestaña Configuration (Configuración), seleccione Edit configuration (Editar configuración).

    Como alternativa, desde Actions (Acciones), seleccione Edit (Editar) y, a continuación, seleccione Edit configuration (Editar configuración).

    CloudFormation mostrará la página Configure extension (Configurar extensión). Asegúrese de que View configuration schema (Ver esquema de configuración) esté activado para ver el esquema de definición de configuración actual de la extensión.

  4. En el cuadro de texto Configuration JSON (JSON de configuración), ingrese una cadena JSON que represente el esquema de configuración que desea especificar para esta extensión. Debe validarse con respecto al esquema definido en Configuration schema (Esquema de configuración).

  5. Seleccione Configure extension (Configurar extensión).

Para especificar las propiedades de configuración para una extensión con AWS CLI

  • Use el comando set-type-configuration para especificar la configuración que se utilizará con la extensión en su cuenta y región.

    El JSON que pase para --configuration debe validarse con el esquema de definición de configuración de la extensión. A continuación, se muestra un ejemplo de un comando set-type-configuration que especifica la configuración.

    aws cloudformation set-type-configuration \
    --region us-west-2 \
    --type RESOURCE \
    --type-name My::Resource::Example \
    --configuration-alias default \
    --configuration "{"CredentialKey": "testUserCredential"}"

Especificación de una versión de una extensión privada que se va a utilizar mediante la AWS CLI

Con el tiempo, puede registrar varias versiones de la misma extensión. Puede especificar qué versión de la extensión desea utilizar para las operaciones de CloudFormation.

Para especificar una versión de una extensión

Utilice el comando set-type-default-version para especificar qué versión de la extensión desea utilizar en las operaciones de CloudFormation en su cuenta.

Por ejemplo, el siguiente comando establece la versión predeterminada del tipo de recurso My::Resource::Example en 00000003 para la cuenta actual.

aws cloudformation set-type-default-version \
  --type RESOURCE \
  --type-name My::Resource::Example \
  --version-id 00000003

Para especificar la versión de enlace por defecto

Para especificar la versión predeterminada de su enlace en su cuenta, use el comando set-type-default-version y especifique el tipo, el nombre del tipo y el ID de la versión.

aws cloudformation set-type-default-version \
    --type HOOK \
    --type-name MyCompany::Testing::MyTestHook \
    --version-id 00000003