Limitare il comportamento di deployment utilizzando i criteri

Questo documento descrive come utilizzare le policy di deployment per limitare le azioni manuali o automatiche della pipeline di distribuzione.

Una policy di deployment è una risorsa Cloud Deploy che puoi utilizzare per limitare le azioni manuali o automatiche su una pipeline di distribuzione o un target selezionato (o su tutte le pipeline o tutti i target).

Quali comportamenti possono essere limitati?

Puoi creare policy di deployment per limitare o impedire a Cloud Deploy di eseguire determinate azioni sui rollout. Ad esempio, una policy può impedire la creazione di implementazioni per una determinata pipeline di distribuzione durante un periodo di tempo specificato. Ad esempio, puoi utilizzare questa opzione per le limitazioni stagionali.

Come vengono valutate e applicate le norme

Per qualsiasi azione manuale o automatica, Cloud Deploy esegue le seguenti operazioni:

1. Controlla le autorizzazioni di Identity and Access Management.

   Se l'utente o il account di servizio non dispone di autorizzazioni IAM adeguate, l'azione non viene eseguita e non è necessario valutare le norme di deployment.

2. Controlla se esiste una policy applicabile per la pipeline di destinazione o di pubblicazione e, in caso affermativo, la valuta.

   • Cloud Deploy valuta l'azione intrapresa per verificare se questa regola è applicabile.

     ovvero, il tipo di azione e l'invoker corrispondono alla policy?

   • Cloud Deploy controlla gli intervalli di date e ore definiti per il criterio per verificare se è in vigore al momento della richiesta.

   • Se il criterio è in vigore e la regola si applica alla pipeline di distribuzione o al target e all'azione, la regola viene applicata e l'azione viene bloccata.

Requisiti e limitazioni

• Ogni policy deve avere almeno un selettore.

• Ogni policy deve avere almeno una regola.

  Tutti gli ID regola devono essere univoci all'interno di una policy di deployment.

• Ogni regola deve avere almeno un timeWindows e, all'interno di questo timeWindows, deve essere presente un oneTimeWindows o un weeklyWindows.

  Per ulteriori dettagli sull'utilizzo dei blocchi di tempo, vedi Date e orari.

• Puoi avere al massimo 1000 policy di deployment per progetto/posizione.

Ruoli e autorizzazioni Identity and Access Management richiesti

Oltre alle autorizzazioni necessarie per eseguire qualsiasi pipeline di distribuzione Cloud Deploy e per eseguire le attività che sarebbero limitate dalle norme, sono necessarie diverse autorizzazioni per eseguire determinate operazioni sulla risorsa policy:

• clouddeploy.deployPolicies.create
• clouddeploy.deployPolicies.delete
• clouddeploy.deployPolicies.get
• clouddeploy.deployPolicies.list
• clouddeploy.deployPolicies.update
• clouddeploy.deployPolicies.override

Queste autorizzazioni sono incluse nel ruolo roles/clouddeploy.policyAdmin. Inoltre, il ruolo roles/clouddeploy.policyOverrider include l'autorizzazione .override.

Crea una policy di deployment

La creazione di una risorsa deploy-policy prevede i seguenti passaggi:

1. Crea un file YAML con la configurazione della policy di deployment.

   La configurazione include un'intestazione che identifica la risorsa come un criterio di deployment. Il campo name è obbligatorio.

    apiVersion: deploy.cloud.google.com/v1
    kind: DeployPolicy
    metadata:
      name: 
    description: 
   

2. Aggiungi un riferimento alle pipeline di distribuzione e alle destinazioni a cui si applica il criterio (selectors).

   Per ulteriori informazioni sui selettori di criteri e su come configurarli, consulta Implementare i selettori di criteri e Riferimento allo schema di configurazione.

3. Aggiungi uno o più rules dei criteri.

   Ogni regola descrive una restrizione e le circostanze in cui viene applicata. Per ulteriori informazioni sulle regole dei criteri e su come configurarle, consulta Deploy policy rules e il Configuration schema reference.

4. Applica il file per creare la policy:

   gcloud deploy apply --file=FILENAME \
                        --region=REGION \
                        --project=PROJECT_ID
   

   dove FILENAME è il nome del file YAML contenente la definizione di DeployPolicy, REGION è la regione in cui vuoi creare la risorsa policy di deployment e PROJECT_ID è il progetto in cui vuoi creare la risorsa.

Le pipeline di distribuzione o i target a cui viene fatto riferimento sono ora limitati in base alle regole nella risorsa deploy-policy.

Selettori delle policy di deployment

I selettori, definiti nelle configurazioni dei criteri di deployment, determinano quali pipeline di distribuzione e quali target sono interessati da una determinata regola.

Un selettore è definito in una sezione selectors nella configurazione della policy di deployment, come proprietà di primo livello:

selectors:
- deliveryPipeline:
    id:
    labels:
  target:
    id:
    labels:

In questo file YAML di configurazione, deliveryPipeline.id prende il nome della pipeline di distribuzione e target.id prende il nome della destinazione (in entrambi i casi, metadata.name).

