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

  1. Cree la integración personalizada.
    1. Haga clic en Integraciones personalizadas > Nuevo e introduzca un nombre pertinente.
    2. Seleccione el entorno de tiempo de ejecución que prefiera.
    3. 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.
  2. 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
    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.
    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
    
  3. 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
  4. 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
    
  5. 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();
    
  6. 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.
  7. 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.
      Cree una versión del script de integración personalizado y seleccione la versión en la tarea Personalizada de la canalización.
  8. (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.
      Después de crear una versión y publicar un script de integración personalizado, puede establecer la versión como más reciente para que un usuario sepa la versión actual que se debe seleccionar en la canalización.
    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.
  9. 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.
  10. 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.
      Cuando cree una integración personalizada, incluya el host, la URL de imagen del compilador y el registro de imágenes.
  11. 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.
      Cuando agregue una tarea personalizada a la canalización, seleccione una versión del script personalizado.
  12. Guarde y habilite la canalización.
    1. Haga clic en Guardar.
    2. En la tarjeta de canalización, haga clic en Acciones > Habilitar.
  13. 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:
      Después de que la canalización ejecuta la tarea personalizada, puede ver el resultado de la tarea para la integración personalizada en las ejecuciones de canalizaciones.
  14. 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.