Documentation Oracle Cloud Infrastructure

Fichier de configuration de déploiement

Le fichier de configuration de déploiement définit les artefacts à télécharger vers l'instance et l'emplacement vers lequel les artefacts doivent être copiés. Le fichier de configuration indique également l'ordre des commandes pour le déploiement.

Le fichier de configuration est écrit en langage YAML. Il peut être défini de façon incorporée ou fourni en tant que référence d'artefact générique lors du déploiement de groupe d'instances.

Les administrateurs DevOps peuvent utiliser le fichier de configuration de déploiement pour effectuer les actions suivantes :

  • Indiquer les packages d'application et leur emplacement de stockage dans l'instance de calcul cible.
  • Indiquer les étapes requises pour le déploiement d'une application.
  • Indiquer les variables d'environnement intégrées ou définies par l'utilisateur requises pour le déploiement.

Structure du fichier de configuration de déploiement

Voici la structure de base du fichier de configuration de déploiement :

{
version:     
component:   
env: 
    variables:        
timeoutInSeconds:  
files:  
  - source:
    destination:                              
steps:                              
  - stepType: Command 
    name:
    command:
    runAs:
    timeoutInSeconds:
  - stepType: Command 
}

Voici les paramètres de configuration de déploiement et leurs détails :

Paramètre Description
version Numéro de version du fichier de spécification. La valeur doit être 1.0.
component Valeur de composant. La seule valeur prise en charge est deployment.
shell Facultatif. Indique le shell à utiliser au niveau global de la spécification de déploiement. La valeur peut être remplacée au niveau d'une étape. Les valeurs autorisées sont /bin/sh et bash. Si aucune valeur n'est indiquée, la valeur par défaut bash est utilisée.
env: variables

Variables d'environnement définies par l'utilisateur disponibles pour les fichiers exécutables ou la commande bash qui sont exécutés dans le cadre du déploiement.

Exemples : key1: static-value, key2: ${PASSED_FROM_PIPELINE}

Les variables intégrées peuvent également être utilisées. Pour éviter tout conflit, le préfixe OCI_DEVOPS est ajouté à toutes les variables intégrées.

Les variables intégrées sont les suivantes :

  • OCI_DEVOPS_PIPELINE_ID
  • OCI_DEVOPS_STAGE_ID
  • OCI_DEVOPS_DEPLOYMENT_ID

env est un paramètre facultatif.
env: vaultVariables Facultatif. La clé doit être une chaîne et conforme à la variable d'envionnement POSIX. La valeur doit être l'identificateur Oracle Cloud (OCID) de la clé secrète du coffre. Le coffre et le pipeline de déploiement doivent être dans la même location. Cette dernière doit disposer d'une stratégie appropriée pour autoriser les ressources de pipeline de déploiement à accéder à la clé secrète.

La portée de cette variable est l'exécution du fichier de spécification de déploiement et est disponible pour toutes les étapes du fichier. Les valeurs de ces variables sont extraites du coffre et sont mises à disposition en tant que variables d'environnement pour toutes les étapes du fichier de spécification de déploiement.
files

Indique les artefacts définis dans le pipeline de déploiement à copier et l'emplacement de l'instance de calcul cible vers lequel les copier. Ce paramètre est facultatif.

Par défaut, l'utilisateur configuré, ocarun, détient le répertoire indiqué, doit disposer de droits d'accès d'écriture et d'exécution (chmod u+wrx). Si le dossier de destination n'existe pas, le déploiement DevOps le crée. Pour ce faire, ocarun (ou l'utilisateur configuré) doit disposer de droits d'accès d'écriture et d'exécution sur le répertoire parent du répertoire de destination indiqué.

Par exemple, si vous affectez le répertoire de destination dans le fichier de configuration de déploiement en tant que /var/services/accountService, vous devez fournir des droits d'accès en écriture et d'exécution à l'utilisateur configuré pour /var/services et un droit d'exécution pour /var.
files: source

