DevOps Insights CLI

La CLI di IBM Cloud® DevOps Insights fornisce una serie di comandi che si possono usare per integrare la propria build con DevOps Insights. Utilizzare due diversi tipi di comandi: Comandi di utilizzo della CLI e comandi della CLI per l'integrazione con DevOps Insights.

DevOps Insights è giunto al termine del servizio e non è più disponibile. Per saperne di più

Prima di iniziare

  • Installa la CLI IBM Cloud. Per istruzioni, vedere Download di IBM Cloud CLI.

  • Aggiungi il plug-in della CLI IBM Cloud. Esegui il seguente comando:

ibmcloud plugin install doi
  • Assicurarsi di poter accedere a una catena di strumenti con lo strumento DevOps Insights configurato per quella catena di strumenti. Per ulteriori informazioni sulle toolchain, vedi Creazione di una toolchain da un'applicazione.

  • Specificare l'ID della catena di strumenti utilizzando uno dei seguenti metodi:

    • Specificare l'ID della catena di strumenti come parametro CLI del comando.
    • Impostare la variabile d'ambiente TOOLCHAIN_ID .
    • La pipeline IBM Cloud® Continuous Delivery potrebbe impostare automaticamente la variabile d'ambiente PIPELINE_TOOLCHAIN_ID.

    La CLI ha bisogno del valore dell'ID della catena di strumenti. Il valore dell'ID della catena di strumenti specificato nel parametro CLI sostituisce il valore della variabile d'ambiente.

    L'ID della toolchain si trova nell'URL della toolchain visualizzato nel browser. Se si usa IBM® Continuous Delivery Pipeline for IBM Cloud®, si può impostare l'ID della catena di strumenti per inviare i dati di compilazione a una catena di strumenti diversa. Per ulteriori informazioni, vedi Aggregazione dei dati da più origini in una sola toolchain.

Accedi

Utilizza questo comando per accedere a IBM Cloud. L'API_KEY deve avere accesso alla toolchain.

ibmcloud login --apikey API_KEY

Accedere alla CLI con un endpoint privato

Per un maggiore controllo e sicurezza dei dati quando si utilizza la CLI, è possibile utilizzare percorsi privati verso gli endpoint IBM Cloud. È necessario innanzitutto abilitare il routing e il forwarding virtuali nel proprio account; solo a quel punto sarà possibile abilitare l'uso degli endpoint del servizio privato " IBM Cloud ". Per ulteriori informazioni sull'impostazione dell'account per supportare l'opzione di connettività privata, vedere Abilitazione di VRF ed endpoint di servizio.

Utilizzare il seguente comando per accedere a un endpoint privato utilizzando la CLI. L'API_KEY deve avere accesso alla toolchain.

ibmcloud login -a private.cloud.ibm.com --apikey API_KEY

Comandi di utilizzo della CLI

DevOps Insights aiuto

Il seguente comando visualizza l'elenco di comandi DevOps Insights:

 ibmcloud doi --help

DevOps Insights command help

Il comando seguente mostra i dettagli dei parametri obbligatori per un comando:

 ibmcloud doi <command> --help

È possibile passare un parametro --region a qualsiasi comando. Impostando il valore di questo parametro sulla regione ibmcloud della catena di strumenti, la CLI non deve determinare in quale regione si trova la catena di strumenti, rendendola più efficiente e affidabile. Questo parametro è opzionale per la compatibilità con le versioni precedenti.

Comandi per l'integrazione con DevOps Insights

Quando utilizzi la CLI per una build, devi pubblicare un record di build.

Il valore dei parametri logicalappname e buildnumber passati alla CLI deve rimanere lo stesso per tutte le invocazioni di comando.

Pubblicazione di un record di build

Il seguente comando pubblica un record di build su DevOps Insights:

 ibmcloud doi buildrecord-publish --branch BRANCH --repositoryurl REPOSITORYURL --commitid COMMITID --status STATUS --logicalappname LOGICALAPPNAME --buildnumber BUILDNUMBER --toolchainid TOOLCHAINID [--joburl JOBURL] [--region REGION]

Le seguenti sono le opzioni di comando per pubblicare un record di build.

