Descrittore di deploy#

Il descrittore dichiara cosa rilasciare e dove. La CLI lo legge in YAML, l'API lo riceve in JSON: i campi sono gli stessi. I campi sconosciuti sono un errore, così un refuso non viene ignorato in silenzio.

Esempio completo#

YAML (CLI)JSON (API)

apiVersion: manent/v1
id: myapp-1.2.3-test               # opzionale: chiave di idempotenza
application: myapp
environment: test

artifact:
  type: application
  name: myapp
  version: 1.2.3
  source: https://artifacts.example.com/myapp/myapp-1.2.3.tar.gz
  sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

secrets:
  - name: deploy-key
    ref: env:DEPLOY_SSH_KEY

deploy:
  plugin: remote-copy
  targets:
    - host: 192.168.1.10
      port: 22
      user: deploy
  params:
    dest_dir: /opt/myapp/releases
    ssh_key_secret: deploy-key

steps:
  post-test: true

postTest:
  http:
    - url: http://192.168.1.10:8080/health
      expectStatus: 200

{
  "apiVersion": "manent/v1",
  "id": "myapp-1.2.3-test",
  "application": "myapp",
  "environment": "test",
  "artifact": {
    "type": "application",
    "name": "myapp",
    "version": "1.2.3",
    "source": "https://artifacts.example.com/myapp/myapp-1.2.3.tar.gz"
  },
  "secrets": [{"name": "deploy-key", "ref": "env:DEPLOY_SSH_KEY"}],
  "deploy": {
    "plugin": "remote-copy",
    "targets": [{"host": "192.168.1.10", "port": 22, "user": "deploy"}],
    "params": {"dest_dir": "/opt/myapp/releases", "ssh_key_secret": "deploy-key"}
  },
  "steps": {"post-test": true},
  "postTest": {"http": [{"url": "http://192.168.1.10:8080/health", "expectStatus": 200}]}
}

Campi#

Identificazione#

Campo	Obbligatorio	Descrizione
`apiVersion`	sì	Sempre `manent/v1`.
`id`	no	ID del deploy e chiave di idempotenza: lo stesso `id` non viene eseguito due volte. Un `id` già usato per un'altra applicazione, un altro artefatto o un altro ambiente viene rifiutato. Non ammesso con `schedule.cron`.
`tenant`	no	Sceglie tra i tenant che elencano l'applicazione; obbligatorio solo se più di uno la elenca. Non assegna mai l'applicazione: decide il registro.
`application`	sì	Nome dell'applicazione.
`environment`	sì	Ambiente di destinazione (es. `test`, `prod`).

id, application, environment e il nome della schedule diventano nomi di directory e chiavi: sono ammessi lettere, cifre, ., _, : e -, con iniziale alfanumerica e al massimo 128 caratteri.

`artifact`#

Campo	Obbligatorio	Descrizione
`type`	sì	Tipo di artefatto (es. `application`). Determina quali plugin possono gestirlo.
`name`	sì	Nome dell'artefatto.
`version`	no	Versione, riportata ai plugin e nei log.
`source`	sì	Da dove scaricarlo: percorso locale, `file://`, `http(s)://` oppure un'immagine di container `oci://registry/repository:tag` (vedi il plugin container).
`sha256`	no	Hash atteso, verificato dallo step `qa`.

`secrets`#

Elenco di segreti con un nome logico e un riferimento. Il valore non compare mai nel descrittore: viene letto dal worker solo quando serve.

secrets:
  - name: deploy-key
    ref: env:DEPLOY_SSH_KEY      # variabile d'ambiente del worker
  - name: db-password
    ref: file:/run/secrets/db    # contenuto di un file sul worker

