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 | 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 | 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:
| 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 | 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 | 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 | 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_datasetsopoliciespuò essere vuoto, oppure entrambi possono essere vuoti. - Gli unici valori validi per un set di dati personalizzati
type_of_testsonotestecode. - 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-updateelenca 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.