Opzioni di comando per la pubblicazione di un record di build
Opzioni di comando Obbligatoria o facoltativa Descrizione
-B, --branch Obbligatorio Il ramo del repository in cui viene eseguita la build.
-R, --repositoryurl Obbligatorio L'URL del repository Git.
-C, --commitid Obbligatorio L'ID di commit Git.
-S, --status Obbligatorio Lo stato di build. Valori accettabili: pass e
fail.
-L, --logicalappname Obbligatorio Il nome dell'applicazione.
-N, --buildnumber Obbligatorio Qualsiasi stringa che identifica la build.
-I, --toolchainid Obbligatorio Se la variabile d'ambiente TOOLCHAIN_ID è impostata, questo flag è opzionale. Se vengono forniti sia la variabile d'ambiente che il flag, il valore del flag sovrascrive il valore della variabile d'ambiente.
-J, --joburl Facoltativo l'URL ai log di build del lavoro impostato automaticamente dalla CLI in IBM® Continuous Delivery Pipeline for IBM Cloud®.
--region Obbligatorio La regione ibmcloud della catena di strumenti. Questo valore è necessario quando si utilizzano endpoint privati. È opzionale, ma è bene che sia presente nel caso di endpoint pubblici.

Esempio

ibmcloud doi buildrecord-publish  -B master -R "https://github.com/oic/dlms.git" -C dff7884b9168168d91cb9e5aec78e93db0fa80d9 -S pass -L testapp -N master:199 -I b531487c-9c22-4f3b-9d20-5be408d57891 --region eu-gb
or
ibmcloud doi buildrecord-publish  --branch master --repositoryurl "https://github.com/oic/dlms.git" --commitid dff7884b9168168d91cb9e5aec78e93db0fa80d9 --status pass --logicalappname testapp --buildnumber master:199 --toolchainid b531487c-9c22-4f3b-9d20-5be408d57891

Pubblicare un record di prova

Il seguente comando pubblica un record di test su DevOps Insights:

 ibmcloud doi testrecord-publish --filelocation FILELOCATION --type TYPE --logicalappname LOGICALAPPNAME --buildnumber BUILDNUMBER --toolchainid TOOLCHAINID [--drilldownurl DRILLDOWNURL] [--env ENV] [--sqtoken SONARQUBE_TOKEN] [--tags TAGS] [--region REGION]

Le seguenti sono le opzioni di comando per pubblicare dei record di test.

Opzioni di comando per la pubblicazione di un record di build
Opzioni di comando Obbligatoria o facoltativa Descrizione
-F, --filelocation Obbligatorio L'ubicazione dei risultati che vuoi caricare. Può essere un singolo file, un'intera directory oppure diversi file che corrispondono a un'espressione jolly.
-T, --type Obbligatorio Il tipo dei risultati di test che vuoi caricare.
-L, --logicalappname Obbligatorio Il nome dell'applicazione.
-N, --buildnumber Obbligatorio Qualsiasi stringa che identifica la build.
-I, --toolchainid Obbligatorio Se la variabile d'ambiente TOOLCHAIN_ID è impostata, questo flag è opzionale. Se vengono forniti sia la variabile d'ambiente che il flag, il valore del flag sovrascrive il valore della variabile d'ambiente.
-U, --drilldownurl Facoltativo Un URL dove possono essere trovate ulteriori informazioni sui risultati del test. Se questo URL non è valido, l'opzione viene ignorata.
-E, --env Facoltativo Il nome dell'ambiente da associare ai risultati del test. Questa opzione viene ignorata per i test di unità, i test di copertura del codice e le scansioni di sicurezza statiche.
-K, --sqtoken Facoltativo Questo comando è un token SonarQube. Valido solo se il tipo specificato è SonarQube. Utilizzato per eseguire il pull di ulteriori informazioni dal server SonarQube
--tags Facoltativo Specificare un elenco separato da virgole di tag da associare a questo risultato del test.
--region Obbligatorio La regione ibmcloud della catena di strumenti. Questo valore è necessario quando si utilizzano endpoint privati. È opzionale, ma è bene che sia presente nel caso di endpoint pubblici.

Esempio

