Intégration d'outils de génération, de test et de déploiement propres avec Code Stream

En tant qu'administrateur ou développeur DevOps, vous pouvez créer des scripts personnalisés qui étendent la capacité de Code Stream.

Avec votre script, vous pouvez intégrer Code Stream à vos propres outils et API d'intégration continue (CI) et de prestation continue (CD) qui génèrent, testent et déploient vos applications. Les scripts personnalisés sont particulièrement utiles si vous n'exposez pas publiquement vos API d'application.

Votre script personnalisé peut effectuer presque toutes les opérations nécessaires à l'intégration de vos outils de génération, de test et de déploiement à Code Stream. Par exemple, votre script peut utiliser l'espace de travail de votre pipeline pour prendre en charge les tâches d'intégration continue qui génèrent et testent votre application, ainsi que les tâches de livraison continue qui la déploient. Il peut envoyer un message à Slack lorsqu'un pipeline se termine, et bien plus encore.

L'espace de travail de pipeline Code Stream prend en charge Docker et Kubernetes pour les tâches d'intégration continue et les tâches personnalisées.

Pour plus d'informations sur la configuration de l'espace de travail, consultez Configuration de l'espace de travail de pipeline.

Vous écrivez votre script personnalisé dans l'un des langages pris en charge. Dans le script, vous incluez votre logique métier, et définissez des entrées et des sorties. Les types de sorties peuvent inclure un nombre, une chaîne, un texte et un mot de passe. Vous pouvez créer plusieurs versions d'un script personnalisé avec une logique d'activité, une entrée et une sortie différentes.

Les scripts que vous créez résident dans votre instance de Code Stream. Vous pouvez importer du code YAML pour créer une intégration personnalisée ou exporter votre script sous la forme d'un fichier YAML à utiliser dans une autre instance de Code Stream.

Votre pipeline exécute une version publiée de votre script dans une tâche personnalisée. Si vous disposez de plusieurs versions publiées, vous pouvez définir l'une d'elles comme la plus récente afin qu'elle s'affiche avec l'étiquette dernière --> lorsque vous sélectionnez la tâche personnalisée.

Lorsqu'un pipeline utilise une intégration personnalisée et que vous tentez de supprimer cette intégration, un message d'erreur s'affiche indiquant que vous ne pouvez pas la supprimer.

La suppression d'une intégration personnalisée supprime toutes les versions de votre script personnalisé. Si vous disposez d'un pipeline existant incluant une tâche personnalisée qui utilise une version du script, ce pipeline va échouer. Pour vous assurer que les pipelines existants n'échouent pas, vous pouvez déconseiller et retirer la version de votre script que vous ne souhaitez plus utiliser. Si aucun pipeline n'utilise cette version, vous pouvez la supprimer.

Tableau 1. Actions postérieures à la rédaction de votre script personnalisé
Actions…	Plus d'informations sur cette action…
Ajout d'une tâche personnalisée à votre pipeline.	La tâche personnalisée : s'exécute sur le même conteneur que les autres tâches CI de votre pipeline. inclut les variables d'entrée et de sortie que votre script remplit avant l'exécution de la tâche personnalisée par le pipeline. prend en charge plusieurs types de données et différents types de métadonnées que vous définissez comme entrées et sorties dans votre script.
Sélection de votre script dans la tâche personnalisée.	Vous déclarez les propriétés d'entrée et de sortie dans le script.
Enregistrement de votre pipeline, avant activation et exécution.	Lorsque le pipeline s'exécute, la tâche personnalisée appelle la version du script spécifié et y exécute la logique métier, ce qui intègre votre outil de génération, de test et de déploiement à Code Stream.
Une fois votre pipeline exécuté, observation des exécutions.	Vérifiez que le pipeline a fourni les résultats attendus.

Lorsque vous utilisez une tâche personnalisée qui appelle une version d'intégration personnalisée, vous pouvez inclure des variables d'environnement personnalisées sous forme de paires nom-valeur dans l'onglet Espace de travail du pipeline. Lorsque l'image de générateur crée le conteneur d'espace de travail qui exécute la tâche CI et déploie votre image, Code Stream transmet les variables d'environnement à ce conteneur.

