Referencia del modelo de integración - AWS CodePipeline
Cómo funcionan los tipos de acciones de terceros con el integradorConceptosModelos de integración compatiblesModelo de integración de LambdaModelo de integración de procesos de trabajo

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Referencia del modelo de integración

Existen varias integraciones prediseñadas para servicios de terceros que ayudan a incorporar las herramientas existentes para los clientes en el proceso de lanzamiento de la canalización. Los socios o proveedores de servicios externos utilizan un modelo de integración para implementar tipos de acciones que se utilizarán en CodePipeline.

Utilice esta referencia cuando planifique o trabaje con tipos de acciones que se administran con un modelo de integración compatible en CodePipeline.

Para certificar el tipo de acción de un tercero como una integración de socios con CodePipeline, consulte la Red de socios de AWS (APN). Esta información es un complemento de la AWS CLI Reference.

Cómo funcionan los tipos de acciones de terceros con el integrador

Puede añadir tipos de acciones de terceros a las canalizaciones de los clientes para completar las tareas relacionadas con los recursos de los clientes. El integrador administra las solicitudes de trabajo y ejecuta la acción con CodePipeline. En el siguiente diagrama, se muestra un tipo de acción de terceros creado para que los clientes lo utilicen en su proceso. Una vez que el cliente configura la acción, ésta se ejecuta y crea solicitudes de trabajo que administra el motor de acciones del integrador.

En el diagrama se muestran los siguientes pasos:

  1. La definición de acción se registra y está disponible en CodePipeline. La acción de terceros está disponible para los clientes del proveedor de terceros.

  2. El cliente del proveedor elige y configura la acción en CodePipeline.

  3. La acción se ejecuta y los trabajos se ponen en cola en CodePipeline. Cuando el trabajo está listo en CodePipeline, envía una solicitud de trabajo.

  4. El integrador (el trabajador de las API de sondeo de terceros o de la función de Lambda) recoge la solicitud de trabajo, devuelve una confirmación y trabaja en los artefactos de las acciones.

  5. El integrador devuelve un resultado de éxito o fracaso (el proceso de trabajo utiliza las API de éxito o fracaso o la función de Lambda envía un resultado de éxito o fracaso) con un resultado del trabajo y un token de continuación.

Para obtener información sobre los pasos que puede seguir para solicitar, ver y actualizar un tipo de acción, consulte Trabajar con tipos de acciones.

Conceptos

En esta sección se utilizan los siguientes términos para los tipos de acciones de terceros:

Tipo de acción

Un proceso repetible que se puede reutilizar en canalizaciones que realizan las mismas cargas de trabajo de entrega continua. Los tipos de acciones se identifican mediante Owner, Category, Provider y Version. Por ejemplo:


            {

                "Category": "Deploy",
                "Owner": "AWS",
                "Provider": "CodeDeploy",
                "Version": "1"
            },

Todas las acciones del mismo tipo comparten la misma implementación.

Acción

Una instancia única de un tipo de acción, uno de los procesos discretos que tienen lugar dentro de una etapa de una canalización. Por lo general, esto incluye los valores de usuario específicos de la canalización en la que se ejecuta esta acción.

Definición de la acción

El esquema de un tipo de acción que define las propiedades necesarias para configurar la acción y los artefactos de entrada/salida.

Action execution (Ejecución de acciones)

Conjunto de trabajos que se han ejecutado para determinar si la acción realizada por el cliente se ha realizado correctamente o no.

Motor de ejecución de acciones

Propiedad de la configuración de ejecución de acciones que define el tipo de integración utilizado por un tipo de acción. Los valores válidos son JobWorker y Lambda.

Integration

Describe una pieza de software que ejecuta un integrador para implementar un tipo de acción. CodePipeline admite dos tipos de integración correspondientes a los dos motores de acciones JobWorker y Lambda admitidos.

Integrador

La persona propietaria de la implementación de un tipo de acción.

Trabajo

Un trabajo con el contexto del proceso y del cliente para ejecutar una integración. La ejecución de una acción se compone de una o más tareas.

Proceso de trabajo

El servicio que procesa las entradas del cliente y ejecuta un trabajo.