ibmcloud doi testrecord-publish -F "tests/fvt/*.json" -T fvt -L testapp -N master:199 -I b531487c-9c22-4f3b-9d20-5be408d57891 --tags "CC,app1"
or
ibmcloud doi testrecord-publish --filelocation "tests/fvt/*.json" --type fvt --logicalappname testapp --buildnumber master:199 --toolchainid b531487c-9c22-4f3b-9d20-5be408d57891 --region ca-tor

Sono supportati i seguenti tipi di test:

Tipi di record di prova
Immettere Descrizione
unittest Risultati del test di unità
fvt Risultati del test di verifica funzionale (FVT)
code Risultati della copertura del codice
sonarqube Risultati della scansione SonarQube
vulnerabilityadvisor Risultati del Controllo vulnerabilità da IBM Vulnerability Advisor on Cloud
cratf Rapporto Terraform generato da Code Risk Analyzer
crabom Rapporto sulla distinta materiali (BOM) generato da Code Risk Analyzer
cradeploy Rapporto di distribuzione generato da Code Risk Analyzer
cracve Rapporto sulle vulnerabilità generato da Code Risk Analyzer
zapscan Rapporti di scansione OWASP Zed Attack Proxy (ZAP)

IBM Application Security on Cloud 1.0.0 non è più pubblicato (tipi di test staticsecurityscan e dynamicsecurityscan ). Tutto il supporto di IBM Application Security on Cloud 1.0.0 è fornito da HCL. Per ulteriori informazioni, consultare il sito Documentazione HCL AppScan.

Pubblicazione di un record di distribuzione

Il seguente comando pubblica un record di distribuzione su DevOps Insights:

 ibmcloud doi deployrecord-publish --env ENV --status STATUS --logicalappname LOGICALAPPNAME --buildnumber BUILDNUMBER --toolchainid TOOLCHAINID [--joburl JOBURL] [--appurl APPURL] [--region REGION]
Opzioni di comando per la pubblicazione di un record di distribuzione
Opzioni di comando Obbligatoria o facoltativa Descrizione
-E, --env Obbligatorio L'ambiente in cui il lavoro della pipeline ha distribuito l'applicazione.
-S, --status Obbligatorio Lo stato della distribuzione. Questo valore deve essere pass o fail.
-L, --logicalappname Obbligatorio Il nome dell'applicazione.
-N, --buildnumber Obbligatorio Qualsiasi stringa che identifica la build.
-I, --toolchainid Obbligatorio Se la variabile d'ambiente TOOLCHAIN_ID è impostata, questo flag è opzionale. Se vengono forniti sia la variabile d'ambiente che il flag, il valore del flag sovrascrive il valore della variabile d'ambiente.
-A, --appurl Facoltativo L'URL in cui è in esecuzione l'applicazione distribuita.
-J, --joburl Facoltativo l'URL ai log di build del lavoro impostato automaticamente dalla CLI in IBM® Continuous Delivery Pipeline for IBM Cloud®.
--region Obbligatorio La regione ibmcloud della catena di strumenti. Questo valore è necessario quando si utilizzano endpoint privati. È opzionale, ma è bene che sia presente nel caso di endpoint pubblici.

Esempio

ibmcloud doi deployrecord-publish -E "staging" -S pass -L testapp -N master:199 -I b531487c-9c22-4f3b-9d20-5be408d57891 --region au-syd
or
ibmcloud doi deployrecord-publish --env "staging" --status pass --logicalappname testapp --buildnumber master:199 --toolchainid b531487c-9c22-4f3b-9d20-5be408d57891

Valutazione dei gate

Il seguente comando valuta un gate DevOps Insights:

 ibmcloud doi gate-evaluate --policy POLICY --logicalappname LOGICALAPPNAME --buildnumber BUILDNUMBER --toolchainid TOOLCHAINID [--forcedecision] [--ruletype RULETYPE] [--region REGION]

Le seguenti sono le opzioni di comando per valutare i gate:

