Spécification de commande

La spécification de commande contient les paramètres et commandes de shell qui sont exécutés pendant un déploiement. La spécification de commande est écrite en langage YAML. Le contenu du fichier peut être défini de façon incorporée ou la spécification peut être stockée dans un référentiel Artifact Registry.

Pour exécuter un fichier binaire qui n'est pas préinstallé par Oracle, vous devez soit le télécharger directement dans le dossier racine, soit 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 comprend les sections suivantes :

Configuration des variables d'environnement.
Artefacts d'entrée.
Etapes à 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

Vous trouverez ci-dessous les paramètres de spécification de commande et leurs détails :


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 la phase de shell. La valeur prise en charge est `0.1`.
`component`	Obligatoire. Indique un composant particulier dans DevOps. Une valeur manquante ou non valide entraîne l'échec de la phase. La valeur prise en charge est `command`.
`timeoutInSeconds`	Facultatif. Indique le délai d'expiration pour l'ensemble du fichier de spécification de commande. Chaque étape peut également avoir sa propre valeur de délai d'expiration. Si aucune valeur n'est indiquée, la valeur par défaut est utilisée, soit 8 heures. La valeur maximale autorisée est 8 heures.
`shell`	Facultatif. Indique le shell à utiliser au niveau global de la spécification de commande. La valeur peut éventuellement ê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.
`failImmediatelyOnError`	Facultatif. Indique si le déploiement doit continuer lorsqu'une commande de l'étape échoue avec une valeur de sortie différente de zéro. Si aucune valeur n'est renseignée, la valeur par défaut est `false` et l'étape continue. Les valeurs autorisées sont `true` et `false`. OCI recommande de définir la valeur de cet attribut sur `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 et conforme à la variable d'envionnement POSIX. La valeur peut être n'importe quelle chaîne. La portée de cette variable est l'exécution du fichier de spécification de commande. Toute modification apportée à 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 nouvelle ligne (\n) ou de retour chariot (\r), celui-ci est remplacé par un espace dans les étapes suivantes. env/vaultVariables : facultatif. La clé doit être une chaîne et conforme à la variable d'envionnement POSIX. La valeur doit être un OCID de la clé secrète du coffre. Le coffre et le pipeline 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 commande 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 commande. env/exportedVariables : facultatif. Vous pouvez déclarer la liste des variables ici. Le nom de la variable doit être une chaîne et conforme à la variable d'envionnement POSIX. La valeur peut être affectée à n'importe quelle étape 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 phases de shell du même pipeline.
`inputArtifacts`	Facultatif. Utilisé afin de définir la liste des artefacts d'entrée requis pour exécuter la phase de shell en cours. Prend en charge les artefacts génériques provenant d'Artifact Registry. 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 publique. L'authentification/autorisation n'est pas prise en charge pour le moment. inputArtifacts//name :* obligatoire. Ce nom est utilisé pour référencer les artefacts lors de l'exécution de la commande. *inputArtifacts//location : obligatoire. Chemin de destination du système de fichiers local vers lequel l'artefact d'entrée doit être téléchargé. Le chemin peut être indiqué à l'aide de l'une des méthodes suivantes : `${OCI_PRIMARY_SOURCE_DIR}/pom.xml` `${OCI_WORKSPACE_DIR}/[source-name]/pom.xml` `/workspace/[source-name]/pom.xml` Chemin relatif à partir de l'accueil du projet, `pom.xml` Peu importe la valeur utilisée, l'artefact d'entrée est téléchargé vers le répertoire de base de la source principale avec le nom de fichier `pom.xml`. L'emplacement ne prend pas en charge `exportedVariables` ou les variables de pipeline. inputArtifacts//type* : obligatoire. Type de l'artefact d'entrée à télécharger. 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 les paramètres registryId, chemin et 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. Remarque: Pour le type d'artefact d'entrée `GENERIC_ARTIFACT`, vous pouvez fournir en tant que paramètre obligatoire l'OCID de l'artefact ou une combinaison de l'ID de registre, du chemin et de la version de l'artefact.
`steps`	Obligatoire. Cette section définit la liste des étapes à exécuter. *steps//type : obligatoire. Indique le type d'étape. Prend en charge les valeurs suivantes : `Command` steps//name :* facultatif. Nom convivial de l'étape.

Types d'étape

Commande :


Nom de l'attribut	Description
`command`	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.
`timeoutInSeconds` (facultatif)	Indique le délai d'expiration de l'étape. Si aucune valeur n'est fournie, la valeur est héritée du paramètre `timeoutInSeconds` global. La valeur maximale autorisée est 8 heures.
`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`.
`onFailure` (facultatif)	Liste des étapes à exécuter en cas d'échec pour sortir progressivement de la phase de shell. Si l'étape correspondante échoue, exécutez ces étapes. Après l'exécution, la spécification de commande se ferme. La gestion de l'échec n'a aucune incidence sur le statut de la phase de shell. En cas d'échec de l'une des étapes, le statut de la phase de shell reste `failed`, même si le bloc `onFailure` est utilisé pour gérer l'échec.
`failImmediatelyOnError` (facultatif)	Indique si le déploiement doit continuer lorsqu'une commande de l'étape échoue avec une valeur de sortie différente de zéro. Si aucune valeur n'est renseignée, la valeur par défaut est `false` et l'étape continue. Les valeurs autorisées sont `true` et `false`. OCI recommande de définir la valeur de cet attribut sur `true`. La valeur de l'attribut `failImmediatelyOnError` définie sous `steps` est prioritaire par rapport à la valeur de ce même attribut définie en dehors de `steps`.

Variables système prédéfinies

DevOps fournit un ensemble de variables 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 en cours.
`OCI_PIPELINE_ID`	OCID du pipeline de déploiement en cours.
`OCI_RESOURCE_PRINCIPAL_RPST`	Jeton de principal de ressource.
`OCI_RESOURCE_PRINCIPAL_VERSION`	Version de principal de ressource.
`OCI_CLI_AUTH`	Variable OCI CLI AUTH préconfigurée pour utiliser le principal de ressource.
`OCI_RESOURCE_PRINCIPAL_REGION`	Région de principal de ressource.
`OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM`	Chemin de clé privée de principal de ressource.

Exemple de spécification de commande

Exemple : créez un espace de noms OKE.