Documentazione di Oracle Cloud Infrastructure

Specifica creazione

La specifica di build contiene i passi e le impostazioni di build utilizzati dalla pipeline di build per eseguire una build.

La specifica di build è scritta in YAML. Per impostazione predefinita, la specifica della build si trova nella radice della directory di origine della build primaria ed è utilizzata quando si esegue una pipeline di build. Il nome del file è build_spec.yml o build_spec.yaml. Se la specifica di build non è presente nella directory radice, è necessario fornire un percorso relativo del file quando si aggiunge la fase Build gestita.

La specifica di build è organizzata nelle seguenti sezioni:

  • Configurazione del motore di esecuzione build.
  • Impostazione delle variabili di ambiente.
  • Immettere gli artifact.
  • Passi da eseguire in sequenza.
  • Artifact di output.

Sintassi specifica build

version: 0.1
component: build
timeoutInSeconds: 10000
shell: bash
failImmediatelyOnError: true
env:
  variables:
    key: "value"
    key: "value"
  vaultVariables:
    key: "secret-id"
  exportedVariables:
    - variable
    - variable
    - variable

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: STAGE_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

outputArtifacts:
  - name: artifact-name
    type: artifact-type
    location: source-location
Nota

sudo non è disponibile nell'host del motore di esecuzione build. Se sono necessarie autorizzazioni di superutente, eseguire il passo della build come utente root.

Parametri specifica build

Di seguito sono riportati i parametri della specifica di build e i relativi dettagli:

Parametro descrizione;
version obbligatorio. Indica la versione della specifica build. Una versione mancante o non valida causa un errore della fase di creazione.

Il valore supportato è 0.1.
component obbligatorio. Indica un particolare componente in DevOps. Un valore mancante o non valido causa un errore di generazione.

Il valore supportato è build.
timeoutInSeconds facoltativo. Specifica il timeout per l'intero file di specifica della build. 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 build. 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 build 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 della build. 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 della build.

    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 di build devono appartenere alla stessa tenancy. La tenancy deve disporre di un criterio appropriato per consentire alle risorse della pipeline di build di accedere al segreto.

    L'ambito di questa variabile è l'esecuzione del file di specifica della build ed è disponibile per tutti i passi nel 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 della build.

  • 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 della build. L'ambito di questa variabile è la pipeline di build. Qualsiasi variabile esportata è disponibile nelle fasi successive della stessa pipeline.
inputArtifacts

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

Supporta i seguenti tipi di artifact di input:
  • Artifact da una qualsiasi delle fasi di build precedenti.
  • Artifact da qualsiasi URL HTTP scaricabile esterno.
  • 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. Se l'URL non è presente, questo nome viene utilizzato per cercare gli artifact prodotti dalle fasi di build precedenti nella stessa pipeline. Pertanto, outputArtifacts/name e inputArtifacts/name devono corrispondere per utilizzare un artifact specifico prodotto dalla fase di build precedente nella pipeline.
  • 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, STAGE_ARTIFACT e GENERIC_ARTIFACT.
  • inputArtifacts/*/artifactld: obbligatorio. L'OCID dell'artifact. Se è stato fornito l'OCID, la pipeline di build 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, VulnerabilityAudit. Per ulteriori informazioni, vedere Tipo di passo.
  • passi/*/nome: facoltativo. Nome riconoscibile dall'utente per il passo.
outputArtifacts

facoltativo. Specifica gli artifact prodotti dalla fase di creazione. Gli artifact prodotti come output in questa sezione vengono salvati per tutta la durata dell'esecuzione corrente della build. Possono essere utilizzati nelle fasi successive della pipeline di build.

  • outputArtifacts/*/name: obbligatorio. Il nome può contenere lettere minuscole (a-z), lettere maiuscole (A-Z), caratteri di sottolineatura (_) e trattini (-). Il nome è l'identificativo univoco per l'artifact di output. Nelle fasi successive della pipeline di build, il nome viene utilizzato per identificare un artifact.
  • outputArtifacts/*/type: obbligatorio. I valori consentiti sono BINARY e DOCKER_IMAGE.

    BINARY: specifica i file binari come artifact di output.

    outputArtifacts/*/location: percorso di origine del file system locale in cui è possibile trovare l'artifact di output. Il percorso può essere specificato in uno dei seguenti metodi (si supponga che il file pom.xml sia presente nella directory home di origine primaria):

    • ${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

    Se il file non viene trovato nella posizione specificata, la fase di creazione non riesce.

    DOCKER_IMAGE: specifica un'immagine Docker come artifact di output.

    outputArtifacts/*/location: tag di immagine Docker creato in base a uno dei passi del file di specifica della build.

    Ad esempio, se in uno dei passi del file di specifica della build viene creata un'immagine Docker come docker build -t iad.ocir.io/id204we8d65n/hello-world:1.0, il campo della posizione deve contenere iad.ocir.io/id204we8d65n/hello-world:1.0 per la produzione di questo artifact.

    L'immagine deve essere creata o estratta e resa disponibile in uno dei passi della specifica di build. In caso contrario, il passo outputArtifact non riesce e alla fine anche la fase di build non riesce.

    La posizione non supporta le variabili exportedVariables o pipeline.

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.