Indique l'emplacement source des artefacts. La source peut faire référence à un fichier ou à un dossier. Si la source est un fichier, ce fichier est copié dans le dossier défini dans la destination. Si s'agit d'un dossier, tout le contenu de ce dossier est copié dans la destination. La source utilise un chemin relatif, dont la racine est le dossier racine des artefacts.

Indiquez le nom complet de l'artefact, y compris l'extension de type de fichier. Par exemple, si le fichier dans la source est test.sh, le chemin d'artefact doit être test.sh ou folder-name/test.sh si le fichier se trouve dans un dossier.

Par exemple, si l'artefact général indique un fichier unique, run.sh, ce fichier est téléchargé vers le dossier racine (/) dans la source. Si l'artefact général est une archive, par exemple app_pkg.zip, la racine du contenu de l'archive est le dossier racine.
files: destination Indique le dossier cible dans lequel le fichier ou le dossier source doit être copié. OCI DevOps recommande de considérer la destination comme un répertoire de préparation pour le code de production car le contenu du répertoire de destination est écrasé à chaque déploiement.

Dans l'exemple de spécification de déploiement suivant, deux répertoires sont mentionnés. Le répertoire de destination est /var/ocarun_staging/app1_staging_folder et le répertoire de production est var/ocarun_prod/main_app.
steps Indique la liste des étapes exécutées de façon séquentielle lors du déploiement. Chaque étape est exécutée en tant que processus distinct sur l'instance. Toutes les variables d'environnement intégrées et définies par l'utilisateur qui sont indiquées au processus.
steps: name Nom de l'étape défini par l'utilisateur.
steps: command

Commande shell ou fichier exécutable shell.

Si le paramètre files est indiqué dans le fichier de configuration, le chemin d'emplacement du fichier exécutable est un chemin absolu, par exemple /genericArtifactDemo/start.sh. Si le paramètre files n'est pas indiqué, le chemin relatif est utilisé pour spécifier l'emplacement du fichier exécutable. Le chemin relatif fait référence au dossier de travail du déploiement. Les artefacts sont téléchargés et extraits dans le dossier de travail en cours du déploiement.

