Migration and Rollout
This page is the canonical migration guide for the MX Fuels Reporting app. Keep operational guidance here instead of maintaining separate migration notes inside the application directory.
Current status
Section titled “Current status”The JSON schema and credential-routing implementation are complete in PR #240. The application is not in the deployment stage.
| Area | Status | Notes |
|---|---|---|
CNE ReporteVolumenes schema |
Complete | The schema is tracked in orchestration/include/assets/. |
Migration 016 |
Complete | The migration allows the api_key credential type. It was applied and tested. |
| Dashboard Key Vault routing | Complete | The dashboard reads the web vault and writes the CER, KEY, submission password, and company API key to the CNE vault. |
| CNE API submission | Implemented, unverified | Mocked and QA submission tests are deferred to a later pull request. Keep generation-only mode enabled until those tests pass. |
| Custom CNE writer role | Assigned | The portal UAMI has the role at the CNE vault scope. |
| Local validation | Pending | Use the Testing Guide. |
| Production deployment | Pending | Do not deploy until review and local validation are complete. |
Identity and vault model
Section titled “Identity and vault model”Use one identity per execution environment:
- Local development: the developer’s Azure CLI identity.
- Production Container App: the attached
visory-dev-scus-portal-uamiUAMI.
The dashboard uses these vaults:
visory-dev-scus-web-kv: read existing dashboard and integration secrets.visory-dev-scus-cne-kv: write regulator credential secrets only.
The CNE submission contract requires four values: the CER file, the KEY file, the submission
password, and the company API key. The dashboard stores all four values as company credentials.
Airflow sends the API key in the X-API-KEY header and the remaining values as multipart data. It
stores the files, password, and API key as Base64 secrets. PostgreSQL stores only credential metadata.
The password and API key are write-only in the dashboard and are never returned or displayed.
The company_regulator_credentials.credential_type values are cer, key, password, and
api_key. File rows retain their original filename. Password and API-key rows store NULL for
that column.
The submission task reads the JSON artifact again from Blob Storage. This allows the task to run on
a different Airflow worker than the assembly task. It creates local credential files with owner-only
permissions and removes them after the request. It reserves SUBMITTED before calling CNE because
the published contract has no idempotency key. Jobs left in SUBMITTED or UNDER_REVIEW need a
manual reconciliation process until that process is implemented.
The production workflow supplies AZURE_CLIENT_ID and AZURE_USERNAME. The first value selects
the UAMI for Azure SDK authentication. The second value is the PostgreSQL role name. See
Postgres Setup for connection details.
Azure access requirements
Section titled “Azure access requirements”The portal UAMI needs Key Vault Secrets User on the web vault. It must not read the CNE vault.
The custom Key Vault Secrets Writer role has this single data action:
Microsoft.KeyVault/vaults/secrets/setSecret/action.
Role definition ID: e52bc23c-0d4e-4b88-92aa-a309aa8e9f72.
The portal UAMI has this role assigned at the visory-dev-scus-cne-kv vault scope. Do not use
Key Vault Secrets Officer, because that role also permits secret reads and other operations.
Airflow reads pipeline secrets from visory-dev-scus-ds-kv and CNE credential secrets from the
CNE vault through its routed secrets backend. See RBAC & Identity
for the complete permission table.
CNE schema provenance
Section titled “CNE schema provenance”The tracked ReporteVolumenes schema is based on the CNE API Masivos QA documentation:
Swagger UI and the
OpenAPI document. The document identifies
the API as ApiMasivos | v1 and reports version 1.0.0. It also documents
GET /api/Pruebas/GetJSonScheme, which provides the JSON schema contract.
When CNE changes the contract, update orchestration/include/assets/ReporteVolumenes.schema.json,
the matching Python models, and the mapping and serialization tests. Record the new source version
in this section.
Rollout checklist
Section titled “Rollout checklist”Complete these steps in order:
- Review and approve PR #240.
- Run the focused Python and web tests.
- Verify the web UAMI has web-vault read access.
- Verify Key Vault Secrets Writer remains assigned to the UAMI at the CNE vault scope.
- Verify the PostgreSQL role uses the UAMI name from
AZURE_USERNAME. - Promote the dashboard changes to
main, which triggers its deployment workflow. - Verify the deployed Container App has
WEB_KEY_VAULT_URLandCNE_CREDENTIALS_KEY_VAULT_URL. - Smoke-test Key Vault reads and regulator credential writes.
- Complete the deferred CNE submission test pull request before enabling non-generation-only jobs outside QA.
Do not copy secret values into the repository, workflow arguments, or documentation.
Rollback
Section titled “Rollback”If validation fails, stop the rollout and keep the previous Container App revision active. Remove the new role assignment only if it was created for this rollout. Do not delete vault secrets as a rollback step. Record the failure and restore the prior application revision through the approved deployment process.