Cómo se integran las herramientas personalizadas de compilación, pruebas e implementación con Code Stream

Como administrador o desarrollador de DevOps, puede crear scripts personalizados que amplíen la capacidad de Code Stream.

Con un script, puede integrar Code Stream con sus propias API y herramientas de integración continua (Continuous Integration, CI) y distribución continua (Continuous Delivery, CD) que compilan, prueban e implementan las aplicaciones. Los scripts personalizados son especialmente útiles si no se exponen las API de aplicaciones de manera pública.

El script personalizado puede hacer casi todo lo necesario para que las herramientas de compilación, pruebas e implementación se integren con Code Stream. Por ejemplo, el script puede funcionar con el área de trabajo de la canalización para tareas de integración continua que compilan y prueban la aplicación, así como para tareas de entrega continua que implementan la aplicación. Puede enviar un mensaje a Slack cuando finaliza una canalización, etc.

El área de trabajo de canalización de Code Stream admite Docker y Kubernetes para tareas de integración continua y tareas personalizadas.

Para obtener más información sobre la configuración del área de trabajo, consulte Configurar el área de trabajo de la canalización.

Escriba el script personalizado en uno de los lenguajes compatibles. En el script, incluya la lógica empresarial y defina las entradas y las salidas. Los tipos de salida pueden ser números, cadenas, texto y contraseñas. Puede crear varias versiones de un script personalizado con diferentes entradas, salidas y lógicas empresariales.

Los scripts que cree residirán en la instancia de Code Stream. Puede importar código YAML para crear una integración personalizada o exportar el script como un archivo YAML para utilizarlo en otra instancia de Code Stream.

Haga que la canalización ejecute una versión publicada del script en una tarea personalizada. Si tiene varias versiones publicadas, puede establecer una de ellas como la más reciente para que aparezca con la etiqueta más reciente --> cuando seleccione la tarea personalizada.

Cuando una canalización utiliza una integración personalizada y se intenta eliminarla, aparece un mensaje de error que indica que no se puede eliminar.

Al eliminar una integración personalizada, se eliminan todas las versiones de su script personalizado. Si tiene una canalización existente con una tarea personalizada que utiliza cualquier versión del script, se producirá un error en esa canalización. Para asegurarse de que no se produzcan errores en las canalizaciones existentes, puede descartar y retirar la versión del script que ya no desee utilizar. Si ninguna canalización utiliza esa versión, puede eliminarla.

Tabla 1. Qué hacer después de escribir el script personalizado
Qué hacer...	Más información sobre esta acción...
Agregue una tarea personalizada a la canalización.	La tarea personalizada: Se ejecuta en el mismo contenedor que otras tareas de CI de la canalización. Incluye variables de entrada y de salida que el script rellena antes de que la canalización ejecute la tarea personalizada. Admite varios tipos de datos y varios tipos de metadatos que define como entradas y salidas en el script.
Seleccione el script en la tarea personalizada.	Declare las propiedades de entrada y de salida en el script.
Guarde la canalización y, a continuación, habilítela y ejecútela.	Cuando se ejecuta la canalización, la tarea personalizada llama a la versión del script especificado y ejecuta la lógica empresarial que contiene, lo que integra la herramienta de compilación, pruebas e implementación con Code Stream.
Una vez que se ejecute la canalización, observe las ejecuciones.	Compruebe que la canalización ha producido los resultados esperados.

Cuando se utiliza una tarea personalizada que llama a una versión de integración personalizada, se pueden incluir variables de entorno personalizadas como pares nombre-valor en la pestaña Área de trabajo de la canalización. Cuando la imagen del compilador crea el contenedor del área de trabajo que ejecuta la tarea de CI e implementa la imagen, Code Stream envía las variables de entorno a ese contenedor.

Por ejemplo, cuando la instancia de Code Stream requiere un proxy web, y se utiliza un host de Docker a fin de crear un contenedor para una integración personalizada, Code Stream ejecuta la canalización y envía las variables de configuración del proxy web a ese contenedor.

Tabla 2. Ejemplo de pares nombre-valor de variables de entorno
Nombre	Valor
HTTPS_PROXY	http://10.0.0.255:1234
https_proxy	http://10.0.0.255:1234
NO_PROXY	10.0.0.32, *.dept.vsphere.local
no_proxy	10.0.0.32, *.dept.vsphere.local
HTTP_PROXY	http://10.0.0.254:1234
http_proxy	http://10.0.0.254:1234
PATH	/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