L'errore di velocità 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 con grazia dalla fase di build. Eseguire se il passo corrispondente non riesce e, dopo l'esecuzione, la specifica di build viene interrotta.

La gestione dell'errore non influisce sullo stato della fase di build. Se uno dei passi non riesce, lo stato della fase di build rimane failed, anche se gestito mediante il blocco onFailure.
failImmediatelyOnError (facoltativo) Specifica se la build 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.

Audit delle vulnerabilità

Un audit delle vulnerabilità descrive le vulnerabilità dell'applicazione e le relative dipendenze. Quando si esegue una build utilizzando il servizio DevOps OCI, è possibile avviare una scansione del codice per un nuovo commit nel repository di codici. L'audit delle vulnerabilità si verifica nella fase Build gestita.

Nel file delle specifiche di build viene aggiunto un passo di audit delle vulnerabilità di tipo VulnerabilityAudit che la pipeline di build DevOps utilizza durante l'esecuzione della build per la scansione del codice. Gli attributi di questo passo sono elencati come segue:

Nome attributo descrizione; Supporto dei valori con parametri
name (facoltativo) Nome del passo. NA
vulnerabilityAuditName (facoltativo) Nome della risorsa di audit delle vulnerabilità. Sì
vulnerabilityAuditCompartmentId (Facoltativo)

Il valore predefinito è knowledgeBaseCompartmentId

 OCID del compartimento in cui è necessario creare la risorsa di audit. Sì
knowledgeBaseId (obbligatorio) OCID del segnaposto/tag per la gestione dei dettagli delle risorse di audit delle vulnerabilità. Risorsa padre della risorsa di audit delle vulnerabilità. Sì
configuration/buildType (obbligatorio) Tipo di strumento di creazione. NA
configuration/pomFilePath (obbligatorio) Posizione del file pom.xml. Sì
configuration/packagesToIgnore (facoltativo) Lista di pacchetti Java da ignorare durante il calcolo del risultato della scansione durante l'audit delle vulnerabilità. NA
configuration/maxPermissibleCvssV2Score (facoltativo)

Il valore predefinito è 0.0

 Punteggio massimo v2 CVSS, consentito per l'audit delle vulnerabilità. Qualsiasi elemento al di sopra di questa configurazione deve contrassegnare la build come Failed. NA
configuration/maxPermissibleCvssV3Score (facoltativo)

Il valore predefinito è 0.0

 Punteggio massimo v3 CVSS, consentito per l'audit delle vulnerabilità. Qualsiasi elemento al di sopra di questa configurazione deve contrassegnare la build come Failed. NA
freeFormTags (facoltativo) Accetta la coppia chiave-valore. NA

Variabili di sistema predefinite

DevOps fornisce un set di variabili di sistema predefinite con valori predefiniti che è possibile utilizzare, ad esempio le variabili di ambiente nella specifica della build.

Variabile descrizione;
OCI_STAGE_ID OCID della fase corrente.
OCI_PIPELINE_ID OCID della pipeline di build corrente.
OCI_BUILD_RUN_ID OCID dell'esecuzione della build corrente.
OCI_TRIGGER_COMMIT_HASH Hash di commit del trigger corrente.
OCI_TRIGGER_SOURCE_BRANCH_NAME Diramazione che attiva la build.
OCI_TRIGGER_SOURCE_URL URL del repository che ha attivato la build
OCI_TRIGGER_EVENT_TYPE Attivazione che ha avviato l'evento.
OCI_PRIMARY_SOURCE_DIR Directory di lavoro predefinita della build (directory di lavoro di origine principale).
OCI_WORKSPACE_DIR Valore della directory di lavoro. Contiene /workspace come valore predefinito.
${OCI_WORKSPACE_DIR}/<source-name> Creare il percorso della directory di origine.

source-name è il nome dell'origine build fornito dall'utente durante la creazione della fase di build.
OCI_BUILD_STAGE_NAME Nome fase build.
OCI_PRIMARY_SOURCE_NAME Nome dell'origine build primaria.
OCI_PRIMARY_SOURCE_COMMIT_HASH Hash di commit dell'origine build primaria utilizzato nell'esecuzione della build corrente.
OCI_PRIMARY_SOURCE_URL URL dell'origine build primaria.
OCI_PRIMARY_SOURCE_BRANCH_NAME Diramazione di origine build primaria utilizzata nell'esecuzione della build corrente.