Modelos de integración compatibles

CodePipeline tiene dos modelos de integración:

  • Modelo de integración Lambda: este modelo de integración es la forma preferida de trabajar con los tipos de acciones en CodePipeline. El modelo de integración de Lambda utiliza una función de Lambda para procesar las solicitudes de trabajo cuando se ejecuta la acción.

  • Modelo de integración de proceso de trabajo: el modelo de integración del proceso de trabajo es el modelo utilizado anteriormente para las integraciones de terceros. El modelo de integración de procesos de trabajo utiliza proceso de trabajo configurado para ponerse en contacto con las API de CodePipeline a fin de procesar las solicitudes de trabajo cuando se ejecuta la acción.

A modo de comparación, en la siguiente tabla se describen las características de los dos modelos:

Modelo de integración de Lambda Modelo de integración de procesos de trabajo
Descripción El integrador escribe la integración como una función de Lambda, que CodePipeline invoca siempre que haya un trabajo disponible para la acción. La función de Lambda no sondea los trabajos disponibles, sino que espera hasta que se reciba la siguiente solicitud de trabajo. El integrador escribe la integración como un proceso de trabajo que consulta constantemente los puestos disponibles en la cartera del cliente. A continuación, el proceso de trabajo ejecuta el trabajo y envía el resultado del trabajo a CodePipeline mediante las API de CodePipeline.
Infraestructura AWS Lambda Implemente el código del proceso de trabajo en la infraestructura del integrador, como las instancias de Amazon EC2.
Esfuerzo de desarrollo La integración solo contiene la lógica empresarial. La integración debe interactuar con las API de CodePipeline además de contener la lógica empresarial.
Esfuerzo operativo Menor esfuerzo operativo, ya que la infraestructura es solo recursos de AWS. Mayor esfuerzo operativo porque el proceso de trabajo necesita su hardware independiente.
Tiempo máximo de ejecución de un trabajo Si la integración debe ejecutarse de forma activa durante más de 15 minutos, no se puede utilizar este modelo. Esta acción está destinada a los integradores que necesitan iniciar un proceso (por ejemplo, iniciar una creación a partir del artefacto de código del cliente) y devolver un resultado cuando finalice. No recomendamos que el integrador siga esperando a que finalice la compilación. En su lugar, devuelva una continuación. CodePipeline crea un nuevo trabajo en otros 30 segundos si se recibe una continuación del código del integrador para comprobar el trabajo hasta que finalice. Con este modelo se pueden mantener trabajos de larga duración (horas/días).

Modelo de integración de Lambda

El modelo de integración de Lambda compatible incluye la creación de la función de Lambda y la definición del resultado para el tipo de acción de terceros.

Actualizar la función de Lambda para administrar la entrada de CodePipeline

Puede crear una función de Lambda nueva. Puede añadir lógica empresarial a la función de Lambda, que se ejecuta siempre que haya un trabajo disponible en su proceso para su tipo de acción. Por ejemplo, dado el contexto del cliente y del proceso, es posible que desee empezar a desarrollar su servicio para el cliente.

Utilice los siguientes parámetros para actualizar su función de Lambda para manejar la entrada de CodePipeline.

