AWS CloudFormation

Ejecuta una operación en una AWS CloudFormation pila. Una pila es un conjunto de AWS recursos que se pueden gestionar como una sola unidad. Los recursos de una pila se definen según la plantilla de AWS CloudFormation de la pila. Un conjunto de cambios crea una comparación que se puede visualizar sin modificar la pila original. Para obtener información sobre los tipos de AWS CloudFormation acciones que se pueden realizar en las pilas y los conjuntos de cambios, consulte el ActionMode parámetro.

Para crear un mensaje de error para una AWS CloudFormation acción en la que se ha producido un error en una operación de apilado, CodePipeline llama a la AWS CloudFormation DescribeStackEvents API. Si un rol de IAM de acción tiene permiso para acceder a esa API, los detalles sobre el primer recurso fallido se incluirán en el mensaje de CodePipeline error. De lo contrario, si la política de roles no tiene el permiso adecuado, CodePipeline ignorará el acceso a la API y, en su lugar, mostrará un mensaje de error genérico. Para ello, el permiso cloudformation:DescribeStackEvents debe agregarse al rol de servicio o a otros roles de IAM de la canalización.

Si no desea que los detalles del recurso aparezcan en los mensajes de error de la canalización, puede eliminar el permiso cloudformation:DescribeStackEvents para revocar este permiso para el rol de IAM de acción.

Tipo de acción

• Categoría: Deploy

• Propietario: AWS

• Proveedor: CloudFormation

• Versión: 1

Parámetros de configuración

ActionMode

Obligatorio: sí

ActionModees el nombre de la acción que se AWS CloudFormation realiza en una pila o conjunto de cambios. Están disponibles los siguientes modos de acción:

• CHANGE_SET_EXECUTE ejecuta un conjunto de cambios para la pila de recursos que se basa en un conjunto de actualizaciones de recursos especificadas. Con esta acción, AWS CloudFormation comienza a alterar la pila.

• CHANGE_SET_REPLACE crea el conjunto de cambios, si no existe, basándose en el nombre de la pila y la plantilla que envíe. Si el conjunto de cambios existe, lo AWS CloudFormation elimina y, a continuación, crea uno nuevo.

• CREATE_UPDATE crea la pila si no existe. Si la pila existe, AWS CloudFormation actualiza la pila. Utilice esta acción para actualizar pilas existentes. Por el contrarioREPLACE_ON_FAILURE, si la pila existe y se encuentra en un estado fallido, CodePipeline no la eliminará ni la reemplazará.

• DELETE_ONLY elimina una pila. Si especifica una pila que no existe, la acción se realiza de forma satisfactoria sin eliminar una pila.

• REPLACE_ON_FAILURE crea una pila si no existe. Si la pila existe y se encuentra en un estado fallido, la AWS CloudFormation elimina y, a continuación, crea una nueva pila. Si la pila no está en un estado fallido, la AWS CloudFormation actualiza.

  La pila está en un estado de error cuando se muestra alguno de los siguientes tipos de estado en AWS CloudFormation:

  • ROLLBACK_FAILED

  • CREATE_FAILED

  • DELETE_FAILED

  • UPDATE_ROLLBACK_FAILED

  Utilice esta acción para sustituir automáticamente pilas fallidas sin recuperarlos ni solucionar sus problemas.

  importante

  Le recomendamos que utilice REPLACE_ON_FAILURE solo con fines de prueba, ya que podría eliminar la pila.

StackName

Obligatorio: sí

StackName es el nombre de una pila existente o una pila que desea crear.

Capacidades

Obligatorio: condicional

El uso de Capabilities reconoce que la plantilla podría tener las capacidades de crear y actualizar algunos recursos por sí misma y que estas capacidades se determinan en función de los tipos de recursos de la plantilla.

Esta propiedad es necesaria si tiene recursos de IAM en la plantilla de pila o si crea una pila directamente desde una plantilla que contiene macros. Para que la AWS CloudFormation acción funcione correctamente de esta manera, debe reconocer explícitamente que desea que lo haga con una de las siguientes capacidades:

• CAPABILITY_IAM

• CAPABILITY_NAMED_IAM

• CAPABILITY_AUTO_EXPAND

Puede especificar más de una capacidad mediante el uso de una coma (sin espacio) entre las capacidades. El ejemplo de Declaración de acciones muestra una entrada con las propiedades CAPABILITY_IAM y CAPABILITY_AUTO_EXPAND.

Para obtener más información al respectoCapabilities, consulte las propiedades que aparecen UpdateStacken la referencia de la AWS CloudFormation API.

ChangeSetName

Obligatorio: condicional