Par exemple, lorsque votre instance de Code Stream nécessite un proxy Web et que vous utilisez un hôte Docker pour créer un conteneur pour une intégration personnalisée, Code Stream exécute le pipeline et transmet les variables de configuration de proxy Web à ce conteneur.

Tableau 2. Exemple de paires nom-valeur de variable d'environnement
Nom	Valeur
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

Les paires nom-valeur s'affichent dans l'interface utilisateur de la manière suivante :

Code Stream transmet les variables d'environnement au conteneur créé par l'image du générateur.

Cet exemple crée une intégration personnalisée qui connecte Code Stream à votre instance Slack et publie un message sur un canal Slack.

Conditions préalables

Pour écrire votre script personnalisé, vérifiez que vous disposez de l'un des langages suivants : Python 2, Python 3, Node.js ; ou de l'un des langages Shell suivants : bash, sh ou zsh.
Générez une image de conteneur à l'aide du composant d'exécution Node.js ou Python installé.

Procédure

Créez l'intégration personnalisée.

Cliquez sur Intégrations personnalisées > Nouveau et entrez un nom pertinent.
Sélectionnez l'environnement d'exécution préféré.
Cliquez sur Créer.
Votre script s'ouvre et affiche le code, qui inclut l'environnement d'exécution requis. Par exemple, runtime: "nodejs". Le script doit inclure le composant d'exécution que l'image du générateur utilise, afin que la tâche personnalisée que vous ajoutez à votre pipeline aboutisse lorsque le pipeline s'exécute. Sinon, la tâche personnalisée échoue.

Les principaux aspects de votre intégration personnalisée YAML incluent l'exécution, le code, les propriétés d'entrée et les propriétés de sortie. Cette procédure explique différents types et la syntaxe.


Clés YAML d'intégration personnalisée	Description
runtime	Environnement d'exécution des tâches où Code Stream exécute le code, qui peut être l'une de ces chaînes insensibles à la casse : nodejs python2 python3 shell Si rien n'est indiqué, shell est la valeur par défaut supposée.
code	Logique métier personnalisée à exécuter dans le cadre de la tâche personnalisée.
inputProperties	Tableau de propriétés d'entrée à capturer dans le cadre de la configuration de la tâche personnalisée. Ces propriétés sont normalement utilisées dans le code.
outputProperties	Tableau de propriétés de sortie que vous pouvez exporter à partir de la tâche personnalisée à propager au pipeline.

Déclarez les propriétés d'entrée dans votre script en utilisant les types de données et les métadonnées disponibles.

Les propriétés d'entrée sont transmises sous forme de contexte à votre script dans la section code: du fichier YAML.


