Aller au contenu principal

Environnements et promotion

La plateforme permet de déplacer les agents et les flux de travail entre les différentes étapes (développement, préproduction, production) et entre les instances de la plateforme (par exemple, Tietai cloud vers un hôpital). Elle est accessible via Tiet · Hub → Platform → Environments et l'API REST. Veuillez lire la section suivante au préalable, car trois éléments du produit contiennent les termes « environnement » ou « déploiement ».

Quelle version cette page décrit-elle ?

La navigation ci-dessous correspond à l'interface feat/849-light-rebrand à 3a99cf9. La page Environnements se trouve sous Tiet · Hub → Platform ; sa route reste /studio/environments.

Ce que vous pouvez utiliser aujourd'hui​

OùCe que cela fait
Tiet · Studio → Workflows → Builder → Deploy menuDéfinit le statut d'un pipeline à deployed:<environment slug> pour l'environnement sélectionné et exporte au format JSON ou YAML. Aucune vérification de hachage, demande d'approbation ni accusé de réception n'est effectué.
Admin Console → Platform → EnvironmentsGère les environnements d'organisation dans le service d'authentification : nom, description, icône, région, nom du cluster, indicateur par défaut et variables. Il ne comporte ni routes, ni politiques, ni approbations, ni autorisations de publication.
Tiet · Hub → Platform → Environments (/studio/environments)La page relative aux environnements décrits ici : environnements avec politiques, routes, manifestes, sources de confiance, approbations et conservation des traces. Voir ci-dessous.
L'API REST décrite sur cette pageLe même système, pour les scripts : environnements, routes, manifestes, versions signées, promotion, approbations et accusés de réception.

La ligne de commande hydra fournie ne contient aucune commande export, diff, apply, deploy, env ou approvals Utilisez la page ou l'API.

La page Environnements​

Toute personne disposant des droits access:hydra peut la lire. Toute modification nécessite les droits de superutilisateur ou l'autorisation Manage Environments (manage:hydra.environment) ; sans cela, la page affiche You can view environments. Changing them needs the Manage Environments permission.. La page possède un sélecteur Run in (voir Tiet · Studio Constructeur) et, pour les administrateurs, les boutons Register remote instance et New environment Ses onglets :

LanguetteCe qu'il contient
Environments (n)Un tableau avec Environment, Slug, Rank, Status (badges Default, Protected, Entry, Remote, Archived) et, pour les gestionnaires : Actions : monter ou descendre, Deploy to l’environnement, What runs in : l’environnement, Variables of : l’environnement local, Test connection et Reconnect : l’environnement distant, Edit, Archive. L’environnement par défaut ne peut pas être archivé. Show archived (n) liste les environnements archivés.
Routes (n)L'éditeur Promotion graph et Routes : Route from, Route to, Save routes No routes: every environment is an entry environment.. Le serveur refuse les boucles, les auto-routes et les routes vers des environnements inconnus ou archivés.
Agents & workflowsImport agents and workflows à partir des fichiers YAML manifestes (avec I reviewed the permission findings et Create drafts), et une liste d'agents et de flux de travail avec un téléchargement par manifeste.
Trusted sourcesInstances sources qui ont tenté de se déployer ici, avec Key fingerprint, Trust et Revoke.
ApprovalsVersions en attente d'approbation, avec Approve et Reject.
RetentionDurée de conservation des données de traçage (en jours) par étendue. Nécessite l'autorisation « Gérer la conformité » pour être modifiée.