Esempi di specifiche di build

Ad esempio 1:

version: 0.1             
component: build
timeoutInSeconds: 1000
shell: bash           

steps:
  - type: Command
    name: "Build app"
    command: |
      mvn clean install

Ad esempio 2:

version: 0.1
component: build
timeoutInSeconds: 6000
shell: bash
failImmediatelyOnError: true
env:
  exportedVariables:
    - BuildServiceDemoVersion

steps:
  - type: Command
    name: "Build Source"
    timeoutInSeconds: 4000
    failImmediatelyOnError: true
    command: |
      echo $PATH
      mvn clean install
  - type: Command
    timeoutInSeconds: 400
    name: "Dockerizer"
    command: |
      BuildServiceDemoVersion=`echo ${OCI_BUILD_RUN_ID} | rev | cut -c 1-7`
      echo $BuildServiceDemoVersion
      docker build -t build-service-demo

  - type: VulnerabilityAudit
    name: "Scan my maven repo"
    vulnerabilityAuditName: Report-${buildRunId}
    vulnerabilityAuditCompartmentId: ocid1.compartment.oc1.iad.restoftheocid
    knowledgeBaseId: ocid1.knowledgebase.oc1.iad.restoftheocid
    configuration:
      buildType: maven
      pomFilePath: ./pom.xml
      packagesToIgnore:
        - "oracle.jdbc.*"
        - "org.apache.logging.log4j:1.2"
      maxPermissibleCvssV2Score: 5.0  
      maxPermissibleCvssV3Score: 5.1
      freeFormTags:
                  key1: value1
                  key2: value2

outputArtifacts:
  - name: build-service-demo
    type: DOCKER_IMAGE
    location: build-service-demo
  - name: build-service-demo-kube-manifest
    type: BINARY
    location: deployment/app.yml

Ad esempio 3:

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

# Variables
env:
  variables:
    "testEnv" : "testValue1"
  vaultVariables:
    docker_registry_password : <secret-ocid>
  exportedVariables:
    - patch_number
    - build_Result

inputArtifacts:
  - name: hello-dev-jar 
    type: STAGE_ARTIFACT
    location: /workspace/Source/hello123.class
  - name: public-artifact
    type: URL
    url: https://raw.githubusercontent.com/apache/kafka/trunk/README.md  #URL must be publicly accessible
    location: /workspace/Source/readme.md
  - name: shell_script
    type: GENERIC_ARTIFACT
    artifactId: ocid1.genericartifact.oc1.iad.0.restoftheocid #appropriate policy is required for access
    location: /workspace/Source/script.sh
  - name: shell_script
    type: GENERIC_ARTIFACT
    registryId: ocid1.artifactrepository.oc1.iad.0.restoftheocid #appropriate policy is required for access
    path: some_script.sh
    version: 2.0
    location: /workspace/Source/script.sh

steps:
  - type: Command
    name: "Build Source"
    timeoutInSeconds: 4000
    shell: /bin/sh
    command: |
      # oci cli pre configured with build pipeline resource principal
      oci os ns get
      javac HelloWorld.java
    onFailure:
      - type: Command
        timeoutInSeconds: 400
        shell: /bin/sh
        command: |
          echo "Handling Failure"
          build_result=FAILURE
          echo "Failure successfully handled"
        timeoutInSeconds: 400
  - type: Command
    timeoutInSeconds: 400
    name: "Dockerizer & Test"
    command: |
      docker build -t test-image .
    onFailure:
      - type: Command
        command: |
          echo "Handling Failure"
          build_result=FAILURE
          echo "Failure successfully handled"
        timeoutInSeconds: 400
  - type: Command
    timeoutInSeconds: 400
    name: "Dockerizer & Test"
    command: |
      build_result=SUCCESS
      patch_number==`echo ${OCI_BUILD_RUN_ID} | rev | cut -c 1-7`
        
outputArtifacts:
  - name: kube-manifest
    type: BINARY
    location: ${OCI_WORKSPACE_DIR}/Source/app.yml
  - name: hello-dev-image
    type: DOCKER_IMAGE
    location: test-image
Nota

Per creare applicazioni Java ad alte prestazioni, è possibile utilizzare Oracle GraalVM nella pipeline di build. Per installare e utilizzare Oracle GraalVM nella pipeline di build DevOps, è necessario aggiornare il file di specifica della build. Per ulteriori informazioni ed esempi, vedere Uso di Oracle GraalVM in DevOps Pipeline di build.