Los pares nombre-valor aparecen en la interfaz de usuario de la siguiente manera:

Code Stream envía las variables de entorno al contenedor que crea la imagen del compilador.

En este ejemplo, se crea una integración personalizada que conecta Code Stream con la instancia de Slack y publica un mensaje en un canal de Slack.

Requisitos previos

Para escribir un script personalizado, asegúrese de tener uno de estos lenguajes: Python 2, Python 3, Node.js o cualquiera de estos lenguajes de shell: Bash, sh o zsh.
Genere una imagen de contenedor mediante el tiempo de ejecución de Node.js o Python instalado.

Procedimiento

Cree la integración personalizada.

Haga clic en Integraciones personalizadas > Nuevo e introduzca un nombre pertinente.
Seleccione el entorno de tiempo de ejecución que prefiera.
Haga clic en Crear.
Se abrirá el script mostrando el código, que incluye el entorno de tiempo de ejecución requerido. Por ejemplo, runtime: "nodejs". El script debe incluir el tiempo de ejecución que la imagen de Builder usa, de forma que la tarea personalizada que agregue a la canalización se realice correctamente cuando la canalización se ejecute. De lo contrario, se producirá un error en la tarea personalizada.

Las principales áreas de los YAML de integración personalizada incluyen el tiempo de ejecución, el código, las propiedades de entrada y las propiedades de salida. Este procedimiento explica diversos tipos y sintaxis.


Claves de YAML de integración personalizada	Descripción
runtime	Entorno de tiempo de ejecución de la tarea en el que Code Stream ejecuta el código, que puede ser una de estas cadenas sin distinción entre mayúsculas y minúsculas: nodejs python2 python3 shell Si no se proporciona nada, se asume el valor predeterminado de shell.
code	Lógica empresarial personalizada que se ejecutará como parte de la tarea personalizada.
inputProperties	Matriz de propiedades de entrada que se capturarán como parte de la configuración de la tarea personalizada. Por lo general, estas propiedades se utilizan en el código.
outputProperties	Matriz de propiedades de salida que puede exportar de la tarea personalizada para propagarla a la canalización.

Declare las propiedades de entrada en el script mediante los tipos de datos y los metadatos disponibles.

Las propiedades de entrada se transfieren como contexto al script en la sección code: del YAML.


Claves de entrada de YAML de tareas personalizadas	Descripción	Obligatorio
`type`	Tipos de entrada para representar: `text` `textarea` `number` `checkbox` `password` `select`	Sí
`name`	Nombre o cadena de entrada a la tarea personalizada, que se inyecta en el código YAML de integración personalizada. Debe ser único para cada propiedad de entrada definida para una integración personalizada.	Sí
`title`	Etiqueta de la cadena de texto de la propiedad de entrada de la tarea personalizada en el lienzo del modelo de canalización. Si se deja en blanco, se utiliza `name` de forma predeterminada.	No
`required`	Determina si un usuario debe introducir la propiedad de entrada al configurar la tarea personalizada. Establézcalo en true o false. Cuando el valor es true, si un usuario no proporciona un valor al configurar la tarea personalizada en el lienzo de canalización, el estado de la tarea permanece como sin configurar.	No
`placeHolder`	Texto predeterminado para el área de entrada de propiedades de entrada cuando no hay ningún valor. Se asigna al atributo del marcador de posición HTML. Solo se admite para ciertos tipos de propiedad de entrada.	No
`defaultValue`	Valor predeterminado que rellena el área de entrada de la propiedad de entrada cuando la tarea personalizada se representa en la página del modelo de canalización.	No
`bindable`	Determina si la propiedad de entrada acepta variables de signo de dólar al modelar la tarea personalizada en el lienzo de canalización. Agrega el indicador $ junto al título. Solo se admite para ciertos tipos de propiedad de entrada.	No
`labelMessage`	Cadena que actúa como información sobre herramientas de ayuda para los usuarios. Agrega un icono de información sobre herramientas i junto al título de entrada.	No
`enum`	Toma una matriz de valores que muestra las opciones de la propiedad de entrada seleccionada. Solo se admite para ciertos tipos de propiedad de entrada. Cuando un usuario selecciona una opción y la guarda para la tarea personalizada, el valor de inputProperty corresponde a este valor y aparece en el modelado de tareas personalizado. Por ejemplo, el valor 2015. 2015 2016 2017 2018 2019 2020	No
`options`	Toma una matriz de objetos usando optionKey y optionValue. optionKey. Valor propagado a la sección de código de la tarea. optionValue. Cadena que muestra la opción en la interfaz de usuario. Solo se admite para ciertos tipos de propiedad de entrada. Opciones: optionKey: key1. Cuando se selecciona y se guarda para la tarea personalizada, el valor de inputProperty corresponde a key1 en la sección de código. optionValue: 'Etiqueta para 1'. Valor para mostrar de key1 en la interfaz de usuario. No aparece en ningún otro lugar para la tarea personalizada. optionKey: key2 optionValue: 'Etiqueta para 2' optionKey: key3 optionValue: 'Etiqueta para 3'	No
`minimum`	Acepta un número que actúa como el valor mínimo que es válido para esta propiedad de entrada. Solo se admite para la propiedad de entrada del tipo de número.	No
`maximum`	Acepta un número que actúa como el valor máximo que es válido para esta propiedad de entrada. Solo se admite para la propiedad de entrada del tipo de número.	No

