Questo documento descrive il funzionamento delle destinazioni personalizzate in Cloud Deploy.
Cloud Deploy include il supporto integrato per vari ambienti di runtime come target. Tuttavia, l'elenco dei tipi di destinazione supportati è limitato. Le destinazioni personalizzate ti consentono di eseguire il deployment in altri sistemi oltre ai runtime supportati.
Una destinazione personalizzata è una destinazione che rappresenta un ambiente di output arbitrario diverso da un runtime supportato da Cloud Deploy.
La pagina Crea un target personalizzato descrive il processo per definire un tipo di target personalizzato e implementarlo come target in una pipeline di distribuzione.
Come funziona un target personalizzato?
Ogni target personalizzato è costituito dai seguenti componenti:
Azioni personalizzate, definite in
skaffold.yaml
Sono simili a come definisci gli hook di deployment. Nel file
skaffold.yaml
definiscicustomActions
, in cui ogni azione personalizzata identifica un'immagine container da utilizzare e i comandi da eseguire su quel container.In questo modo, il target personalizzato è semplicemente un'azione o un insieme di azioni personalizzato.
Per qualsiasi tipo di target personalizzato, puoi configurare un'azione di rendering e un'azione di deployment personalizzata. Queste azioni consumano valori forniti da Cloud Deploy e devono soddisfare un insieme di output richiesti.
L'azione di rendering personalizzato è facoltativa, ma devi crearne una a meno che il target personalizzato non funzioni correttamente se eseguito da
skaffold render
, che è l'impostazione predefinita per Cloud Deploy.Una definizione del tipo di target personalizzato
CustomTargetType
è una risorsa di Cloud Deploy che identifica le azioni personalizzate (definite separatamente inskaffold.yaml
) che le destinazioni di questo tipo utilizzano per le attività di rendering della release e di deployment dell'implementazione.-
La definizione di un target personalizzato è la stessa che per qualsiasi tipo di target, tranne per il fatto che include la proprietà
customTarget
, il cui valore è il nome diCustomTargetType
.
Una volta implementati questi componenti, puoi utilizzare il target come qualsiasi altro target, fa riferimento all'avanzamento della pipeline di distribuzione e sfruttando appieno le funzionalità di Cloud Deploy, come promozione e approvazioni e rollback.
Esempio
La guida rapida Definisci e utilizza un tipo di target personalizzato crea un tipo di target personalizzato che include semplici comandi da eseguire su un'immagine container: un comando per il rendering e uno per il deployment. I comandi, in questo caso, si limitano ad aggiungere testo ai file di output richiesti per il rendering e il deployment.
Per altri esempi, consulta la sezione Esempi di target personalizzati.
Input e output obbligatori
Qualsiasi tipo di target personalizzato definito per Cloud Deploy deve soddisfare i requisiti di input e output, sia per il rendering che per il deployment. Questa sezione elenca quali input e output sono obbligatori e il modo in cui vengono forniti.
Cloud Deploy fornisce gli input richiesti, sia per il rendering che per il deployment, come variabili di ambiente. Le sezioni seguenti elencano questi input, nonché gli output che devono essere restituiti dalle azioni di rendering e deployment personalizzato.
Esegui il deployment dei parametri come variabili di ambiente
Oltre alle variabili di ambiente elencate in questa sezione, Cloud Deploy può passare ai tuoi container personalizzati qualsiasi parametro di deployment impostato.
I parametri di deployment intesi come input per i target personalizzati devono iniziare con
customTarget/
, ad esempio customTarget/vertexAIModel
. Quando fai riferimento a un parametro di deployment come variabile di ambiente, utilizza la seguente sintassi:
CLOUD_DEPLOY_customTarget_[VAR_NAME]
Dove VAR_NAME
è il nome che segue la barra nel nome del parametro di deployment. Ad esempio, se definisci un parametro di deployment denominato customTarget/vertexAIModel
, fai riferimento a questo parametro come CLOUD_DEPLOY_customTarget_vertexAIModel
.
Input per il rendering delle azioni
Per azioni di rendering personalizzate, Cloud Deploy fornisce i seguenti input obbligatori, come variabili di ambiente. Per le implementazioni multifase (deployment canary), Cloud Deploy fornisce queste variabili per ogni fase.
CLOUD_DEPLOY_PROJECT
Il progetto Google Cloud in cui viene creato il tipo di destinazione personalizzato.
CLOUD_DEPLOY_LOCATION
La regione Google Cloud per il tipo di target personalizzato.
CLOUD_DEPLOY_DELIVERY_PIPELINE
Il nome della pipeline di distribuzione di Cloud Deploy che fa riferimento al tipo di destinazione personalizzato.
CLOUD_DEPLOY_RELEASE
Il nome della release per cui viene richiamata l'operazione di rendering.
CLOUD_DEPLOY_TARGET
Il nome della destinazione di Cloud Deploy che utilizza il tipo di destinazione personalizzato.
CLOUD_DEPLOY_PHASE
La fase di implementazione a cui corrisponde il rendering.
CLOUD_DEPLOY_REQUEST_TYPE
Per l'azione di rendering personalizzato, il valore è sempre
RENDER
.CLOUD_DEPLOY_FEATURES
Un elenco separato da virgole di funzionalità Cloud Deploy che il container personalizzato deve supportare. Questa variabile viene compilata in base alle funzionalità configurate nella pipeline di distribuzione.
Se la tua implementazione non supporta le funzionalità in questo elenco, ti consigliamo che l'implementazione non vada a buon fine durante il rendering.
Per i deployment standard, questo campo è vuoto. Per i deployment canary, il valore è
CANARY
. Se il valore fornito da Cloud Deploy èCANARY
, l'azione di rendering viene richiamata per ogni fase nella versione canary. La percentuale canary per ogni fase è fornita nella variabile di ambienteCLOUD_DEPLOY_PERCENTAGE_DEPLOY
.CLOUD_DEPLOY_PERCENTAGE_DEPLOY
La percentuale di deployment associata a questa operazione di rendering. Se la variabile di ambiente
CLOUD_DEPLOY_FEATURES
è impostata suCANARY
, l'azione di rendering personalizzata viene richiamata per ogni fase e questa variabile è impostata sulla percentuale canary per ogni fase. Per i deployment standard e per i deployment canary che hanno raggiunto la fasestable
, questo valore è100
.CLOUD_DEPLOY_STORAGE_TYPE
Il fornitore di spazio di archiviazione. Sempre
GCS
.CLOUD_DEPLOY_INPUT_GCS_PATH
Il percorso Cloud Storage per l'archivio del file di rendering scritto al momento della creazione della release.
CLOUD_DEPLOY_OUTPUT_GCS_PATH
Il percorso di Cloud Storage in cui si prevede che il container di rendering personalizzato carichi gli artefatti da utilizzare per il deployment. Tieni presente che l'azione di rendering deve caricare un file denominato
results.json
contenente i risultati di questa operazione di rendering. Per maggiori informazioni, consulta la sezione Output dell'azione di rendering.
Output dell'azione di rendering
L'azione di rendering personalizzato deve fornire le informazioni descritte in questa sezione. Le informazioni devono essere incluse nel file dei risultati, denominato results.json
, che si trova nel bucket Cloud Storage fornito da Cloud Deploy.
File o file di configurazione sottoposti a rendering
Un file
results.json
contenente le seguenti informazioni:Un'indicazione dello stato di riuscita o non riuscita dell'azione personalizzata.
I valori validi sono
SUCCEEDED
eFAILED
.(Facoltativo) Eventuali messaggi di errore generati dall'azione personalizzata.
Il percorso Cloud Storage del file o dei file di configurazione visualizzati.
Il percorso di tutti i file di configurazione visualizzati è l'URI completo. Puoi compilarlo in parte utilizzando il valore di
CLOUD_DEPLOY_OUTPUT_GCS_PATH
fornito da Cloud Deploy.Devi fornire il file di configurazione visualizzato, anche se è vuoto. I contenuti del file possono essere qualsiasi cosa e in qualsiasi formato, purché sia utilizzabile dall'azione di deployment personalizzata. Consigliamo che questo file sia leggibile da una persona, in modo che tu e gli altri utenti della tua organizzazione possiate visualizzarlo nello strumento di controllo delle release.
(Facoltativo) Una mappa dei metadati da includere
Il target personalizzato crea questi metadati. Questi metadati vengono archiviati nella release, nel campo
custom_metadata
.
Se devi esaminare il file results.json
, ad esempio per il debug, puoi trovare il relativo URI Cloud Storage nei log di Cloud Build.
Esempio di file dei risultati di rendering
Di seguito è riportato un esempio di output del file results.json
da un'azione di rendering personalizzata:
{
"resultStatus": "SUCCEEDED",
"manifestFile": "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/manifest.yaml",
"failureMessage": "",
"metadata": {
"key1": "val",
"key2": "val"
}
}
Input per il deployment delle azioni
Per azioni di deployment personalizzate, Cloud Deploy fornisce i seguenti input obbligatori, come variabili di ambiente:
CLOUD_DEPLOY_PROJECT
Il progetto Google Cloud in cui viene creata la destinazione personalizzata.
CLOUD_DEPLOY_LOCATION
La regione Google Cloud per il tipo di target personalizzato.
CLOUD_DEPLOY_DELIVERY_PIPELINE
Il nome della pipeline di distribuzione di Cloud Deploy che fa riferimento al target che utilizza il tipo di target personalizzato.
CLOUD_DEPLOY_RELEASE
Il nome della release per cui viene richiamata l'operazione di deployment.
CLOUD_DEPLOY_ROLLOUT
Il nome dell'implementazione di Cloud Deploy a cui è destinato questo deployment.
CLOUD_DEPLOY_TARGET
Il nome della destinazione di Cloud Deploy che utilizza il tipo di destinazione personalizzato.
CLOUD_DEPLOY_PHASE
La fase di implementazione a cui corrisponde il deployment.
CLOUD_DEPLOY_REQUEST_TYPE
Per l'azione di deployment personalizzato, il valore è sempre
DEPLOY
.CLOUD_DEPLOY_FEATURES
Un elenco separato da virgole di funzionalità Cloud Deploy che il container personalizzato deve supportare. Questa variabile viene compilata in base alle funzionalità configurate nella pipeline di distribuzione.
Se la tua implementazione non supporta le funzionalità in questo elenco, ti consigliamo che l'implementazione non vada a buon fine durante il rendering.
Per i deployment standard, questo campo è vuoto. Per i deployment canary, il valore è
CANARY
. Se il valore fornito da Cloud Deploy èCANARY
, l'azione di rendering viene richiamata per ogni fase nella versione canary. La percentuale canary per ogni fase è fornita nella variabile di ambienteCLOUD_DEPLOY_PERCENTAGE_DEPLOY
.CLOUD_DEPLOY_PERCENTAGE_DEPLOY
La percentuale di deployment associata a questa operazione di deployment. Se la variabile di ambiente
CLOUD_DEPLOY_FEATURES
è impostata suCANARY
, l'azione di deployment personalizzato viene richiamata per ogni fase e questa variabile è impostata sulla percentuale canary per ogni fase. L'azione di deployment deve essere eseguita per ogni fase.CLOUD_DEPLOY_STORAGE_TYPE
Il fornitore di spazio di archiviazione. Sempre
GCS
.CLOUD_DEPLOY_INPUT_GCS_PATH
Il percorso di Cloud Storage in cui il renderer personalizzato ha scritto i file di configurazione sottoposti a rendering.
CLOUD_DEPLOY_SKAFFOLD_GCS_PATH
Percorso Cloud Storage della configurazione Skaffold sottoposta a rendering.
CLOUD_DEPLOY_MANIFEST_GCS_PATH
Percorso Cloud Storage del file manifest sottoposto a rendering.
CLOUD_DEPLOY_OUTPUT_GCS_PATH
Il percorso della directory Cloud Storage in cui è previsto che il container di deployment personalizzato carichi gli artefatti di deployment. Per maggiori informazioni, consulta Output dell'azione di deployment.
Output dall'azione di deployment
L'azione di deployment personalizzata deve scrivere un file di output results.json
. Questo file deve trovarsi nel bucket Cloud Storage fornito da Cloud Deploy (CLOUD_DEPLOY_OUTPUT_GCS_PATH
).
Il file deve includere quanto segue:
Un'indicazione dello stato di operazione riuscita o non riuscita dell'azione di deployment personalizzato.
Di seguito sono riportati gli stati validi:
SUCCEEDED
FAILED
SKIPPED
(per i deployment canary in cui le fasi canary vengono ignorate per passare direttamente astable
.)
(Facoltativo) Un elenco dei file degli artefatti di deployment, sotto forma di percorsi di Cloud Storage
Il percorso è l'URI completo. La compili in parte utilizzando il valore di
CLOUD_DEPLOY_OUTPUT_GCS_PATH
fornito da Cloud Deploy.I file elencati qui sono compilati nelle risorse di esecuzione del job come artefatti di deployment.
(Facoltativo) Un messaggio di errore, se l'azione di deployment personalizzato non va a buon fine (restituisce uno stato
FAILED
)Questo messaggio viene utilizzato per compilare
failure_message
nell'esecuzione del job per questa azione di deployment.(Facoltativo) Un messaggio Ignora, per fornire ulteriori informazioni se l'azione restituisce uno stato
SKIPPED
.(Facoltativo) Una mappa dei metadati da includere
Il target personalizzato crea questi metadati. Questi metadati vengono archiviati nell'esecuzione del job e nel campo
custom_metadata
al momento dell'implementazione.
Se devi esaminare il file results.json
, ad esempio per il debug, puoi trovare il relativo URI Cloud Storage nei log di rendering della release di Cloud Build.
Esempio di file dei risultati del deployment
Di seguito è riportato un esempio di output del file results.json
da un'azione di deployment personalizzata:
{
"resultStatus": "SUCCEEDED",
"artifactFiles": [
"gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file1.yaml",
"gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file2.yaml"
],
"failureMessage": "",
"skipMessage": "",
"metadata": {
"key1": "val",
"key2": "val"
}
}
Ulteriori informazioni sulle azioni personalizzate
Di seguito sono riportati alcuni aspetti da tenere a mente durante la configurazione e l'utilizzo dei tipi di target personalizzati.
Esecuzione delle azioni personalizzate
Le azioni di rendering e deployment personalizzate vengono eseguite nell'ambiente di esecuzione di Cloud Deploy. Non puoi configurare le azioni personalizzate per l'esecuzione su un cluster Google Kubernetes Engine.
Utilizzo di configurazioni Skaffold remote e riutilizzabili
Come descritto in questo documento, configuri l'azione personalizzata nel file skaffold.yaml
fornito al momento della creazione della release. Tuttavia, puoi anche archiviare le configurazioni Skaffold in un repository Git o in un bucket Cloud Storage e fare riferimento a queste configurazioni dalla tua definizione del tipo di destinazione personalizzata.
In questo modo puoi utilizzare azioni personalizzate definite e archiviate in un'unica posizione condivisa, invece di includere le azioni personalizzate nel file skaffold.yaml
di ogni release.
Target personalizzati e strategie di deployment
Le destinazioni personalizzate sono completamente supportate per i deployment standard.
Cloud Deploy supporta i deployment canary purché il renderer personalizzato e il deployer supporti la funzionalità canary.
Devi utilizzare la configurazione canary personalizzata. Le versioni canary automatiche e automatiche personalizzate non sono supportate.
Target personalizzati e parametri di deployment
Puoi utilizzare i parametri di deployment con target personalizzati. Puoi impostarle nella fase della pipeline di distribuzione, nel target che utilizza un tipo di target personalizzato o nella release.
I parametri di deployment vengono passati ai container di rendering e di deployment personalizzati, come variabili di ambiente, oltre a quelli già forniti.
Esempi di target personalizzati
Il repository cloud-deploy-samples contiene un insieme di implementazioni di target personalizzate di esempio. Sono disponibili i seguenti esempi:
GitOps
Vertex AI
Terraform
Infrastructure Manager
Helm
Ogni esempio include una guida rapida.
Questi esempi non sono un prodotto Google Cloud supportato e non sono coperti da un contratto di assistenza per Google Cloud. Per segnalare bug o richiedere funzionalità in un prodotto Google Cloud, contatta l'assistenza Google Cloud.
Passaggi successivi
Ora che conosci le destinazioni personalizzate, scopri come configurarle e utilizzarle.
Prova la guida rapida: definisci e utilizza un tipo di target personalizzato.
Scopri di più sulla configurazione delle destinazioni di Cloud Deploy.
Scopri di più sugli ambienti di esecuzione di Cloud Deploy.