Touches d'entrée YAML de tâche personnalisée	Description	Requis
`type`	Types d'entrée à rendre : `text` `textarea` `number` `checkbox` `password` `select`	Oui
`name`	Nom ou chaîne de l'entrée de la tâche personnalisée, qui est injectée dans le code YAML d'intégration personnalisée. Doit être unique pour chaque propriété d'entrée définie pour une intégration personnalisée.	Oui
`title`	Libellé de chaîne de texte de la propriété d'entrée pour la tâche personnalisée sur le canevas du modèle de pipeline. S'il est laissé vide, `name` est utilisé par défaut.	Non
`required`	Détermine si un utilisateur doit entrer la propriété d'entrée lorsqu'il configure la tâche personnalisée. Définissez sur true ou false. Lorsque la valeur est true, si un utilisateur ne fournit pas de valeur lorsqu'il configure la tâche personnalisée sur le canevas du pipeline, l'état de la tâche reste non configuré.	Non
`placeHolder`	Texte par défaut pour la zone d'entrée de la propriété d'entrée lorsqu'aucune valeur n'est présente. Correspond à l'attribut html placeholder. Uniquement pris en charge pour certains types de propriétés d'entrée.	Non
`defaultValue`	Valeur par défaut qui renseigne la zone d'entrée de la propriété d'entrée lorsque la tâche personnalisée s'affiche sur la page du modèle de pipeline.	Non
`bindable`	Détermine si la propriété d'entrée accepte les variables de symbole dollar lors de la modélisation de la tâche personnalisée sur le canevas du pipeline. Ajoute l'indicateur $ en regard du titre. Uniquement pris en charge pour certains types de propriétés d'entrée.	Non
`labelMessage`	Chaîne qui agit comme une info-bulle d'aide pour les utilisateurs. Ajoute une icône d'info-bulle i en regard du titre d'entrée.	Non
`enum`	Prend un tableau de valeurs qui affiche les options de sélection de propriétés d'entrée. Uniquement pris en charge pour certains types de propriétés d'entrée. Lorsqu'un utilisateur sélectionne une option et l'enregistre pour la tâche personnalisée, la valeur de inputProperty correspond à cette valeur et figure dans la modélisation de tâche personnalisée. Par exemple, la valeur 2015. 2015 2016 2017 2018 2019 2020	Non
`options`	Prend un tableau d'objets en utilisant optionKey et optionValue. optionKey. Valeur propagée à la section code de la tâche. optionValue. Chaîne qui affiche l'option dans l'interface utilisateur. Uniquement pris en charge pour certains types de propriétés d'entrée. Options : optionKey : key1. Lorsque cette option est sélectionnée et enregistrée pour la tâche personnalisée, la valeur de inputProperty correspond à key1 dans la section code. optionValue : « Label for 1 ». Valeur d'affichage de key1 dans l'interface utilisateur et ne figure nulle part ailleurs pour la tâche personnalisée. optionKey : key2 optionValue : « Label for 2 » optionKey : key3 optionValue : « Label for 3 »	Non
`minimum`	Prend un nombre qui agit comme la valeur minimale qui est valide pour cette propriété d'entrée. Uniquement pris en charge pour la propriété d'entrée de type nombre.	Non
`maximum`	Prend un nombre qui agit comme la valeur maximale valide pour cette propriété d'entrée. Uniquement pris en charge pour la propriété d'entrée de type nombre.	Non

Tableau 3. Types de données et métadonnées pris en charge pour les scripts personnalisés
Types de données pris en charge	Métadonnées prises en charge pour l'entrée
Chaîne Texte Liste : sous forme de liste de n'importe quel type Carte : sous la forme map[chaîne]any Sécurisé : rendu sous forme de zone de texte pour mot de passe, chiffrée lorsque vous enregistrez la tâche personnalisée Nombre Booléen : s'affiche sous forme de zones de texte URL : identique au type Chaîne, avec validation supplémentaire Sélection, case d'option	type : Une chaîne \| Texte... valeur par défaut : valeur par défaut options : liste ou carte d'options à utiliser avec la sélection ou la case d'option min. : valeur ou taille minimale max. : valeur ou taille maximale titre : nom détaillé de la zone de texte espace réservé : espace réservé dans l'interface utilisateur description : devient une info-bulle

Par exemple :

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

Déclarez les propriétés de sortie dans votre script.

Le script capture les propriétés de sortie à partir de la section de la logique métier code: de votre script, dans laquelle vous déclarez le contexte de la sortie.

Lorsque le pipeline s'exécute, vous pouvez entrer le code de réponse correspondant au résultat de la tâche. Par exemple, 200.

Clés que Code Stream prend en charge pour chaque outputProperty.


key	Description
type	Inclut actuellement une seule valeur de `label`.
name	Clé que le bloc de code de l'intégration personnalisée YAML émet.
title	Étiquette dans l'interface utilisateur qui affiche outputProperty.

Par exemple :

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

Pour interagir avec l'entrée et la sortie de votre script personnalisé, obtenez une propriété d'entrée ou définissez une propriété de sortie en utilisant context.

Pour une propriété d'entrée : (context.getInput("key"))

Pour une propriété de sortie : (context.setOutput("key", "value"))

Pour Node.js :

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

Pour Python :

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

Pour Shell :

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

Dans la section code:, déclarez l'ensemble de la logique métier pour votre intégration personnalisée.

Par exemple, avec l'environnement d'exécution 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();