Formato:

  • jobId:

    • El ID exclusivo del trabajo generado por el sistema.

    • Tipo: String

    • Patrón: [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}

  • accountId:

    • El ID de la cuenta de AWS del cliente que se utilizará al realizar el trabajo.

    • Tipo: String

    • Patrón: [0-9]{12}

  • data:

    • Otra información sobre un trabajo que una integración utiliza para completar el trabajo.

    • Contiene un mapa de lo siguiente:

      • actionConfiguration:

        • Los datos de configuración de la acción. Los campos de configuración de la acción son una asignación de pares clave-valor para que el cliente introduzca valores. Las claves vienen determinadas por los parámetros clave del archivo de definición del tipo de acción al configurar la acción. En este ejemplo, los valores los determina el usuario de la acción especificando la información en los campos Username y Password.

        • Tipo: asignación de cadena a cadena, presente de forma opcional

          Ejemplo: 

          
    "configuration": {
        "Username": "MyUser",
        "Password": "MyPassword"
    },

      • encryptionKey:

        • Representa información acerca de la clave que se usa para cifrar datos en el almacén de artefactos, como, por ejemplo una clave de AWS KMS.

        • Contenido: tipo de tipo de datos encryptionKey, disponible opcionalmente

      • inputArtifacts:

        • Lista de información sobre un artefacto en el que se va a trabajar, como, por ejemplo, una prueba o un artefacto de compilación.

        • Contenido: lista de tipo de datos Artifact, disponible opcionalmente

      • outputArtifacts:

        • Lista de información sobre el resultado de una acción.

        • Contenido: lista de tipo de datos Artifact, disponible opcionalmente

      • actionCredentials:

        • Representa un objeto de credenciales de sesión de AWS. Estas credenciales son credenciales temporales emitidas por AWS STS. Se pueden usar para acceder a los artefactos de entrada y salida del bucket de S3 que se usa para almacenar los artefactos de la canalización en CodePipeline.

          Estas credenciales también tienen los mismos permisos que la plantilla de declaraciones de política especificada en el archivo de definición del tipo de acción.

        • Contenido: tipo de tipo de datos AWSSessionCredentials, disponible opcionalmente

      • actionExecutionId:

        • El ID externo de la ejecución de la acción.

        • Tipo: String

      • continuationToken:

        • Un token generado por el sistema, como un ID de implementación, que necesita un trabajo para continuar con el trabajo de forma asíncrona.

        • Tipo: cadena, presente de forma opcional

Tipos de datos:

  • encryptionKey:

    • id:

      • El ID utilizado para identificar la clave. Si se trata de una clave de AWS KMS, puede utilizar el ID de la clave, el ARN de la clave o el ARN del alias.

      • Tipo: String

    • type:

      • El tipo de clave de cifrado, como, por ejemplo, la clave de AWS KMS.

      • Tipo: String

      • Valores válidos: KMS

  • Artifact:

    • name:

      • El nombre del artefacto.

      • Tipo: cadena, presente de forma opcional

    • revision:

      • El ID de revisión del artefacto. En función del tipo de objeto, podría ser un ID de confirmación (GitHub) o un ID de revisión (Amazon S3).

      • Tipo: cadena, presente de forma opcional

    • location:

      • La ubicación de un artefacto.

      • Contenido: tipo de tipo de datos ArtifactLocation, disponible opcionalmente

  • ArtifactLocation:

    • type:

      • El tipo de artefacto en la ubicación.

      • Tipo: cadena, presente de forma opcional

      • Valores válidos: S3

    • s3Location:

      • Ubicación del bucket de S3 que contiene una revisión.

      • Contenido: tipo de tipo de datos S3Location, disponible opcionalmente

  • S3Location:

    • bucketName:

      • Nombre del bucket de S3.

      • Tipo: String

    • objectKey:

      • La clave del objeto en el bucket de S3 que identifica de forma exclusiva el objeto en el bucket.

      • Tipo: String

  • AWSSessionCredentials:

    • accessKeyId:

      • La clave de acceso secreta de la sesión.

      • Tipo: String

    • secretAccessKey:

      • La clave de acceso secreta de la sesión.

      • Tipo: String

    • sessionToken:

      • Ll token de la sesión.

      • Tipo: String

Ejemplo:

{
    "jobId": "01234567-abcd-abcd-abcd-012345678910",
    "accountId": "012345678910",
    "data": {
        "actionConfiguration": {
            "key1": "value1",
            "key2": "value2"
        },
        "encryptionKey": {
            "id": "123-abc",
            "type": "KMS"
        },
        "inputArtifacts": [
            {
                "name": "input-art-name",
                "location": {
                    "type": "S3",
                    "s3Location": {
                        "bucketName": "inputBucket",
                        "objectKey": "inputKey"
                    }
                }
            }
        ],
        "outputArtifacts": [
            {
                "name": "output-art-name",
                "location": {
                    "type": "S3",
                    "s3Location": {
                        "bucketName": "outputBucket",
                        "objectKey": "outputKey"
                    }
                }
            }
        ],
        "actionExecutionId": "actionExecutionId",
        "actionCredentials": {
            "accessKeyId": "access-id",
            "secretAccessKey": "secret-id",
            "sessionToken": "session-id"
        },
        "continuationToken": "continueId-xxyyzz"
    }
}