Les commandes sur une seule ligne et sur plusieurs lignes sont prises en charge. Toutes les commandes indiquées dans une étape sont exécutées dans la même session de shell. En fonction de la valeur steps/*/shell, les commandes peuvent être shell ou bash. L'échec rapide n'est pas activé. La sortie de la dernière commande d'une étape est prise en compte dans la réussite de l'étape. Si le code de sortie de la dernière commande est 0, l'étape est considérée comme réussie. Une commande sur plusieurs lignes fonctionne comme un script bash. Si vous voulez activer l'échec rapide pour la commande sur plusieurs lignes, indiquez cette dernière avec set -e \n <suite des commandes> (pour le script bash) afin de vous assurer que le script se ferme lors de l'échec de la première de commande.

Par exemple, si vous indiquez la commande wrongcommand \n /usr/bin/sudo -n -u root -E /home/opc/scripts/stop.sh \n echo \"Done\" sous la forme set -e \n wrongcommand \n /usr/bin/sudo -n -u root -E /home/opc/scripts/stop.sh \n echo \"Done\", le script se ferme sur wrongcommand.
steps: runAs Exécute l'étape sous l'identité de l'utilisateur indiqué. Par défaut, toutes les étapes sont exécutées en tant qu'utilisateur ocarun.
steps: timeoutInSeconds Indique le délai d'expiration pour la réalisation d'une étape.
steps: shell Facultatif. Indique le type de shell de l'étape en cours. Si aucune valeur n'est indiquée, la valeur est héritée du paramètre shell global. Les valeurs autorisées sont /bin/sh et shell.
steps: onFailure Liste des étapes à exécuter en cas d'échec pour sortir progressivement de la phase de déploiement. Les commandes sous la section onFailure sont exécutées uniquement en cas d'échec de l'étape correspondante. La spécification de déploiement se ferme après l'exécution. La gestion de l'échec n'affecte pas le statut de la phase de déploiement. Si l'une des étapes échoue, le statut de la phase de déploiement continue d'indiquer un échec.

Voici un exemple de fichier de configuration de déploiement : 

version: 1.0
component: deployment
runAs: ocarun
env: 
  variables: 
    version: ${appVersion}
  vaultVariables:
    SECRET_ID: "OCID of the secret in the vault"    
files: 
  - source: /
    destination: /var/ocarun_staging/app1_staging_folder
steps: 
  - stepType: Command
    name: Validate Variables
    command: echo "Version = ${version}:  Secret = ${SECRET_ID}"
    timeoutInSeconds: 60
  - stepType: Command
    name: Stop currently-running application
    command: cd /var/ocarun_prod/main_app; ./stop.sh
    timeoutInSeconds: 600
  - stepType: Command
    name: Clean old version of source code in prod directory
    command: echo "Perform suitable cleanup"
    timeoutInSeconds: 600
  - stepType: Command
    name: Copy new version of source code from staging directory to prod directory
    command: cp -R /var/ocarun_staging/app1_staging_folder/main_app /var/ocarun_prod/
    timeoutInSeconds: 600
  - stepType: Command
    name: Install application
    command: cd /var/ocarun_prod/main_app; ./install.sh
    timeoutInSeconds: 600
  - stepType: Command
    name: Run application
    command: cd /var/ocarun_prod/main_app; ./start.sh
    timeoutInSeconds: 600

Exemple de fichier cloud-init pour la configuration des deux répertoires (préparation et production) : 

#cloud-config
users:
  - default
  - name: ocarun
    sudo: ALL=(ALL) NOPASSWD:ALL

# Create two directories, one for staging and one for production.
runcmd:
  - [mkdir, -p, /var/ocarun_staging]
  - [mkdir, -p, /var/ocarun_prod]
  - [chown, ocarun, /var/ocarun_staging]
  - [chown, ocarun, /var/ocarun_prod]

Exemple pour comprendre plusieurs entrées pour la source et la destination :

version: 1.0
component: deployment
runAs: root
shell: bash
env:
  variables:
    version: ${appVersion}
  vaultVariables:
    docker_registry_password : <secret-ocid>  
files:
  # This section is to define how the files in the artifact is put on the compute instance.
  # Multiple entires are supported using a separate source destination section for every entry.
  - source: /
    destination: /genericArtifactDemo
  - source: /tmp/file1
    destination: /var/applicationPath/someDir1
  - source: /tmp/file2
    destination: /var/applicationPath/someDir2  
steps:
  # This section is to define the scripts that each step runs on the instance after file copy.
  - stepType: Command
    name: Install Apache Web Server
    command: /genericArtifactDemo/install_dependencies.sh
    runAs: root
    timeoutInSeconds: 600
  - stepType: Command
    name: Stop Web Server
    command: /genericArtifactDemo/stop.sh
    runAs: root
    timeoutInSeconds: 60
  - stepType: Command
    name: Install New Version of Software
    command: /genericArtifactDemo/install.sh
    runAs: root
    timeoutInSeconds: 60
  - stepType: Command
    name: Start Web Server
    command: /genericArtifactDemo/start.sh
    runAs: root
    timeoutInSeconds: 60
  - stepType: Command
    name: stop and install
    command: |
      /scripts/stop.sh
      echo "Done stop.sh.."
      /scripts/install_dependencies.sh
      echo "Done install_dependencies.sh.."
      /scripts/install.sh
      echo "Done install.sh.."
    timeoutInSeconds: 1200
    runAs: root
    shell: /bin/sh
    onFailure:
       - stepType: Command
         command: /scripts/recovery_steps.sh
         name:"OnFailure step"
         timeoutInSeconds: 1200

Exécution du fichier de configuration de déploiement

Le service DevOps utilise l'agent RunCommand pour exécuter les commandes indiquées dans le fichier de configuration sur l'instance de calcul cible. Pour plus d'informations sur l'activation du module d'extension RunCommand, reportez-vous à Prérequis dans Déploiement vers un groupe d'instances. Si le fichier de configuration de déploiement contient des espaces réservés, ils sont remplacés par les valeurs définies dans la liste des paramètres du déploiement. Reportez-vous à Configuration des paramètres.