Avant de procéder au contrôle de la version et à la publication de votre script d'intégration personnalisé, téléchargez le fichier de contexte pour Python ou Node.js, et testez la logique d'activité que vous avez incluse dans votre script.
1. Placez le pointeur en haut du canevas, puis cliquez sur le bouton de fichier de contexte. Par exemple, si votre script est écrit dans le langage de programmation Python, cliquez sur CONTEXT.PY.
2. Modifiez le fichier et enregistrez-le.
3. Sur votre système de développement, exécutez et testez votre script personnalisé à l'aide du fichier de contexte.
Appliquez une version à votre script d'intégration personnalisé.
1. Cliquez sur Version.
2. Entrez les informations relatives à la version.
3. Cliquez sur Version pour pouvoir sélectionner le script dans votre tâche personnalisée.
4. Pour créer la version, cliquez sur Créer.
(Facultatif) Vous pouvez définir n'importe quelle version publiée d'un script d'intégration personnalisée comme étant la plus récente afin que la version s'affiche avec l'étiquette dernière --> sur le canevas du pipeline.
1. Placez le pointeur en haut du canevas, puis cliquez sur Historique des versions.
2. Pour afficher les actions disponibles, cliquez sur les points de suspension horizontaux de la version souhaitée et sélectionnez Définir comme la plus récente.
  
  Note : Seules les versions publiées s'affichent avec l'action Définir comme la plus récente.
3. Pour confirmer la sélection de la version, cliquez sur Définir comme la plus récente.
4. Pour quitter l'Historique des versions et revenir au canevas de l'éditeur de script, cliquez sur la flèche Précédent.
Pour enregistrer le script, cliquez sur Enregistrer.
Pour exporter votre script en tant que fichier YAML à utiliser dans une autre instance de Code Stream, cliquez sur Actions > Exporter sur la fiche d'intégration personnalisée et sélectionnez les versions à exporter.
Dans votre pipeline, configurez l'espace de travail.
Cet exemple utilise un espace de travail Docker.
1. Cliquez sur l'onglet Espace de travail.
2. Sélectionnez l'hôte Docker et l'URL de l'image du générateur.
Ajoutez une tâche personnalisée à votre pipeline et configurez-la.
1. Cliquez sur l'onglet Modèle.
2. Ajoutez une tâche, sélectionnez le type personnalisé et entrez un nom pertinent.
3. Sélectionnez votre script d'intégration personnalisé et sa version. Si une version du script a été définie comme la dernière version, cette version s'affiche avec l'étiquette dernière --> avant le nom de la version.
4. Pour afficher un message personnalisé dans Slack, entrez le texte du message.
  Tout texte que vous entrez remplace la defaultValue dans votre script d'intégration personnalisé.
Enregistrez et activez votre pipeline.
1. Cliquez sur Enregistrer.
2. Sur la fiche du pipeline, cliquez sur Actions > Activer.
Exécutez votre pipeline.
1. Cliquez sur Exécuter.
2. Observez l'exécution du pipeline.
3. Vérifiez que la sortie inclut le code d'état, le code de réponse, l'état et le résultat déclaré attendus.
  Vous avez défini statusCode comme propriété de sortie. Par exemple, un statusCode de 200 peut indiquer une publication Slack réussie et un responseCode de 0 peut indiquer la réussite sans erreur du script.
4. Pour vérifier le résultat dans les journaux d'exécution, cliquez sur Exécutions, sur le lien vers votre pipeline, puis sur la tâche, et examinez les données consignées. Par exemple :
Si une erreur se produit, résolvez le problème et réexécutez le pipeline.
Par exemple, si un fichier ou un module de l'image de base est manquant, vous devez créer une autre image de base qui inclut le fichier manquant. Ensuite, fournissez le fichier Docker et transmettez l'image via le pipeline.

Résultats

Félicitations ! Vous avez créé un script d'intégration personnalisé qui connecte Code Stream à votre instance de Slack et publie un message sur un canal Slack.

Que faire ensuite

Continuez à créer des intégrations personnalisées pour prendre en charge l'utilisation de tâches personnalisées dans vos pipelines, afin de pouvoir étendre la capacité de Code Stream dans l'automatisation du cycle de vie de votre version logicielle.