Documentazione di Oracle Cloud Infrastructure

Specifica comando

La specifica del comando contiene i comandi e le impostazioni della shell eseguiti durante una distribuzione. La specifica del comando è scritta in YAML. Il contenuto del file può essere specificato in linea oppure la specifica può essere memorizzata in un repository del Registro artifact.

Per eseguire qualsiasi file binario non preinstallato da Oracle, è necessario scaricarlo direttamente nella cartella radice oppure scaricarlo nella cartella dell'area di lavoro, quindi spostarlo nella cartella radice prima di eseguire l'esecuzione.

La specifica del comando è organizzata nelle seguenti sezioni:

  • Impostazione delle variabili di ambiente.
  • Immettere gli artifact.
  • Passi da eseguire in sequenza.

Sintassi specifica comando

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

Parametri specifica comando

Di seguito sono riportati i parametri della specifica del comando e i relativi dettagli:

Parametro descrizione;
version obbligatorio. Indica la versione della specifica del comando. Una versione mancante o non valida causa un errore della fase della shell.

Il valore supportato è 0.1.
component obbligatorio. Indica un particolare componente in DevOps. Un valore mancante o non valido causa l'errore della fase.

Il valore supportato è command.
timeoutInSeconds facoltativo. Specifica il timeout per l'intero file di specifica dei comandi. Ogni 'passo' può anche avere un proprio valore di timeout.

Se non viene specificato un valore, viene utilizzato il valore predefinito di 8 ore. Il valore massimo consentito è 8 ore.
shell facoltativo. Specifica la shell da utilizzare a livello globale della specifica comando. Il valore può essere sostituito facoltativamente a livello di passo.

I valori consentiti sono /bin/sh e bash. Se non è specificato, verrà utilizzato il valore predefinito di bash.
failImmediatelyOnError facoltativo. Specifica se la distribuzione deve continuare se un comando del passo non riesce con un valore di uscita diverso da zero. Se non viene specificato, il valore predefinito è false e il passo continua. I valori consentiti sono true e false. OCI consiglia di impostare il valore di questo attributo su true.
env

facoltativo. È possibile definire variabili personalizzate. Sono supportati tre tipi di variabili:

  • env/variabili: facoltativo. La chiave deve essere conforme a una stringa e a una variabile d'ambiente POSIX. Il valore può essere qualsiasi stringa. L'ambito di questa variabile è l'esecuzione del file di specifica del comando. Qualsiasi modifica al valore della variabile è visibile nei passi successivi. Queste variabili sono disponibili come variabili di ambiente per tutti i passi all'interno del file di specifica dei comandi.

    Se il valore della variabile contiene una nuova riga(\n) o un carattere di ritorno a capo(\r), verranno sostituiti con uno spazio nei passi successivi.

  • env/vaultVariables: facoltativo. La chiave deve essere conforme a una stringa e a una variabile d'ambiente POSIX. Il valore deve essere un OCID del segreto del vault. Il vault e la pipeline devono appartenere alla stessa tenancy. La tenancy deve disporre di un criterio appropriato per consentire alle risorse della pipeline di distribuzione di accedere al segreto.

    L'ambito di questa variabile è l'esecuzione del file di specifica dei comandi ed è disponibile per tutti i passi del file. Il valore di queste variabili viene recuperato dal vault e reso disponibile come variabili di ambiente per tutti i passi all'interno del file di specifica dei comandi.

  • env/exportedVariables: facoltativo. Un elenco di variabili può essere dichiarato qui. Il nome della variabile deve essere una stringa e una variabile di ambiente POSIX conforme. Il valore può essere assegnato in uno qualsiasi dei passi all'interno del file di specifica dei comandi. L'ambito di questa variabile è la pipeline di distribuzione. Qualsiasi variabile esportata è disponibile solo nelle fasi della shell della stessa pipeline.
inputArtifacts

facoltativo. Utilizzato per definire una lista di artifact di input necessari per l'esecuzione della fase shell corrente.

Supporta artifact generici dal Registro artifact.