La boîte de dialogue New environment et Edit comporte Name, Slug, Description, Colour et Rank (ordre d'affichage uniquement ; les routes déterminent la promotion) et une section Policy : Protected, Allow direct deploy, Allow draft execution, Default environment, Promotion into this environment (Approvers required, Four-eyes (requester cannot approve), Approver permission, Require a change reference, Approval expires after (hours), Required compliance gate), Rollback (authentification par quatre yeux) et Reason for the change. Register a remote instance demande les API URL, Name here, Slug here, Environment on the target et Token issued by the target, puis enregistre l'empreinte de la clé présentée par la cible. La boîte de dialogue de déploiement pour un environnement distant demande les Promote from (Choose the environment the versions come from), Reason et Change reference. J'ai consulté ces écrans dans le code source ; je ne les ai pas exécutés.

Le menu Déploiement du générateur​

Le bouton Deploy de la barre d'outils Builder ouvre un menu dont l'en-tête est « Version du pipeline · environnement du projet actif ».

ArticleÉtat
*Deploy version to environment * (un par autre environnement actif ; No other environments. si aucun)Actif. Enregistre le pipeline, puis définit son statut à deployed:<slug>.
Export as JSON, Export as YAMLActif
Enable schedule, Enable trigger, Push to external platform instance, Deployment historyAffiché mais désactivé
Les pipelines ne sont pas des artefacts de mise en production.

Un pipeline enregistré depuis le Builder n'est pas une version publiée. Il s'exécute uniquement dans les environnements dont la politique autorise l'exécution des brouillons. La promotion versionnée et vérifiée par hachage ci-dessous s'applique aux versions de workflow et aux agents publiés.

Concepts​

TermeSignification
EnvironmentUne étape nommée de votre organisation. « Local » désigne une étape sur cette instance ; « remote » désigne une autre instance de plateforme sur laquelle vous déployez par push.
Default environmentLorsqu'une instruction run s'exécute sans spécifier aucun nom.
RouteUn chemin de promotion autorisé, par exemple development → staging. Un environnement comportant des routes d'accès n'est accessible que par promotion.
Policyprotected, allow_direct_deploy, allow_draft_execution et règles de promotion : min_approvers, four_eyes, approver_permission, require_change_reference, approval_ttl_hours.
ManifestDocument YAML ou JSON portable pour une version d'agent ou de workflow. Il fait référence aux autres éléments par slug@version et ne contient aucune information d'identification. Son algorithme SHA-256 identifie la version.
ReleaseUn ensemble de manifestes signés, destinés à un environnement donné, indiquant le demandeur, le motif et la référence de la modification. Chaque version est signée, même au sein d'une même instance.
ReceiptConfirmation signée par la cible de sa demande.

Deux règles expliquent la plupart des comportements :

  1. Un environnement dont la politique autorise l'exécution de versions préliminaires exécute la version demandée. Tout autre environnement exécute exactement la version qui y est déployée.
  2. Une version n'est promue que depuis un environnement qui l'exécute, avec le même hachage.

Environnements par défaut​

Une organisation sans environnement reçoit ces éléments lors de la première utilisation (pkg/deployenv/defaults.yaml). Tout ceci peut être modifié ultérieurement.

EnvironnementDéfautProtégéDéploiement directExécution du projetAutorisation requise pour entrer
developmentOuiNonOuiOuiaucun
stagingNonNonNon1 (le déploiement direct est désactivé)
productionOuiNonNon1, quatre yeux, changement de référence requis

Itinéraires : development → staging → production.

Parcours de promotion : du développement à la mise en production

Exportez un manifeste et effectuez un test à blanc.​

Tous les chemins sont relatifs à la racine de l'API de l'instance, /api sur hydra-server. Authentifiez-vous avec un jeton de connexion ou un jeton d'API disposant des autorisations requises.

# list exportable workflows (needs read:hydra.builder or scope manifests:read)
curl -s "$HYDRA/api/manifests/workflows" -H "Authorization: Bearer $TOKEN"

# one manifest as YAML; the hash is in the X-Hydra-Manifest-SHA256 header
curl -si "$HYDRA/api/manifests/workflows/triage/1.0.0" -H "Authorization: Bearer $TOKEN"

# plan an apply without writing anything
curl -s -X POST "$HYDRA/api/manifests/apply?dry_run=true" \
-H "Authorization: Bearer $TOKEN" --data-binary @triage.yaml

GET /api/manifests/{agents|workflows}/{slug}[/{version}] accepte ?format=json. POST /api/manifests/apply accepte également mode=deploy|draft, environment=<slug> et review_token=<slug>:<token>. Un déploiement via ce point de terminaison est autorisé uniquement dans l'environnement local par défaut de l'organisation, et seulement si celui-ci autorise le déploiement direct. Chaque élément est planifié au préalable ; si un élément est refusé, aucune écriture n'est effectuée. La taille du corps de la requête est limitée à 4 Mio.

Déployer ou promouvoir dans un environnement​

POST /api/environments/{slug}/deployments fonctionne en environnement local et distant.

curl -s -X POST "$HYDRA/api/environments/staging/deployments" \
-H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
-d '{
"from": "development",
"items": [{"kind": "workflow", "slug": "triage", "version": "1.0.0"}],
"reason": "QA sign-off",
"change_reference": "CR-1234",
"dry_run": true
}'

La réponse comporte un status (planned pour un essai à blanc), un release et une entrée par élément avec un action (create, update, unchanged ou refused). Envoyez le même corps avec "dry_run": false pour le déploiement.

Ce qui est vérifié :

VérifierÉchec
Vous pouvez exporter chaque article403 cannot export ...
Un itinéraire from → target existe, et from est attribué lorsque les itinéraires mènent à la cible.422 there is no promotion route ..., environment ... is reached by promotion only
Chaque élément est déployé dans la from, à la même version409 ... is not deployed in ..., ... runs <slug>@<version>, not ...
Le hachage correspond à ce que from exécute409 ... differs from what ... runs
Une référence de modification, lorsque la politique l'exige422 environment "..." requires a change reference
L'instance possède une clé de signature503 this instance has no signing key (...); it cannot sign releases
L'environnement est actif409 archivés

Une promotion interne est refusée (422). Les vérifications sont relancées lorsqu'une libération en attente est finalement approuvée. Si des modifications ont été apportées pendant l'attente, la libération est refusée et rien ne bouge.