Tabla 3. Tipos de datos y metadatos admitidos para scripts personalizados
Tipos de datos admitidos	Metadatos admitidos para la entrada
String Text List: como una lista de cualquier tipo Map: como map[string]any Secure: se representa como un cuadro de texto de contraseña, cifrado cuando se guarda la tarea personalizada Number Boolean: se muestra como cuadros de texto URL: igual que una cadena, con validación adicional Botón de selección o de radio	type: un tipo como String \| Text... default: valor predeterminado options: lista o asignación de opciones que se usará con un botón de selección o de radio min: valor o tamaño mínimo max: valor o tamaño máximo title: nombre detallado del cuadro de texto placeHolder: marcador de posición de la interfaz de usuario description: se convierte en información sobre herramientas

Por ejemplo:

inputProperties:
        - name: message
          type: text
          title: Message
          placeHolder: Message for Slack Channel
          defaultValue: Hello Slack
          bindable: true
          labelInfo: true
          labelMessage: This message is posted to the Slack channel link provided in the code

Declare las propiedades de salida del script.

El script captura las propiedades de salida de la sección code: de la lógica empresarial del script, donde declara el contexto de la salida.

Cuando se ejecuta la canalización, puede introducir el código de respuesta para la salida de la tarea. Por ejemplo, 200.

Las claves que Code Stream admite para cada outputProperty.


key	Descripción
type	Actualmente incluye un solo valor de `label`.
name	Clave que emite el bloque de código de YAML de integración personalizada.
title	Etiqueta en la interfaz de usuario que muestra outputProperty.

Por ejemplo:

outputProperties:
  - name: statusCode
    type: label
    title: Status Code

Para interactuar con la entrada y la salida del script personalizado, obtenga una propiedad de entrada o establezca una propiedad de salida mediante context.

Para una propiedad de entrada: (context.getInput("key"))

Para una propiedad de salida: (context.setOutput("key", "value"))

Para Node.js:

var context = require("./context.js")
var message = context.getInput("message");
//Your Business logic
context.setOutput("statusCode", 200);

Para Python:

from context import getInput, setOutput
message = getInput('message')
//Your Business logic
setOutput('statusCode', '200')

Para Shell:

# Input, Output properties are environment variables
echo ${message} # Prints the input message
//Your Business logic
export statusCode=200 # Sets output property statusCode

En la sección code:, declare toda la lógica empresarial de la integración personalizada.

Por ejemplo, con el entorno de tiempo de ejecución de Node.js:

code: |
    var https = require('https');
    var context = require("./context.js")
    
    //Get the entered message from task config page and assign it to message var
    var message = context.getInput("message");
    var slackPayload = JSON.stringify(
        {
            text: message
        });

    const options = {
        hostname: 'hooks.slack.com',
        port: 443,
        path: '/YOUR_SLACK_WEBHOOK_PATH',
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Content-Length': Buffer.byteLength(slackPayload)
        }
    };
    
    // Makes a https request and sets the output with statusCode which 
    // will be displayed in task result page after execution
    const req = https.request(options, (res) => {
        context.setOutput("statusCode", res.statusCode);
    });

    req.on('error', (e) => {
        console.error(e);
    });
    req.write(slackPayload);
    req.end();