I parametri sono i seguenti:

  • inputArtifacts/*/url: facoltativo. Fornire l'URL HTTP scaricabile esterno dell'artifact di input. L'URL deve essere disponibile pubblicamente. Al momento l'autenticazione/autorizzazione non è supportata.
  • inputArtifacts/*/name: obbligatorio. Questo nome viene utilizzato per fare riferimento agli artifact nell'esecuzione dei comandi.
  • inputArtifacts/*/location: obbligatorio. Percorso di destinazione del file system locale in cui è necessario scaricare l'artifact di input. Il percorso può essere specificato in uno dei seguenti metodi:
    • ${OCI_PRIMARY_SOURCE_DIR}/pom.xml
    • ${OCI_WORKSPACE_DIR}/[source-name]/pom.xml
    • /workspace/[source-name]/pom.xml
    • Percorso relativo dalla home del progetto, pom.xml

    Con uno qualsiasi dei valori, l'artifact di input viene scaricato nella directory home di origine primaria con un nome file, pom.xml.

    La posizione non supporta le variabili exportedVariables o pipeline.

  • inputArtifacts/*/type: obbligatorio. Il tipo di artifact di input che deve essere scaricato. I valori consentiti sono URL e GENERIC_ARTIFACT.
  • inputArtifacts/*/artifactld: obbligatorio. L'OCID dell'artifact. Se è stato fornito l'OCID, la pipeline di distribuzione ignora registryId, il percorso e la versione.
  • inputArtifacts/*/registryld: obbligatorio. OCID del Registro artifact.
  • inputArtifacts/*/path: obbligatorio. Il percorso di destinazione dell'artifact.
  • inputArtifacts/*/version: obbligatorio. La versione dell'artifact.

Nota: per l'artifact di input di tipo GENERIC_ARTIFACT, è possibile fornire come parametro obbligatorio l'OCID dell'artifact o una combinazione di ID registro, percorso e versione dell'artifact.
steps

obbligatorio. Questa sezione definisce un elenco di passi da eseguire.

  • passi/*/tipo: obbligatorio. Specifica il tipo di passo. Supporta i seguenti valori: Command
  • passi/*/nome: facoltativo. Nome riconoscibile dall'utente per il passo.

Tipi di passo

Comando

Nome attributo descrizione;
command Sono supportati sia comandi a riga singola che comandi a riga multipla. Tutti i comandi specificati in un passo vengono eseguiti nella stessa sessione della shell. I comandi possono essere shell o bash in base al valore steps/*/shell.

Il digiuno non riuscito non è abilitato. Affinché il passo abbia successo, viene considerato l'output dell'ultimo comando in un passo. Se il codice di uscita dell'ultimo comando è 0, il passo viene considerato come riuscito.
timeoutInSeconds (facoltativo) Specifica il timeout per il passo. Se non viene fornito, il valore viene ereditato dal parametro timeoutInSeconds globale. Il valore massimo consentito è 8 ore.
shell (facoltativo) Specifica il tipo di shell del passo corrente. Se non specificato, il valore viene ereditato dal parametro shell globale. I valori consentiti sono /bin/sh e shell.
onFailure (facoltativo) Lista di passi che devono essere eseguiti in caso di errore per uscire in modo normale dalla fase Shell. Eseguire se il passo corrispondente non riesce e, dopo l'esecuzione, la specifica del comando viene interrotta.

La gestione dell'errore non influisce sullo stato della fase Shell. Se uno dei passi non riesce, lo stato dello stadio della shell rimane failed, anche se gestito mediante il blocco onFailure.
failImmediatelyOnError (facoltativo) Specifica se la distribuzione deve continuare se un comando del passo non riesce con un valore di uscita diverso da zero. Se non viene specificato, il valore predefinito è false e il passo continua. I valori consentiti sono true e false. OCI consiglia di impostare il valore di questo attributo su true.

Il valore dell'attributo failImmediatelyOnError definito in steps ha la precedenza sullo stesso valore di attributo definito al di fuori di steps.

Variabili di sistema predefinite

DevOps fornisce un set di variabili di sistema predefinite con valori predefiniti che è possibile utilizzare nella specifica dei comandi.

Variabile descrizione;
OCI_DEPLOYMENT_ID OCID della distribuzione corrente.
OCI_PIPELINE_ID OCID della pipeline di distribuzione corrente.
OCI_RESOURCE_PRINCIPAL_RPST Token principal risorsa.
OCI_RESOURCE_PRINCIPAL_VERSION Versione principal risorsa.
OCI_CLI_AUTH AUTH CLI OCI preconfigurata per utilizzare il principal risorsa.
OCI_RESOURCE_PRINCIPAL_REGION Area principal risorsa.
OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM Percorso della chiave privata del principal risorsa.

Esempio di specifica comando

Esempio: creare uno spazio di nomi OKE.

version: 0.1
component: command
timeoutInSeconds: 6000
shell: bash

steps:
  - type: Command
    timeoutInSeconds: 600
    name: "Setup kube config and get nodes"
    command: |
      oci ce cluster create-kubeconfig --cluster-id ${clusterid} --file $HOME/.kube/config --region us-ashburn-1 --token-version 2.0.0  --kube-endpoint ${endpoint}
      kubectl get nodes
    onFailure:
      - type: Command
        command: |
          echo "Failed to set up kube config and get nodes"
        timeoutInSeconds: 60