Spécification de commande

La spécification de commande contient les commandes et les paramètres de l'interpréteur de commandes exécutés lors d'un déploiement. La spécification de commande est écrite en YAML. Le contenu du fichier peut être inséré ou la spécification peut être stockée dans un référentiel du registre d'artefacts.

Pour exécuter un fichier binaire qui n'est pas préinstallé par Oracle, vous devez le télécharger directement dans le dossier racine ou le télécharger dans le dossier de l'espace de travail, puis le déplacer dans le dossier racine avant de l'exécuter.

La spécification de commande se compose des sections suivantes :

Configuration des variables d'environnement.
Artefacts d'entrée.
Étapes à exécuter dans l'ordre.

Syntaxe de spécification de commande

version: 0.1
component: command
timeoutInSeconds: 10000
shell: bash
failImmediatelyOnError: true
env:
  variables:
    key: "value"
    key: "value"
  vaultVariables:
    key: "secret-id"
 
inputArtifacts:
  - name: artifact-name
    type: GENERIC_ARTIFACT
    artifactId: "artifact-ocid"
    registryId: OCID of the Artifact Registry
    path: path of the artifact in the Registry
    version: version of the artifact
    location: target-location
  - name: artifact-name
    type: URL
    url: downloadable link
    location: target-location
 
steps:
  - type: Command
    name: step-name
    shell: shellType
    timeoutInSeconds: 650
    failImmediatelyOnError: true
    command: command
    onFailure:
      - type: Command
        command: |
          command
          command
        timeoutInSeconds: 400
 
  - type: Command
    name: step-name
    command: |
      command
      command
      command
    onFailure:
      - type: Command
        command: |
          command
        timeoutInSeconds: 400

Paramètres de spécification de commande

Voici la liste des paramètres de la spécification de commande et leur description :


Paramètre	Description
`version`	Obligatoire. Indique la version de la spécification de commande. Une version manquante ou non valide entraîne l'échec de l'étape d'interpréteur de commandes. La valeur prise en charge est `0.1`.
`component`	Obligatoire. Indique un composant spécifique dans DevOps. Une valeur manquante ou non valide entraîne l'échec de l'étape. La valeur prise en charge est `command`.
`timeoutInSeconds`	Facultatif. Indique la temporisation pour l'ensemble du fichier de spécification de commande. Chaque étape peut également avoir sa propre valeur de temporisation. Si aucune valeur n'est spécifiée, la valeur par défaut, 8 heures, est utilisée. La valeur maximale autorisée est 8 heures.
`shell`	Facultatif. Indique l'interpréteur de commandes à utiliser au niveau global de la spécification de commande. Cette valeur peut éventuellement être remplacée au niveau de l'étape. Les valeurs autorisées sont `/bin/sh` et `bash`. Si aucune valeur n'est spécifiée, la valeur par défaut, `bash`, est utilisée.
`failImmediatelyOnError`	Facultatif. Indique si le déploiement doit continuer si l'une des commandes de l'étape échoue avec une valeur de sortie différente de zéro. Si vous ne spécifiez pas de valeur, la valeur par défaut est `false` et l'étape continue. Les valeurs autorisées sont `true` et `false`. OCI recommande de régler la valeur de cet attribut à `true`.
`env`	Facultatif. Vous pouvez définir des variables personnalisées. Trois types de variable sont pris en charge : env/variables : Facultatif. La clé doit être une chaîne conforme aux variables d'environnement POSIX. La valeur peut être une chaîne quelconque. La portée de cette variable est l'exécution du fichier de spécification de commande. Toute modification de la valeur de la variable est visible dans les étapes suivantes. Ces variables sont disponibles en tant que variables d'environnement pour toutes les étapes du fichier de spécification de commande. Si la valeur de la variable contient un caractère de saut de ligne (\n) ou de retour de chariot (\r), il est remplacé par un espace dans les étapes suivantes. env/vaultVariables : Facultatif. La clé doit être une chaîne conforme aux variables d'environnement POSIX. La valeur doit être un OCID de clé secrète de la chambre forte. La chambre forte et le pipeline doivent se trouver dans la même location. La location doit disposer d'une politique permettant aux ressources du pipeline de déploiement d'accéder à la clé secrète. La portée de cette variable est l'exécution du fichier de spécification de commande et elle est disponible pour toutes les étapes du fichier. La valeur de ces variables est extraite de la chambre forte et mise à disposition en tant que variable d'environnement pour toutes les étapes du fichier de spécification de commande. env/exportedVariables : Facultatif. Vous pouvez déclarer une liste de variables. Le nom de la variable doit être une chaîne conforme aux variables d'environnement POSIX. La valeur peut être affectée dans une étape quelconque du fichier de spécification de commande. La portée de cette variable est le pipeline de déploiement. Toute variable exportée est disponible uniquement dans les étapes d'interpréteur de commandes suivantes du même pipeline.
`inputArtifacts`	Facultatif. Sert à définir une liste des artefacts d'entrée requis pour exécuter l'étape d'interpréteur de commandes courante. Prend en charge les artefacts génériques du registre d'artefacts. Les paramètres sont les suivants : *inputArtifacts//url : Facultatif. L'URL HTTP téléchargeable externe de l'artefact d'entrée doit être fournie. L'URL doit être accessible au public. L'authentification/autorisation n'est pas prise en charge actuellement. inputArtifacts//name* : Obligatoire. Ce nom est utilisé pour référencer les artefacts dans l'exécution de commande. *inputArtifacts//location : Obligatoire. Chemin de destination du système de fichiers local où l'artefact d'entrée doit être téléchargé. Le chemin peut être spécifié de l'une des façons suivantes : `${OCI_PRIMARY_SOURCE_DIR}/pom.xml` `${OCI_WORKSPACE_DIR}/[source-name]/pom.xml` `/workspace/[source-name]/pom.xml` Chemin relatif à partir du répertoire de base du projet, `pom.xml` Quelle que soit la valeur utilisée, l'artefact d'entrée est téléchargé dans le répertoire de base source principal avec un nom de fichier, `pom.xml`. L'emplacement ne prend pas en charge `exportedVariables` ni les variables de pipeline. inputArtifacts//type* : Obligatoire. Type de l'artefact d'entrée qui doit être téléchargé. Les valeurs autorisées sont `URL` et `GENERIC_ARTIFACT`. *inputArtifacts//artifactld : Obligatoire. OCID de l'artefact. Si vous avez fourni l'OCID, le pipeline de déploiement ignore registryId, le chemin et la version. inputArtifacts//registryld* : obligatoire. OCID du registre d'artefacts. *inputArtifacts//path : Obligatoire. Chemin de destination de l'artefact. inputArtifacts//version* : Obligatoire. Version de l'artefact. Note : Pour le type d'artefact d'entrée `GENERIC_ARTIFACT`, vous pouvez fournir comme paramètre obligatoire l'OCID de l'artefact ou une combinaison d'ID registre, chemin et version d'artefact.
`steps`	Obligatoire. Cette section définit une liste d'étapes à exécuter. *steps//type : obligatoire. Indique le type d'étape. Prise en charge des valeurs suivantes : `Command` steps//name* : Facultatif. Nom convivial de l'étape.