Antes de crear una versión del script de integración personalizado y publicarla, descargue el archivo de contexto para Python o Node.js y pruebe la lógica empresarial que incluyó en el script.
1. Coloque el puntero en la parte superior del lienzo y, a continuación, haga clic en el botón de archivo de contexto. Por ejemplo, si el script se encuentra en Python, haga clic en CONTEXT.PY.
2. Modifique el archivo y guárdelo.
3. En el sistema de desarrollo, ejecute y pruebe su script personalizado con la ayuda del archivo de contexto.
Aplique una versión al script de integración personalizado.
1. Haga clic en Versión.
2. Introduzca la información de la versión.
3. Haga clic en Versión de publicación para poder seleccionar el script en la tarea personalizada.
4. Para crear la versión, haga clic en Crear.
(opcional) Puede establecer cualquier versión publicada de un script de integración personalizado como la más reciente para que la versión aparezca con la etiqueta más reciente --> en el lienzo de la canalización.
1. Coloque el puntero en la parte superior del lienzo y, a continuación, haga clic en Historial de versiones.
2. Para ver las acciones disponibles, haga clic en los tres puntos horizontales de la versión que desee y seleccione Establecer como más reciente.
  
  Nota: Solo aparecen las versiones publicadas con la acción Establecer como más reciente.
3. Para confirmar la selección de la versión, haga clic en Establecer como más reciente.
4. Para salir del Historial de versiones y volver al lienzo del editor de scripts, haga clic en la flecha hacia atrás.
Para guardar el script, haga clic en Guardar.
Si desea exportar el script como un archivo YAML para utilizarlo en otra instancia de Code Stream, haga clic en Acciones > Exportar en la tarjeta de integración personalizada y seleccione las versiones que desea exportar.
En la canalización, configure el área de trabajo.
En este ejemplo, se utiliza un área de trabajo de Docker.
1. Haga clic en la pestaña Área de trabajo.
2. Seleccione el host de Docker y la dirección URL de la imagen de Builder.
Agregue una tarea personalizada a la canalización y configúrela.
1. Haga clic en la pestaña Modelo.
2. Agregue una tarea, seleccione el tipo como Personalizado e introduzca un nombre pertinente.
3. Seleccione el script de integración personalizado y la versión. La versión del script que se haya establecido como la más reciente aparecerá con la etiqueta más reciente --> delante de su nombre.
4. Para mostrar un mensaje personalizado en Slack, introduce el texto del mensaje.
  Cualquier texto que introduzca reemplaza el valor defaultValue en el script de integración personalizado.
Guarde y habilite la canalización.
1. Haga clic en Guardar.
2. En la tarjeta de canalización, haga clic en Acciones > Habilitar.
Ejecute la canalización.
1. Haga clic en Ejecutar.
2. Observe la ejecución de la canalización.
3. Confirme que la salida incluya el código de estado, el código de respuesta, el estado y la salida declarada previstos.
  Ha definido statusCode como una propiedad de salida. Por ejemplo, si statusCode tiene un valor de 200 puede indicar una publicación de Slack correcta, y responseCode con un valor de 0 puede indicar que el script se ha completado correctamente sin errores.
4. Para confirmar la salida en los registros de ejecución, haga clic en Ejecuciones, haga clic en el vínculo a la canalización, haga clic en la tarea y observe los datos registrados. Por ejemplo:
Si se produce un error, solucione el problema y vuelva a ejecutar la canalización.
Por ejemplo, si falta un archivo o un módulo en la imagen base, debe crear otra imagen base que incluya el archivo que falta. A continuación, proporcione el archivo de Docker e inserte la imagen a través de la canalización.

Resultados

Enhorabuena. Se creó un script de integración personalizada que conecta Code Stream con la instancia de Slack y publica un mensaje en un canal de Slack.

Qué hacer a continuación

Siga creando integraciones personalizadas para permitir el uso de tareas personalizadas en las canalizaciones, de modo que pueda ampliar la capacidad de Code Stream en la automatización del ciclo de vida de publicación de software.