Devuelve los resultados de la función de Lambda a CodePipeline

El recurso del proceso de trabajo del integrador debe devolver una carga útil válida en caso de éxito, fracaso o continuación.

Formato:

  • result: el resultado del trabajo.

    • Obligatorio

    • Valores válidos (no distingue entre mayúsculas y minúsculas):

      • Success: indica que un trabajo se ha realizado correctamente y es terminal.

      • Continue: indica que un trabajo se ha realizado correctamente y debe continuar, por ejemplo, si se vuelve a invocar al trabajador del trabajo para ejecutar la misma acción.

      • Fail: indica que se ha producido un error en un trabajo y es terminal.

  • failureType: un tipo de fallo que se va a asociar a un trabajo fallido.

    La categoría failureType de acciones de los socios describe el tipo de error que se produjo al ejecutar el trabajo. Los integradores configuran el tipo junto con el mensaje de error al devolver el resultado de un error de trabajo a CodePipeline.

    • Opcional. Obligatorio si el resultado es Fail.

    • Debe ser nulo si result es Success o Continue

    • Valores válidos:

      • ConfigurationError

      • JobFailed

      • PermissionsError

      • RevisionOutOfSync

      • RevisionUnavailable

      • SystemUnavailable

  • continuation: el estado de continuación se pasará al siguiente trabajo dentro de la ejecución de la acción actual.

    • Opcional. Obligatorio si el resultado es Continue.

    • Debe ser nulo si result es Success o Fail.

    • Propiedades:

      • State: un hash del estado que se va a aprobar.

  • status: estado de la ejecución de la acción.

    • Opcional.

    • Propiedades:

      • ExternalExecutionId: un ID de ejecución externo o un ID de confirmación opcional para asociarlo al trabajo.

      • Summary: un resumen opcional de lo ocurrido. En los escenarios de error, se convierte en el mensaje de error que ve el usuario.

  • outputVariables: conjunto de pares clave/valor que se transfieren a la siguiente ejecución de la acción.

    • Opcional.

    • Debe ser nulo si result es Continue o Fail.

Ejemplo:

{
    "result": "success",
    "failureType": null,
    "continuation": null,
    "status": {
        "externalExecutionId": "my-commit-id-123",
        "summary": "everything is dandy"
    },
    "outputVariables": {
        "FirstOne": "Nice",
        "SecondOne": "Nicest",
        ...
    }        
}

Utilice los tokens de continuación para esperar los resultados de un proceso asíncrono

El token continuation forma parte de la carga útil y el resultado de la función de Lambda. Es una forma de pasar el estado del trabajo a CodePipeline e indicar que el trabajo debe continuar. Por ejemplo, cuando un integrador inicia una compilación para el cliente en su recurso, no espera a que se complete la compilación, sino que indica a CodePipeline que no tiene un resultado terminal devolviendo el result como continue y devolviendo el ID único de la compilación a CodePipeline como token continuation.

nota

Las funciones de Lambda se pueden ejecutar durante un máximo de 15 minutos. Si el trabajo necesita ejecutarse durante más tiempo, puedes usa los tokens de continuación.

El equipo de CodePipeline invoca al integrador después de 30 segundos con el mismo token continuation en su carga útil para comprobar si está completo. Si la compilación se completa, el integrador devuelve el resultado de éxito o error del terminal; de lo contrario, continúa.

Proporcione a CodePipeline los permisos para invocar la función Lambda del integrador en tiempo de ejecución

Agregue permisos a la función de Lambda de su integrador para proporcionar al servicio CodePipeline permisos para invocarlo mediante la entidad principal del servicio de CodePipeline: codepipeline.amazonaws.com. Los permisos pueden añadirse mediante AWS CloudFormation o la línea de comandos. Para ver un ejemplo, consulte Trabajar con tipos de acciones.

Modelo de integración de procesos de trabajo