Types d'étape

Commande


Nom de l'attribut	Description
`command`	Les commandes à une seule ligne et à plusieurs lignes sont prises en charge. Toutes les commandes spécifiées dans une étape sont exécutées dans la même session de l'interpréteur de commandes. Selon la valeur de `steps/*/shell`, il peut s'agir de commandes shell ou bash. L'interruption immédiate n'est pas activée. Pour que l'étape réussisse, la sortie de la dernière commande d'une étape est prise en compte. Si le code de sortie de la dernière commande est 0, l'étape est considérée comme réussie.
`timeoutInSeconds` (Facultatif)	Indique la temporisation de l'étape. Si elle n'est pas indiquée, la valeur est héritée du paramètre `timeoutInSeconds` global. La valeur maximale autorisée est 8 heures.
`shell` (Facultatif)	Indique le type d'interpréteur de commandes de l'étape courante. Si elle n'est pas spécifiée, la valeur est héritée du paramètre `shell` global. Les valeurs autorisées sont `/bin/sh` et `shell`.
`onFailure` (Facultatif)	Liste d'étapes à exécuter en cas d'échec pour quitter correctement l'étape d'interpéteur de commandes. Elles sont exécutées si l'étape correspondante échoue, et sont suivies de la sortie de la spécification de commande. La gestion de l'échec n'a aucune incidence sur le statut de l'étape d'interpréteur de commandes. Si l'une des étapes échoue, l'étape d'interpréteur de commandes garde le statut `failed`, mais elle est traitée par le bloc `onFailure`.
`failImmediatelyOnError` (Facultatif)	Indique si le déploiement doit continuer si l'une des commandes de l'étape échoue avec une valeur de sortie différente de zéro. Si vous ne spécifiez pas de valeur, la valeur par défaut est `false` et l'étape continue. Les valeurs autorisées sont `true` et `false`. OCI recommande de régler la valeur de cet attribut à `true`. La valeur de l'attribut `failImmediatelyOnError` définie sous `steps` a priorité sur la valeur du même attribut définie en dehors de `steps`.

Variables de système prédéfinies

DevOps fournit un jeu de variables de système prédéfinies avec des valeurs par défaut que vous pouvez utiliser dans la spécification de commande.


Variable	Description
`OCI_DEPLOYMENT_ID`	OCID du déploiement courant.
`OCI_PIPELINE_ID`	OCID du pipeline de déploiement courant.
`OCI_RESOURCE_PRINCIPAL_RPST`	Jeton du principal de ressource.
`OCI_RESOURCE_PRINCIPAL_VERSION`	Version du principal de ressource.
`OCI_CLI_AUTH`	Authentification CLI OCI préconfigurée pour l'utilisation du principal de ressource.
`OCI_RESOURCE_PRINCIPAL_REGION`	Région du principal de ressource.
`OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM`	Chemin de la clé privée du principal de ressource.

Exemple de spécification de commande

Exemple : Créer un espace de noms OKE.