Envoi signé d&#39;une instance source vers une instance cible, avec approbation et réception

Environnements distants​

Un environnement distant est enregistré avec POST /api/environments et "location": "remote", un objet remote (base_url, key_id, environment) et un token. Chaque instance a besoin d'une clé de signature Ed25519 (HYDRA_INSTANCE_SIGNING_KEY_FILE) et ENCRYPTION_MASTER_KEY. GET /api/instance est public et affiche l'identifiant de l'instance et l'empreinte de la clé (key_id) ; les deux administrateurs comparent les empreintes hors bande.

La source envoie la version signée à la cible (POST /api/deployments/receive à l'aide d'un jeton d'autorisation (deployments:write). La cible n'accepte que les clés sources approuvées par son administrateur (GET /api/instance/trust, puis POST /api/instance/trust/{id}/trust ou revoke). La première tentative d'envoi depuis une clé inconnue renvoie pending_trust ; approuvez la clé sur la cible, puis redéployez. Les informations d'identification ne sont jamais transmises lors de la mise en production : la cible utilise ses propres variables et connecteurs.

Statuts de promotion​

Sur la source, la réponse de déploiement et l'enregistrement de version utilisent ces statuts :

StatutSignification
plannedEssai à blanc uniquement
pending_trustLa cible ne fait pas encore confiance à la clé source.
pending_approvalEn attente d'approbation (HTTP 202)
appliedApplication appliquée ; pour une cible distante, un accusé de réception a été vérifié.
refusedUne vérification a échoué ; rien n'a bougé.
unknownLa requête n'a pas abouti. Vérifiez les applications exécutées sur la cible avant de redéployer.

Sur la cible, la boîte de réception des approbations (GET /api/deployments/pending[?status=]) utilise pending, applied, rejected, expired et failed.

Approbations​

Une mise en production est bloquée lorsque la politique de l'environnement cible exige des approbations, n'autorise pas le déploiement direct ou est protégée. Dans les deux derniers cas, au moins une approbation est requise.

curl -s "$HYDRA/api/deployments/pending?status=pending" -H "Authorization: Bearer $JWT"
curl -s -X POST "$HYDRA/api/deployments/pending/$SOURCE_INSTANCE/$RELEASE_ID/approve" \
-H "Authorization: Bearer $JWT" -H "Content-Type: application/json" -d '{"comment":"Reviewed"}'

Règles appliquées par le serveur :

  • Les approbateurs détiennent l'autorisation d'approbateur de l'environnement (par défaut approve:hydra.promotion).
  • Chaque personne décide une fois (409 you already decided on this release; another approver is needed).
  • Le demandeur ne peut pas approuver (403 the requester cannot approve their own release). Les jetons d'API ne peuvent pas approuver (403 releases are approved by people, not API tokens).
  • La dernière approbation requise permet de revérifier et d'appliquer la libération. Tout rejet y met fin.
  • Une libération en attente expire après la période de la politique approval_ttl_hours ; la valeur par défaut est 72.

Pour une cible distante, la source collecte le résultat avec POST /api/environments/{slug}/releases/{id}/refresh. Consultez ce qui s'exécute dans un environnement avec GET /api/environments/{slug}/deployments et l'historique des envois avec GET /api/environments/{slug}/releases.

Retour​

Il n'est pas possible de revenir en arrière. Pour les workflows, redéployez la version publiée précédente via la procédure d'approbation habituelle. Pour les agents, une instance ne possède qu'une seule version active ; publiez donc une nouvelle version d'agent avec le contenu précédent et déployez-la.

Limites​

  • Les exécutions lancées par des déclencheurs entrants (par exemple HL7 via MLLP) et d'autres chemins internes ne dépendent pas de l'environnement. Elles utilisent la configuration de l'instance et les versions actuelles.
  • Un agent ne peut être déployé en environnement local que dans sa version active. Toute modification ultérieure est considérée comme une dérive, et les exécutions de cet agent dans cet environnement sont refusées jusqu'à un nouveau déploiement.
  • En mode push uniquement : la cible doit être accessible depuis la source via HTTPS.
  • manage:hydra.environment, requis pour gérer les environnements et déployer, et l'autorisation d'approbateur par défaut approve:hydra.promotion ne figurent pas dans le catalogue d'autorisations du service d'authentification sur dev (j'ai effectué une recherche), donc en pratique seuls les superutilisateurs peuvent gérer les environnements.
  • Un contrôle de déploiement (la règle required_gate_profile, affichée comme Required compliance gate) peut bloquer ou refuser un déploiement local. Un environnement contrôlé refuse les déploiements provenant d'une autre instance (environment "..." has a release gate; releases into it are deployed on this instance, not received, 422). J'ai lu cela dans le code source, mais je ne l'ai pas exécuté.

Quelque chose n'est pas clair ? Envoyez vos commentaires sur la documentation par courriel.