Una vez designado el flujo general de trabajo, puede crear el proceso de trabajo. Aunque los detalles específicos de la acción de terceros determinan lo que se necesita para el proceso de trabajo, la mayoría de los procesos de trabajo para acciones de terceros incluyen la siguiente funcionalidad:

  • Sondear si hay trabajos en CodePipeline utilizando PollForThirdPartyJobs.

  • Reconocer trabajos y devolver resultados a CodePipeline usando AcknowledgeThirdPartyJob, PutThirdPartyJobSuccessResult y PutThirdPartyJobFailureResult.

  • Recuperar artefactos o insertarlos en el bucket de Amazon S3 de la canalización. Para descargar artefactos del bucket de Amazon S3 debe crear un cliente de Amazon S3 que utilice la versión 4 de Signature (Sig V4). Sig V4 es necesario para AWS KMS.

    Para cargar artefactos al bucket de Amazon S3, también debe configurar la solicitud PutObject de Amazon S3 para que use el cifrado AWS Key Management Service (AWS KMS). AWS KMS use AWS KMS keys. Para saber si se debe utilizar la Clave administrada de AWS o una clave administrada por el cliente para cargar artefactos, el proceso de trabajo debe consultar los datos del trabajo y comprobar la propiedad de la clave de cifrado. Si está establecida la propiedad, debe utilizar ese identificador clave administrado por el cliente al realizar la configuración de AWS KMS. Si la propiedad de clave es nula, se utiliza la Clave administrada de AWS. CodePipeline usa la Clave administrada de AWS a menos que se configure de otra manera.

    Para ver un ejemplo que muestra cómo crear los parámetros de AWS KMS en Java o.NET, consulte Especificación de AWS Key Management Service en Amazon S3 mediante los AWS SDK. Para obtener más información acerca del bucket de Amazon S3 para CodePipeline, consulte CodePipeline conceptos .

Elegir y configurar una estrategia de administración de permisos para el proceso de trabajo

Para desarrollar un proceso de trabajo para una acción personalizada en CodePipeline, necesita una estrategia que permita integrar la administración de usuarios y permisos.

La estrategia más sencilla es añadir la infraestructura que necesita para el proceso de trabajo creando instancias de Amazon EC2 con un rol de instancia de AWS Identity and Access Management (IAM). Esto le permite escalar fácilmente los recursos que necesite para la integración. Puede utilizar la integración incluida en AWS para simplificar la interacción entre el proceso de trabajo y CodePipeline.

Obtenga más información acerca de Amazon EC2 y determine si es la opción correcta para su integración. Para más información, consulte Amazon EC2 - Alojamiento de servidores virtuales. Para obtener información sobre cómo configurar una instancia de Amazon EC2, consulte Introducción a las instancias de Amazon EC2 Linux.

Otra estrategia que puede considerar es utilizar federación de identidades con IAM para integrar los recursos y el sistema de proveedor de identidad que ya tiene. Esta estrategia resulta útil si ya tiene un proveedor de identidad corporativo o una configuración que admita usuarios que utilicen proveedores de identidad web. La federación de identidades le permite garantizar un acceso seguro a los recursos de AWS, incluido CodePipeline, sin necesidad de crear o administrar usuarios de IAM. Puede utilizar características y políticas sobre los requisitos de seguridad de contraseñas y la rotación de credenciales. Puede utilizar aplicaciones de ejemplo como plantillas para su propio diseño. Para obtener información, consulte Administrar federación.

Para proporcionar acceso, agregue permisos a sus usuarios, grupos o roles:

A continuación se muestra una política de ejemplo que puede crear para utilizarla con un proceso de trabajo de terceros. Esta política es solo un ejemplo y se ofrece "tal cual".

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codepipeline:PollForThirdPartyJobs",
        "codepipeline:AcknowledgeThirdPartyJob",
        "codepipeline:GetThirdPartyJobDetails",
        "codepipeline:PutThirdPartyJobSuccessResult",
        "codepipeline:PutThirdPartyJobFailureResult"
      ],
      "Resource": [
        "arn:aws:codepipeline:us-east-2::actionType:ThirdParty/Build/Provider/1/"  
      ]              
    }
  ]
}