Schemi supportati: env:, file: e, se configurato, vault: (es. vault:secret/data/myapp/prod#ssh_key). Vedi Segreti e sorgenti degli artefatti. I nomi logici devono essere univoci. I plugin, i callback e i parametri riferiscono i segreti per nome logico (es. ssh_key_secret: deploy-key).

`deploy`#

Campo	Descrizione
`plugin`	Plugin da usare. Se assente, la policy sceglie il primo plugin attivo che supporta `artifact.type`.
`targets`	Destinazioni: `host` (obbligatorio), `port`, `user`, `labels` (etichette; `region` e `az` sono usate dai rilasci a ondate).
`params`	Parametri specifici del plugin, come mappa di stringhe.
`targetsFrom`	Target presi dagli export `targets` degli import: `[{import: infra, export: vms}]`. Vedi Export e import.
`paramsFrom`	Parametri presi dagli export degli import: `{db_host: {import: infra, export: db_host}}`.
`parallel`	Target di un lotto che il plugin aggiorna nello stesso momento: un numero o una percentuale del lotto (default `1`, uno dopo l'altro), entro `plugins.<nome>.max_parallel` e `descriptor_policy.max_parallel`. Vedi target in parallelo.

Tutti questi campi possono arrivare dalla configurazione di ambiente: il descrittore può solo aggiungere ciò che non vi è definito. Dopo la fusione deve esserci almeno un target.

`steps`#

Attiva o disattiva gli step opzionali per nome. Vedi Pipeline e step.

`stepParams`#

Parametri degli step personalizzati, per step (stepParams: {db-migrate: {database: shop}}). Di norma arrivano dalla configurazione di ambiente: il descrittore può impostare solo quelli ammessi da descriptor_policy.step_params, e ogni valore deve rispettare il pattern dichiarato dallo step.

`postTest`#

Controlli HTTP eseguiti dallo step post-test:

postTest:
  http:
    - url: https://myapp.example.com/health
      expectStatus: 200   # default 200

`schedule`#

Pianifica il deploy invece di eseguirlo subito: at per un orario singolo, cron per i deploy ricorrenti. Vedi Deploy pianificati.

`dryRun`#

true esegue il deploy in simulazione. Non ammesso con schedule. Vedi Dry-run.

`callbacks`#

Fino a 5 endpoint HTTP che ricevono l'esito degli step e del deploy. Vedi Callback.

`rollback`#

Attiva o disattiva il rollback automatico, nei limiti della policy del tipo di artefatto. Vedi Rollback.

rollback:
  enabled: true              # default: quello della policy del tipo di artefatto
  on: [deploy, post-test]    # step il cui fallimento avvia il rollback
  locator: plugin            # come individuare la release a cui tornare

`rollout`#

Strategia di rilascio a ondate: ondate, tempo di osservazione, health gate, comportamento in caso di fallimento. Di norma sta nella configurazione di ambiente; nel descrittore è ammessa solo se l'ambiente non ne definisce una, o se è identica.

`after` e `afterTimeout`#

ID dei deploy che devono riuscire prima che questo parta, e l'attesa massima (default 24h). Fino ad allora il deploy è WAITING_DEPENDENCY e non occupa uno slot della coda dell'ambiente. Vedi Catene di deploy.

after: [shop-db-42-prod]
afterTimeout: 2h

`imports` ed `exports`#

imports sono i deploy di cui questo deploy legge gli export all'avvio (deployment: <id>, tra gli after, o current: {application, environment}, la release in esercizio); exports sono gli output che questo deploy offre agli altri (from: <step>.<chiave>, format: string|targets, pattern). Vedi Export e import.

imports:
  infra: {deployment: infra-42}
exports:
  fqdn: {from: deploy.fqdn, pattern: '[a-z0-9.-]+'}

`freezeOverride`#

Motivo con cui il deploy deroga a una finestra di freeze (al massimo 500 caratteri, non ammesso con schedule.cron). Richiede il permesso deployment.freeze-override ed è registrato nell'audit.

freezeOverride: "INC-4711: correzione del calcolo IVA"

`config`#

Revisione della configurazione di ambiente, con il provider git e solo se descriptor_policy.config_ref lo ammette: il nome di un ref o lo SHA di un commit raggiungibile dai ref ammessi. Senza, il ref di default.

config:
  ref: refs/tags/env-42

Validazione#

Il descrittore viene validato appena letto, sia dalla CLI sia dall'API. Gli errori vengono restituiti tutti insieme, non solo il primo. Alcuni controlli avvengono più tardi, perché dipendono da altro:

i conflitti con la configurazione di ambiente, la presenza di almeno un target e la policy sui descrittori (parametri, segreti e target che il descrittore può aggiungere), all'accodamento (422) e di nuovo nello step config. Se all'accodamento la configurazione di ambiente non è raggiungibile, la verifica resta allo step config;
le regole di governance (freeze, promozione obbligatoria, approvazioni), all'accodamento; il freeze anche nello step config;
la sorgente dell'artefatto, all'accodamento e al download (artifacts.sources);
i permessi dell'utente sull'applicazione e sull'ambiente, all'accodamento;
la risolvibilità dei segreti, nello step secrets;
la policy sugli URL dei callback e la policy di rollback, all'accodamento. La decisione di rollback definitiva è presa nello step config, dopo la fusione con la configurazione di ambiente.

manent validate esegue la validazione e mostra il deploy effettivo senza accodare nulla.

Descrittore di deploy#

Esempio completo#

Campi#

Identificazione#

artifact#

secrets#

deploy#

steps#

stepParams#

postTest#

schedule#

dryRun#

callbacks#

rollback#

rollout#

after e afterTimeout#

imports ed exports#

freezeOverride#

config#