Opzioni di comando per la valutazione dei cancelli
Opzioni di comando Obbligatoria o facoltativa Descrizione
-P, --policy Obbligatorio Il nome della politica utilizzata dal gate per prendere la sua decisione.
-L, --logicalappname Obbligatorio Il nome dell'applicazione.
-N, --buildnumber Obbligatorio Qualsiasi stringa che identifica la build.
-I, --toolchainid Obbligatorio Se la variabile d'ambiente TOOLCHAIN_ID è impostata, questo flag è opzionale. Se vengono forniti sia la variabile d'ambiente che il flag, il valore del flag sovrascrive il valore della variabile d'ambiente.
-D, --forcedecision Facoltativo Imposta il valore su true per uscire con un codice di errore se la valutazione della politica non riesce. Il valore viene impostato automaticamente su false se questa opzione non viene specificata.
-E, --ruletype Facoltativo Un tipo di regola da considerare. Se includi questa opzione, solo le regole di questo tipo vengono considerate nel processo decisionale.
--region Obbligatorio La regione ibmcloud della catena di strumenti. Questo valore è necessario quando si utilizzano endpoint privati. È opzionale, ma è bene che sia presente nel caso di endpoint pubblici.

Esempio

ibmcloud doi gate-evaluate -P "policyname" -D true -L testapp -N master:199 -I b531487c-9c22-4f3b-9d20-5be408d57891 --region br-sao
or
ibmcloud doi gate-evaluate --policy "policyname" --forcedecision true --logicalappname testapp --buildnumber master:199 --toolchainid b531487c-9c22-4f3b-9d20-5be408d57891

Aggiornamento di set di dati e criteri personalizzati

Il comando seguente crea e aggiorna i set di dati e i criteri personalizzati per una catena di strumenti:

 ibmcloud doi policies-update --file FILELOCATION --toolchainid TOOLCHAINID [--dryrun] [--region REGION]

Di seguito sono riportate le opzioni di comando per l'aggiornamento dei set di dati e dei criteri personalizzati:

Opzioni di comando per l'aggiornamento di set di dati e criteri personalizzati
Opzioni di comando Obbligatoria o facoltativa Descrizione
-F, --file Obbligatorio Il percorso del file JSON che contiene l'elenco dei set di dati personalizzati e dei criteri da aggiungere o aggiornare. Sono accettati sia percorsi assoluti che relativi.
-I, --toolchainid Obbligatorio Se la variabile d'ambiente TOOLCHAIN_ID è impostata, questo flag è opzionale. Se vengono forniti sia la variabile d'ambiente che il flag, il valore del flag sovrascrive il valore della variabile d'ambiente.
-D, --dryrun Facoltativo L'opzione per simulare solo le modifiche, senza aggiornamenti.
--region Obbligatorio La regione ibmcloud della catena di strumenti. Questo valore è necessario quando si utilizzano endpoint privati. È opzionale, ma è bene che sia presente nel caso di endpoint pubblici.

Esempio

ibmcloud doi policies-update -F "policies/policy.json" -I b531487c-9c22-4f3b-9d20-5be408d57891 --region jp-tok
or
ibmcloud doi policies-update --file "policies/policy.json" --toolchainid b531487c-9c22-4f3b-9d20-5be408d57891

Struttura del file JSON per il comando updatepolicies

La struttura di un file JSON valido contiene due campi:

{
      "custom_datasets": [],
      "policies": []
}
  • È possibile specificare un numero qualsiasi di criteri (e di set di dati personalizzati) per l'array.
  • Se il criterio specificato (e il set di dati personalizzato) esiste per una catena di strumenti, il criterio viene aggiornato o creato.
  • L'array custom_datasets o policies può essere vuoto, oppure entrambi possono essere vuoti.
  • Gli unici valori validi per un set di dati personalizzati type_of_test sono test e code.
  • Se esiste un set di dati personalizzato per una catena di strumenti, è possibile utilizzarlo nelle regole dei criteri definite nel file JSON. Non è sempre necessario definire il set di dati personalizzato all'interno del file JSON.
  • Il file JSON di esempio fornito per il comando policies-update elenca tutti i possibili tipi di regole che è possibile specificare in un criterio. Tutti i campi di queste regole sono obbligatori.
  • Utilizzare una sola regola per ogni set di dati.
  • Il campo del nome all'interno di una regola è facoltativo.

Esempio di file JSON per il comando policies-update