Puoi utilizzare id: * per selezionare tutte le pipeline di pubblicazione o tutti i target. Tieni presente che * è un valore di campo speciale per selezionare tutti i valori. I caratteri jolly arbitrari non sono supportati. Puoi anche utilizzare le etichette per abbinare pipeline di pubblicazione o target o entrambi.

All'interno di un determinato selettore, gli elementi vengono combinati con l'operatore AND. Più selettori sono combinati con l'operatore OR. ovvero, affinché una determinata richiesta sia limitata dalla policy, deve essere applicata ad almeno un selettore. Tuttavia, all'interno di questo selettore, la richiesta deve corrispondere a tutti gli elementi.

Regole dei criteri di deployment

Ogni policy di deployment include una o più regole della policy, che definiscono l'azione limitata nella pipeline di distribuzione o nella destinazione selezionata. La regola definisce anche in quali circostanze viene applicata.

Sono disponibili le seguenti regole:

• rolloutRestriction

La regola rolloutRestriction impedisce l'esecuzione delle azioni di implementazione specificate sui target selezionati utilizzati dalle pipeline di distribuzione selezionate. Questa regola utilizza una finestra temporale che definisce quando non è possibile creare un rollout per la pipeline di distribuzione e la destinazione selezionate. Consulta la sezione Date e orari per una descrizione di come vengono specificati date e orari nelle regole dei criteri di implementazione.

Le seguenti azioni possono essere limitate mentre la regola è attiva:

• ADVANCE

  Le fasi di implementazione non possono essere avanzate.

• APPROVE

  L'implementazione della promozione non può essere approvata.

• CANCEL

  Le implementazioni non possono essere annullate.

• CREATE

  Non è possibile creare i lanci. Puoi creare una release se una norma impedisce questa azione, ma la release non genererà un lancio.

• IGNORE_JOB

  I job non possono essere ignorati.

• RETRY_JOB

  I job non possono essere riprovati.

• ROLLBACK

  I rollout non possono essere annullati.

• TERMINATE_JOBRUN

  Le esecuzioni dei job non possono essere terminate

  Consulta il Riferimento allo schema di configurazione per la struttura YAML di questa regola.

Date e ore in una regola rolloutRestriction

Configura blocchi di date e ore per specificare intervalli di tempo ripetuti e non ripetuti durante i quali è in vigore la policy di deployment.

Di seguito sono riportati i requisiti per esprimere date e ore:

• Le date sono espresse come yyyy-mm-dd.

• Quando esprimi l'ora del giorno, l'inizio della giornata è 00:00 e la fine della giornata è 24:00.

• Per oneTimeWindows, le date devono includere l'ora. Per weeklyWindows, puoi omettere l'ora del giorno. Se includi startTime, devi includere endTime e viceversa.

  Ad esempio, un blocco solo la domenica sarebbe il seguente:

  - daysOfWeek: [SUNDAY]
    startTime: "00:00"
    endTime: "24:00"
  

  Puoi anche fare quanto segue:

  - daysOfWeek: [SUNDAY]
  

  Ma non questo:

  - daysOfWeek: [SUNDAY]
    startTime: "00:00"
  

• Devi includere un fuso orario nella sezione timeWindows.

  Ad esempio: timeZone: America/New_York.

Finestre temporali non ripetitive

Una finestra temporale non ripetuta inizia e termina in un giorno e un'ora specifici. Utilizza questo valore per qualsiasi periodo di tempo per il quale vuoi limitare le implementazioni.

Le finestre temporali non ripetitive vengono configurate utilizzando una sezione oneTimeWindows.

Intervalli di tempo ripetuti

Una finestra temporale ricorrente descrive un blocco di tempo ricorrente durante il quale vuoi limitare le implementazioni. Ad esempio, potresti utilizzarlo per limitare i rollout nei fine settimana.

Le finestre temporali ripetute vengono configurate utilizzando una sezione weeklyWindows.

Esempi

Questa sezione contiene alcuni esempi di utilizzo di date e ore per configurare quando viene applicata una norma di deployment.

Blocca righe annuale

Se c'è un periodo dell'anno durante il quale vuoi bloccare i rollout, puoi configurare un blocco oneTimeWindows per farlo. Se le date sono prevedibili, di anno in anno, devi comunque utilizzare più blocchi oneTimeWindow.

Il seguente codice YAML mostra una finestra temporale una tantum (non ripetuta) per applicare una policy di deployment per un blocco annuale:

timeWindows:
  timeZone: "America/New_York"
  oneTimeWindows:
  - start: "2024-12-22 17:00"
    end: "2025-01-02 09:00"

Questo file YAML descrive una finestra temporale dal 22 dicembre 2024 alle 17:00 al 2 gennaio 2025 alle 9:00.

Blocco ripetuto del weekend

Il seguente YAML mostra una finestra temporale ripetuta per applicare una policy di deployment che limita i rollout nei fine settimana, da venerdì alle 17:00 fino a lunedì mattina alle 9:00:

timeWindows:
  timeZone: "America/New_York"
  weeklyWindows:
  - daysOfWeek: [FRIDAY]
    startTime: "17:00"
    endTime: "24:00"
  - daysOfWeek: [SATURDAY, SUNDAY]
    startTime: "00:00"
    endTime: "24:00"
  - daysOfWeek: [MONDAY]
    startTime: "00:00"
    endTime: "09:00"