ChangeSetName es el nombre de un conjunto de cambios existentes o un nuevo conjunto de cambios que desee crear para la pila especificada.

Esta propiedad es necesaria para los siguientes modos de acción: CHANGE_SET_REPLACE y CHANGE_SET_EXECUTE. Para todos los demás modos de acción, se pasa por alto esta propiedad.

RoleArn

Obligatorio: condicional

El RoleArn es el ARN del rol de servicio de IAM que AWS CloudFormation asume cuando opera en los recursos de la pila especificada. RoleArn no se aplica al ejecutar un conjunto de cambios. Si no lo utiliza CodePipeline para crear el conjunto de cambios, asegúrese de que el conjunto o la pila de cambios tengan una función asociada.

nota

Este rol debe estar en la misma cuenta que el role de la acción que se está ejecutando, tal como se configura en la declaración de acción RoleArn.

Esta propiedad es necesaria para los siguientes modos de acción:

• CREATE_UPDATE

• REPLACE_ON_FAILURE

• DELETE_ONLY

• CHANGE_SET_REPLACE

nota

AWS CloudFormation recibe una URL de la plantilla firmada por S3; por lo tanto, RoleArn no necesita permiso para acceder al depósito de artefactos. Sin embargo, la acción RoleArn necesita permiso para acceder al bucket de artefactos para generar la URL firmada.

TemplatePath

Obligatorio: condicional

TemplatePathrepresenta el archivo de plantilla AWS CloudFormation . Incluya el archivo en un artefacto de entrada en esta acción. El nombre del archivo sigue este formato:

Artifactname::TemplateFileName

Artifactnamees el nombre del artefacto de entrada tal como aparece en CodePipeline. Por ejemplo, una etapa de origen con el nombre de artefacto de SourceArtifact y un nombre de archivo template-export.json crea un nombre TemplatePath, tal y como se muestra en este ejemplo:

"TemplatePath": "SourceArtifact::template-export.json"

Esta propiedad es necesaria para los siguientes modos de acción:

• CREATE_UPDATE

• REPLACE_ON_FAILURE

• CHANGE_SET_REPLACE

Para todos los demás modos de acción, se pasa por alto esta propiedad.

nota

El archivo AWS CloudFormation de plantilla que contiene el cuerpo de la plantilla tiene una longitud mínima de 1 byte y una longitud máxima de 1 MB. Para las acciones de AWS CloudFormation despliegue en CodePipeline, el tamaño máximo del artefacto de entrada es siempre de 256 MB. Para obtener más información, consulte Cuotas en AWS CodePipeline y Límites de AWS CloudFormation.

OutputFileName

Obligatorio: no

Se utiliza OutputFileName para especificar un nombre de archivo de salida, por ejemploCreateStackOutput.json, que se CodePipeline añada al artefacto de salida de la canalización para esta acción. El archivo JSON contiene el contenido de la Outputs sección de la AWS CloudFormation pila.

Si no especificas un nombre, CodePipeline no generará un archivo o artefacto de salida.

ParameterOverrides

Obligatorio: no

Los parámetros se definen en la plantilla de pila y le permiten proporcionarles valores en el momento de la creación o actualización de la pila. Puede utilizar un objeto JSON para establecer valores de parámetros en la plantilla (estos valores anulan los establecidos en el archivo de configuración de la plantilla). Para obtener más información sobre el uso de anulaciones de parámetros, consulte Propiedades de configuración (objeto JSON).

Le recomendamos que use el archivo de configuración de la plantilla para la mayoría de los valores de parámetros. Utilice anulaciones de parámetros solo para valores que no se conocen hasta que la canalización se está ejecutando. Para obtener más información, consulte Uso de funciones de anulación de parámetros con CodePipeline canalizaciones en la Guía del AWS CloudFormation usuario.

nota

Todos los nombres de parámetros deben estar presentes en la plantilla de pila.

TemplateConfiguration

Obligatorio: no

TemplateConfiguration es el archivo de configuración de la plantilla. Incluya el archivo en un artefacto de entrada en esta acción. Puede incluir valores de parámetros de plantilla y una política de pilas. Para obtener más información sobre el formato del archivo de configuración de plantilla, consulte Artefactos de AWS CloudFormation.

El nombre del archivo de configuración de la plantilla se ajusta a este formato:

Artifactname::TemplateConfigurationFileName

Artifactnamees el nombre del artefacto de entrada tal como aparece en. CodePipeline Por ejemplo, una etapa de origen con el nombre de artefacto de SourceArtifact y un nombre de archivo test-configuration.json crea un nombre TemplateConfiguration, tal y como se muestra en este ejemplo:

"TemplateConfiguration": "SourceArtifact::test-configuration.json"

Artefactos de entrada

• Número de artefactos: 0 to 10

• Descripción: Como entrada, la AWS CloudFormation acción acepta artefactos de forma opcional para los siguientes fines:

  • Para proporcionar el archivo de plantilla de pila que se va a ejecutar (consulte el parámetro TemplatePath).

  • Para proporcionar el archivo de configuración de la plantilla que se va a utilizar (consulte el parámetro TemplateConfiguration). Para obtener más información sobre el formato del archivo de configuración de plantilla, consulte Artefactos de AWS CloudFormation.

  • Proporcionar el artefacto para que una función Lambda se despliegue como parte de la AWS CloudFormation pila.

Artefactos de salida

• Número de artefactos: 0 to 1

• Descripción: si se especifica el parámetro OutputFileName, esta acción produce un artefacto de salida que incluye un archivo JSON con el nombre especificado. El archivo JSON incluye el contenido de la sección Outputs de la pila de AWS CloudFormation .

  Para obtener más información acerca de la sección Outputs que puede crear para la acción de AWS CloudFormation , consulte Salidas.

Variables de salida

Cuando se configura, esta acción produce variables a las que se puede hacer referencia mediante la configuración de acción de una acción descendente en la canalización. Configure una acción con un espacio de nombres para que esas variables estén disponibles para la configuración de las acciones posteriores.

En el caso de las AWS CloudFormation acciones, las variables se generan a partir de cualquier valor designado en la Outputs sección de una plantilla de pila. Tenga en cuenta que los únicos modos de CloudFormation acción que generan resultados son aquellos que dan como resultado la creación o actualización de una pila, como la creación de la pila, las actualizaciones de la pila y la ejecución de conjuntos de cambios. Los modos de acción correspondientes que generan variables son:

• CHANGE_SET_EXECUTE

• CHANGE_SET_REPLACE

• CREATE_UPDATE

• REPLACE_ON_FAILURE

Para obtener más información, consulte Variables. Para ver un tutorial que muestra cómo crear una canalización con una acción de CloudFormation despliegue en una canalización que utilice variables CloudFormation de salida, consulteTutorial: Crear una canalización que utilice variables de las acciones de AWS CloudFormation despliegue.

Declaración de acciones

YAML

Name: ExecuteChangeSet
ActionTypeId:
  Category: Deploy
  Owner: AWS
  Provider: CloudFormation
  Version: '1'
RunOrder: 2
Configuration:
  ActionMode: CHANGE_SET_EXECUTE
  Capabilities: CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND
  ChangeSetName: pipeline-changeset
  ParameterOverrides: '{"ProjectId": "my-project","CodeDeployRole": "CodeDeploy_Role_ARN"}'
  RoleArn: CloudFormation_Role_ARN
  StackName: my-project--lambda
  TemplateConfiguration: 'my-project--BuildArtifact::template-configuration.json'
  TemplatePath: 'my-project--BuildArtifact::template-export.yml'
OutputArtifacts: []
InputArtifacts:
  - Name: my-project-BuildArtifact

JSON

{
    "Name": "ExecuteChangeSet",
    "ActionTypeId": {
        "Category": "Deploy",
        "Owner": "AWS",
        "Provider": "CloudFormation",
        "Version": "1"
    },
    "RunOrder": 2,
    "Configuration": {
        "ActionMode": "CHANGE_SET_EXECUTE",
        "Capabilities": "CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND",
        "ChangeSetName": "pipeline-changeset",
        "ParameterOverrides": "{\"ProjectId\": \"my-project\",\"CodeDeployRole\": \"CodeDeploy_Role_ARN\"}",
        "RoleArn": "CloudFormation_Role_ARN",
        "StackName": "my-project--lambda",
        "TemplateConfiguration": "my-project--BuildArtifact::template-configuration.json",
        "TemplatePath": "my-project--BuildArtifact::template-export.yml"
    },
    "OutputArtifacts": [],
    "InputArtifacts": [
        {
             "Name": "my-project-BuildArtifact"
        }
    ]
},

Véase también

Los recursos relacionados siguientes pueden serle de ayuda cuando trabaje con esta acción.

• Referencia sobre las propiedades de configuración: este capítulo de referencia de la Guía del AWS CloudFormation usuario proporciona más descripciones y ejemplos de estos CodePipeline parámetros.

• AWS CloudFormation Referencia de la API: el CreateStackparámetro de la referencia de la AWS CloudFormation API describe los parámetros de pila de AWS CloudFormation las plantillas.