Questo file JSON di esempio contiene due set di dati personalizzati e due criteri. Il primo criterio name: "Orders" contiene tutti i tipi di regole che si possono utilizzare all'interno di un criterio.

{
  "custom_datasets": [
 .  {
      "lifecycle_stage": "integrationtest",
      "type_of_test": "test",
      "label": "Integration Test"
    },
    {
      "lifecycle_stage": "covtest",
      "type_of_test": "code",
      "label": "Coverage Test"
    }
  ],
  "policies": [
    {
      "name": "Orders",
      "description": "Composite Policy.",
      "rules": [
        {
          "name": "rule1",
 .        "description": "Unit Test Rule with regression",
          "stage": "unittest",
          "percentPass": 100,
          "criticalTests": [
            "Get Weather with incomplete zip code"
          ],
          "regressionCheck": true
        },
        {
          "name": "rule2",
          "description": "Unit Test Rule without regression",
          "stage": "integrationtest",
          "percentPass": 98,
          "criticalTests": [
            "'Get Weather with incomplete zip code'"
          ],
        },
        {
          "name": "rule3",
          "description": "Functional test Rule",
          "stage": "fvt",
          "percentPass": 98,
          "criticalTests": [
            "'Get Weather with incomplete zip code'"
          ],
        },
        {
          "name": "rule4",
          "description": "Code Coverage rule",
          "stage": "code",
          "codeCoverage": 98,
        },
        {
          "name": "rule5",
          "description": "Custom dataset rule",
          "stage": "covtest",
          "codeCoverage": 60,
        },
        {
          "name": "rule6",
          "description": "Static Security Scan rule",
          "stage": "staticsecurityscan",
          "highSeverity": 40,
          "mediumSeverity": 5,
          "lowSeverity": 9
        },
        {
          "name": "rule7",
         "description": "Dynamic Security Scan rule",
          "stage": "dynamicsecurityscan",
          "highSeverity": 40,
          "mediumSeverity": 5,
          "lowSeverity": 9
        },
        {
          "name": "rule8",
          "description": "Sonarqube rule",
          "stage": "sonarqube"
        },
        {
          "name": "rule9",
          "description": "Vulnerability rule",
          "stage": "vulnerabilityadvisor"
        }
      ]
    },
    {
      "name": "UI",
      "description": "Policy to check Unit Test.",
      "rules": [
        {
          "name": "Unit Test Rule",
          "description": "Unit Test Rule",
          "stage": "integrationtest",
          "percentPass": 100,
          "criticalTests": []
        }
      ]
    }
  ]
}

FAQ

Trova le risposte alle domande più frequenti sull'utilizzo della CLI ( DevOps Insights ).

Perché la CLI fallisce con il messaggio "Non si ha accesso alla toolchain"?

La variabile d'ambiente API_KEY, usata per accedere a IBM Cloud, deve poter accedere alla catena di strumenti. Inoltre, verificare che sia stata aggiunta l'integrazione dello strumento DevOps Insights alla propria catena di strumenti.

La CLI è stata eseguita correttamente, perché i dati non vengono visualizzati nel dashboard?

Assicurarsi che il valore dei parametri logicalappname e buildnumber passati alla CLI sia lo stesso in tutti gli stadi della compilazione. Inoltre, verificare che sia stato caricato un record di build per la build. I dati dei record di test caricati per una specifica build non appaiono nel dashboard senza un record di build.

La CLI va in timeout nella comunicazione con il server Sonarqube, c'è un modo per aumentare il periodo di timeout?

Il tempo di attesa predefinito è di 60 secondi. Prima di richiamare la CLI DevOps Insights, impostare la variabile d'ambiente IBMCLOUD_HTTP_TIMEOUT. Il suo valore è il numero di secondi.

    export IBMCLOUD_HTTP_TIMEOUT=120

Come si può determinare il motivo del fallimento della CLI?

Prima di richiamare la CLI DevOps Insights, impostare la variabile d'ambiente IBMCLOUD_TRACE su true per attivare il registro di debug.

    export IBMCLOUD_TRACE=true

Osservare le chiamate API e le risposte visualizzate nel log per determinare il motivo esatto del fallimento.