Aggiorna una policy di deployment

L'aggiornamento di una policy di deployment prevede i seguenti passaggi:

1. Modifica il file YAML di configurazione della policy.

   Se hai creato la policy utilizzando la console Google Cloud , puoi ottenere la configurazione YAML selezionando la scheda YAML nella pagina Dettagli policy di deployment. Poi puoi copiare il testo in un file locale e modificarlo.

2. Applica il file per aggiornare la policy:

   gcloud deploy apply --file=FILENAME \
                        --region=REGION \
                        --project=PROJECT_ID
   

   La risorsa della policy di deployment viene aggiornata con la nuova configurazione.

Poiché le policy di deployment vengono valutate quando viene tentata l'azione con limitazioni, tutte queste azioni su tutte le risorse Cloud Deploy sono soggette alla policy aggiornata. ovvero non rimane alcun residuo delle limitazioni precedenti. Ad esempio, se hai un blocco restrictRollouts per l'intero mese di dicembre e il 14 dicembre aggiorni la norma in modo che la limitazione termini il 15 dicembre, i rollout non vengono più bloccati dopo il 15 dicembre.

Eseguire l'override di una policy di deployment

Se necessario, puoi ignorare una policy di implementazione. Ad esempio, se si verifica un problema con un deployment in produzione e devi eseguire il rollback, ma esiste una norma di deployment che impedisce qualsiasi implementazione, puoi ignorare la norma per eseguire il rollback dell'implementazione errata.

Per eseguire l'override di una policy di deployment, devi disporre dell'autorizzazione IAM clouddeploy.deployPolicies.override.

Puoi eseguire l'override della policy da gcloud CLI o utilizzando la consoleGoogle Cloud :

console

1. Nella Google Cloud console, prova a eseguire un'azione bloccata da un criterio.

   Viene visualizzata una finestra di dialogo che indica che l'azione è bloccata da un criterio di deployment. Questa finestra di dialogo include un link alle norme specifiche che impediscono questa azione.

2. Nel campo di testo fornito, digita il nome della policy e fai clic su Tenta di ignorare le policy.

   Se hai l'autorizzazione per ignorare la policy, Cloud Deploy ora esegue l'azione.

gcloud CLI

Per ignorare una policy di deployment utilizzando gcloud CLI, aggiungi --override-deploy-policies al comando per qualsiasi azione che verrebbe impedita da questa policy. Ad esempio, il seguente comando promuove una release, ignorando una specifica policy di deployment che altrimenti impedirebbe la promozione:

 gcloud deploy releases promote --release=my-release-001 \
   --project=my-policy-testing-project \
   --region=us-central1 \
   --delivery-pipeline=my-pipeline \
   --to-target=prod-target \
   --override-deploy-policies=my-deploy-policy

Eliminare una policy di deployment

Per eliminare una policy di deployment:

console

1. Nella console Google Cloud , vai alla pagina Policy di deployment di Cloud Deploy.

   Apri la pagina Deploy delle policy

   La pagina include un elenco delle policy di deployment disponibili nel tuo progetto attuale, se presenti.

2. Seleziona il pulsante Azioni per il criterio che vuoi eliminare e fai clic su Elimina criterio di deployment.

3. Conferma l'eliminazione digitando il nome della policy di deployment e fai clic su Conferma.

   La norma è stata eliminata e ora puoi eseguire una qualsiasi delle azioni che la norma limitava.

gcloud CLI

Per eliminare una policy di deployment utilizzando gcloud CLI, esegui il seguente comando:

 gcloud deploy deploy-policies delete \
    --project=[PROJECT] \
    --region=[REGION] \
    [POLICY_NAME]

Sostituisci quanto segue:

• [POLICY_NAME]

  Il nome del criterio definito nel file di configurazione dei criteri.

• [PROJECT]

  L'ID progetto del progetto Google Cloud in cui hai creato la policy di deployment.

• [REGION]

  La regione in cui hai creato il criterio di distribuzione.

Dopo aver eliminato la risorsa dei criteri di deployment, le pipeline di distribuzione e le destinazioni interessate non sono più soggette ai criteri e non saranno limitate a meno che non siano interessate da altri criteri di deployment.

Logging della policy di deployment

Quando viene valutato un criterio di deployment, vengono create voci di log della piattaforma per le seguenti azioni:

• Valutazione delle norme

  I log della piattaforma vengono scritti quando una richiesta viene valutata e viola le norme. Un log viene scritto anche quando la policy viene violata da una richiesta, ma la richiesta è consentita perché la policy è sospesa o è stata ignorata. Nessun log viene scritto quando la richiesta viene concessa perché la policy non viene violata.

• Errore di notifica Pub/Sub in caso di modifica di una risorsa di criteri di deployment.

Passaggi successivi

• Per maggiori dettagli sulla configurazione delle policy di deployment, consulta lo schema del file di configurazione.

• Scopri di più sull'automazione del deployment di Cloud Deploy.