Medio ambiente y promoción
La plataforma permite mover agentes y flujos de trabajo entre etapas (desarrollo, pruebas, producción) y entre instancias de la plataforma (por ejemplo, de la Tietai a un hospital). Se puede usar a Tiet · Hub → Platform → Environments de la API REST. Lea primero la siguiente sección, ya que tres elementos distintos del producto incluyen la palabra "entorno" o "despliegue".
La navegación que aparece a continuación coincide con el frontend feat/849-light-rebrand en 3a99cf9. La página de Entornos está debajo de Tiet · Hub → Platform; su ruta sigue siendo /studio/environments.
Lo que puedes usar hoy
| Dónde | Lo que hace |
|---|---|
| Tiet · Studio → Workflows → Builder → Deploy menú | Establece el estado de una canalización en deployed:<environment slug> para el entorno seleccionado y exporta en formato JSON o YAML. No verifica hashes, no solicita aprobación ni registra recibos. |
| Admin Console → Platform → Environments | Gestiona los entornos de la organización en el servicio de autenticación: nombre, descripción, icono, región, nombre del clúster, indicador predeterminado y variables. No tiene rutas, políticas, aprobaciones ni versiones. |
Tiet · Hub → Platform → Environments (/studio/environments) | La página para los entornos descritos aquí: entornos con políticas, rutas, manifiestos, fuentes confiables, aprobaciones y retención de trazas. Véase a continuación. |
| La API REST descrita en esta página | El mismo sistema, para los scripts: entornos, rutas, manifiestos, versiones firmadas, promoción, aprobaciones y recibos. |
La línea de comandos hydra incluida no tiene los comandos export, diff, apply, deploy, env o approvals Utilice la página o la API.
La página de Entornos
Todos con access:hydra pueden leerlo. Cambiar cualquier cosa requiere superusuario o el permiso Manage Environments (manage:hydra.environment); sin él, la página dice You can view environments. Changing them needs the Manage Environments permission.. La página tiene un selector Run in (ver Tiet · Studio Builder) y, para los administradores, los botones Register remote instance y New environment Sus pestañas:
| Pestaña | Lo que contiene |
|---|---|
| Environments (n) | Una tabla con Environment, Slug, Rank, Status (insignias Default, Protected, Entry, Remote, Archived) y, para los administradores, Actions: subir o bajar, Deploy to el entorno, What runs in él, Variables of él (entornos locales), Test connection y Reconnect (entornos remotos), Edit, Archive. El entorno predeterminado no se puede archivar. Show archived (n) enumera los archivados. |
| Routes (n) | El editor Promotion graph y Routes: Route from, Route to, Save routes No routes: every environment is an entry environment.. El servidor rechaza ciclos, rutas propias y rutas a entornos desconocidos o archivados. |
| Agents & workflows | Import agents and workflows de los archivos YAML de manifiesto (con I reviewed the permission findings y Create drafts), y una lista de agentes y flujos de trabajo con una descarga por manifiesto. |
| Trusted sources | Instancias de origen que intentaron implementarse aquí, con Key fingerprint, Trust y Revoke. |
| Approvals | Lanzamientos pendientes de aprobación, con Approve y Reject. |
| Retention | Registro de retención de carga útil en días por ámbito. Se requiere el permiso de Gestionar cumplimiento para realizar cambios. |
El diálogo New environment y Edit tiene Name, Slug, Description, Colour, Rank (solo orden de visualización; las rutas deciden la promoción) y una sección 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 (cuatro ojos) y Reason for the change. Register a remote instance solicita API URL, Name here, Slug here, Environment on the target y Token issued by the target, luego fija la huella digital de la clave que presenta el objetivo. El diálogo de despliegue para un entorno remoto solicita Promote from (Choose the environment the versions come from), un Reason y un Change reference. Leí estas pantallas en el código fuente; no las ejecuté.
Menú de implementación del constructor
El botón Deploy de la barra de herramientas del Generador abre un menú con el encabezado " Versión de la canalización · entorno del proyecto activo ".
| Artículo | Estado |
|---|---|
*Deploy version to environment * (uno por cada entorno activo; No other environments. si no hay ninguno) | Activo. Guarda la canalización y luego establece su estado en deployed:<slug>. |
| Export as JSON, Export as YAML | Activo |
| Enable schedule, Enable trigger, Push to external platform instance, Deployment history | Se muestra pero está deshabilitado |
Una canalización guardada desde el Generador no es una versión versionada. Solo se ejecuta en entornos cuya política permite la ejecución de borradores. La promoción versionada y verificada mediante hash que se describe a continuación se aplica a las versiones y agentes de flujo de trabajo publicados.
Conceptos
| Término | Significado |
|---|---|
| Environment | Una etapa con nombre de su organización. Local es una etapa en esta instancia; remoto es otra instancia de plataforma a la que se implementa mediante push. |
| Default environment | Donde se ejecuta una operación cuando no se especifica ninguna. |
| Route | Una ruta de promoción permitida, por ejemplo development → staging. Un entorno con rutas de acceso solo se alcanza mediante promoción. |
| Policy | protected, allow_direct_deploy, allow_draft_execution y reglas de promoción: min_approvers, four_eyes, approver_permission, require_change_reference, approval_ttl_hours. |
| Manifest | Documento YAML o JSON portátil para una versión de agente o flujo de trabajo. Se refiere a otros elementos mediante el carácter slug@version y no contiene credenciales. Su hash SHA-256 identifica la versión. |
| Release | Un conjunto de manifiestos firmados que se dirigen a un entorno, con información sobre quién lo solicitó, por qué y la referencia del cambio. Cada versión está firmada, incluso dentro de una misma instancia. |
| Receipt | La confirmación firmada por la entidad objetivo de lo que solicitó. |
Dos reglas explican la mayor parte del comportamiento:
- Un entorno cuya política permite la ejecución de borradores ejecuta lo que se solicita. Cualquier otro entorno ejecuta exactamente la versión desplegada en él.
- Una versión se promociona solo desde un entorno que la ejecuta, con el mismo hash.
Entornos predeterminados
Una organización sin entornos obtiene estos en el primer uso (pkg/deployenv/defaults.yaml). Todo se puede editar posteriormente.
| Ambiente | Por defecto | Protegido | Implementación directa | Ejecución del borrador | Se requiere aprobación para ingresar. |
|---|---|---|---|---|---|
development | Sí | No | Sí | Sí | ninguno |
staging | No | No | No | 1 (el despliegue directo está desactivado) | |
production | Sí | No | No | 1, cuatro ojos, se requiere cambio de referencia |
Rutas: development → staging → production.
Exporta un manifiesto y haz una prueba.
Todas las rutas son relativas a la raíz de la API de la instancia, que /api en hydra-server. Autentíquese con un token de inicio de sesión o un token de API que contenga el ámbito mostrado.
# 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}] acepta ?format=json. POST /api/manifests/apply también acepta mode=deploy|draft, environment=<slug> y review_token=<slug>:<token>. Un despliegue a través de este punto final solo se acepta en el entorno local predeterminado de la organización, y solo si permite el despliegue directo. Cada elemento se planifica primero; si se rechaza alguno, no se escribe nada. El cuerpo está limitado a 4 MiB.
Implementar o promocionar en un entorno
POST /api/environments/{slug}/deployments funciona tanto en entornos locales como remotos.
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 respuesta tiene un status (planned para una prueba), el release y una entrada por elemento con un action (create, update, unchanged o refused). Envíe el mismo cuerpo con "dry_run": false para desplegar.
Qué se comprueba:
| Controlar | Falla |
|---|---|
| Puedes exportar todos los artículos | 403 cannot export ... |
Existe una ruta from → target, y se asigna from cuando las rutas conducen al objetivo. | 422 there is no promotion route ..., environment ... is reached by promotion only |
Cada elemento se implementa en from, en la misma versión. | 409 ... is not deployed in ..., ... runs <slug>@<version>, not ... |
El hash coincide con lo que from carreras | 409 ... differs from what ... runs |
| Una referencia de cambio, cuando la política lo requiera. | 422 environment "..." requires a change reference |
| La instancia tiene una clave de firma | 503 this instance has no signing key (...); it cannot sign releases |
| El entorno es activo | 409 archivados |
Se rechaza una promoción interna (422). Las comprobaciones se realizan de nuevo cuando se aprueba finalmente una liberación retenida. Si algo cambió durante el proceso, la liberación falla y no se produce ningún cambio.
Entornos remotos
Un entorno remoto se registra con POST /api/environments y "location": "remote", un objeto remote (base_url, key_id, environment) y un token. Cada instancia necesita una clave de firma Ed25519 (HYDRA_INSTANCE_SIGNING_KEY_FILE) y ENCRYPTION_MASTER_KEY. GET /api/instance es público y muestra el ID de instancia y la huella digital de la clave (key_id); los dos administradores comparan las huellas digitales fuera de banda.
El origen envía la versión firmada al destino POST /api/deployments/receive mediante un token con alcance deployments:write El destino solo acepta de una clave de origen en la que su administrador haya confiado (GET /api/instance/trust, luego POST /api/instance/trust/{id}/trust o revoke). El primer envío desde una clave desconocida devuelve pending_trust; confíe en la clave del destino y vuelva a implementar. Las credenciales nunca se transmiten en la versión: el destino utiliza sus propias variables y conectores.
Estados de promoción
En el origen, la respuesta de despliegue y el registro de lanzamiento utilizan estos estados:
| Estado | Significado |
|---|---|
planned | Solo prueba en seco |
pending_trust | El objetivo aún no confía en la clave de origen. |
pending_approval | Retenido para aprobación (HTTP 202) |
applied | Aplicado; para un objetivo remoto, se verificó un recibo. |
refused | Se produjo un error en la comprobación; no se movió nada. |
unknown | La solicitud no se completó. Verifique qué se ejecuta en el destino antes de volver a implementar. |
En el objetivo, la bandeja de entrada de aprobaciones (GET /api/deployments/pending[?status=]) utiliza pending, applied, rejected, expired y failed.
Aprobaciones
Se retiene una publicación cuando la política del entorno de destino requiere aprobaciones, no permite la implementación directa o está protegido. En los dos últimos casos, se requiere al menos una aprobación.
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"}'
Reglas aplicadas por el servidor:
- Los aprobadores tienen el permiso de aprobador del entorno (valor predeterminado
approve:hydra.promotion). - Cada persona decide una vez (409
you already decided on this release; another approver is needed). - El solicitante no puede aprobar (403
the requester cannot approve their own release). Los tokens de API no pueden aprobar (403releases are approved by people, not API tokens). - La última aprobación requerida revisa y aplica la liberación. Cualquier rechazo la finaliza.
- Una liberación retenida expira después de que la política alcance el
approval_ttl_hours; el valor predeterminado es 72.
Para un destino remoto, la fuente recopila el resultado con POST /api/environments/{slug}/releases/{id}/refresh. Vea qué se ejecuta en un entorno con GET /api/environments/{slug}/deployments y el historial de envío con GET /api/environments/{slug}/releases.
Retroceder
No existe la opción de revertir los cambios. Para los flujos de trabajo, implemente la versión publicada anteriormente mediante el procedimiento habitual y las aprobaciones correspondientes. En el caso de los agentes, una instancia tiene una única versión activa, por lo que debe publicar una nueva versión con el contenido anterior e implementarla.
Límites
- Las ejecuciones iniciadas por activadores entrantes (por ejemplo, HL7 a través de MLLP) y otras rutas internas no tienen en cuenta el entorno. Utilizan la configuración de la instancia y las versiones actuales.
- Un agente solo puede implementarse en un entorno local en su versión activa. Cualquier cambio posterior se detectará como una desviación, y las ejecuciones de ese agente en dicho entorno se rechazarán hasta que se vuelva a implementar.
- Solo para envío de datos: el destino debe ser accesible desde el origen a través de HTTPS.
manage:hydra.environment, necesario para administrar entornos e implementar, y el permiso de aprobador predeterminadoapprove:hydra.promotionno se encuentran en el catálogo de permisos del servicio de autenticación endev(lo busqué), por lo que en la práctica solo los superusuarios pueden administrar entornos.- Una puerta de liberación (el
required_gate_profilede la política, mostrado como Required compliance gate) puede retener o rechazar una implementación local. Un entorno restringido rechaza las liberaciones recibidas de otra instancia (environment "..." has a release gate; releases into it are deployed on this instance, not received, 422). Leí esto en el código fuente y no lo ejecuté.
Relacionado
- Ejecución en malla: ejecución en varios sitios
- Tiet · Studio Constructor: el menú Implementar
- Administración: entornos de la organización en la consola de administración
¿Algo no está claro? Envíe sus comentarios sobre la documentación por correo electrónico..