AIFACTORY-FEAT-048: IaCProvisioningService: complete delivery¶
Generated from the architecture model
This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.
A design artefact, not a tracker
This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).
Epic Runtime Cloud (PF-09) · Increment I2 Deliver it · State elaborated · Route backend-developer · Build order 99 of 185 (Factory code)
IaCProvisioningService is the service of bounded context BC-25 (Provisioning & Reconciliation). The single provisioning owner: deployment specifications (desired state declared in Git, versioned), provisioning runs with plan and apply receipts from the IaC runner (Pulumi, ADR-0004), production applies gated by the promotion's approval, and GitOps reconciliation that re-plans the declared state on a schedule (BC-25; manifest, deployment and GitOps sync rows merged). Its own repository is ConnectSoft.AI.SoftwareFactory.IaCProvisioningService.
| Delivers | IaCProvisioningService (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0004, ADR-0015 |
| Requirements | FR-08, FUX-05, NFR-08, NFR-09, XL-04, XL-10 |
| Depends on | — |
| Sources | model/services/runtime-cloud/IaCProvisioningService.yaml |
Scenarios to trace (10, catalog): SCN-IaCProvisioningService-001 ✓, SCN-IaCProvisioningService-002 ✓, SCN-IaCProvisioningService-003 ✓, SCN-IaCProvisioningService-004 ✓, SCN-IaCProvisioningService-005 ✓, SCN-IaCProvisioningService-006 ✓, SCN-IaCProvisioningService-007 ✓, SCN-IaCProvisioningService-008 ✓, SCN-IaCProvisioningService-009 ✓, SCN-IaCProvisioningService-010 ✓
AIFACTORY-US-025: IaCProvisioningService provisions an environment from its declared specification end to end¶
behavior · persona operator
As an operator, I want an environment provisioned from the specification declared in Git, with a plan I can read before anything is applied, so that infrastructure changes are reviewed, receipted and repeatable, and nothing changes in a cloud account without the decision the policy requires.
This is the integration PBI of IaCProvisioningService, the single provisioning owner of the bounded context Provisioning and Reconciliation (BC-25). The service keeps the desired state of each environment as versioned deployment specifications that refer to a Pulumi program and its commit in Git (ADR-0004), plans and applies provisioning runs through the IaC runner with a plan receipt and an apply receipt, gates every apply on the decision of PolicyEngineService or on the approval a promotion carries, and re-plans the declared state on a schedule. The repository ConnectSoft.AI.SoftwareFactory.IaCProvisioningService is created by the first task of this feature by the steps of the repository checklist of feature repository-and-pipeline-conventions: it is scaffolded once from the pinned base template package with UseFactoryProfile (features component-base-template-factory-profile and component-base-template-findings, consumed by pin), so token validation, the role policies, the scope chain with its 401, 403 and 404 answers, the tenant row filter, the Orleans messaging profile with the service name iac-provisioning, the scheduler, health, readiness and the telemetry wiring come from the profile and are not written again. Every integration event of the service is written as the run event envelope of the pinned contracts package to the Orleans outbox in the transaction of its command (ADR-0014). The public REST operations are reached through RuntimeCloudHost, which forwards the user token unchanged; the service accepts the audience of its own gateway and exchanges no token (ADR-0015 amendment D117). A resource of another tenant is answered 404, over gRPC NOT_FOUND, the same answer as for an unknown identifier, and a missing scope or project role inside the tenant of the caller 403 (ADR-0015 amendment D113). No REST route of the service names a project in its path, a query parameter or a body member: a list returns the rows of the projects in which the token holds a role, every project of the tenant for a Platform admin, and a run or a specification addressed by identifier is checked against the role of the caller in its project. The feature is delivered by six further PBIs: declared specifications and their reads (AIFACTORY-US-1071), reading provisioning runs (AIFACTORY-US-1072), planning a run and its gate (AIFACTORY-US-1073), applying with receipts (AIFACTORY-US-1074), cancelling a planned run (AIFACTORY-US-1075) and the hand-offs with the GitOps reconciliation (AIFACTORY-US-1076). Credentials of a cloud account are reached only by reference through SecretBrokerService; a secret value never reaches telemetry, an event, an artifact, a log record, a receipt or a reply. The inbox registers the four consumed events of the model, EnvironmentCreated, ApprovalDecided, PromotionApproved and ReconciliationDecided; the feature builds and registers no handler of a deletion order, which is built in I4 with RetentionResidencyService. Telemetry carries tenant and project on metrics by default and run, step and attempt on activities and log records where the work has them, and no stored or generated content, a plan or its outputs included, reaches telemetry by default (ADR-0019).
Acceptance criteria
| AC1 | Given the repository ConnectSoft.AI.SoftwareFactory.IaCProvisioningService created by the steps of the repository checklist, whose first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.IaCProvisioningService --UseFactoryProfile true from the pinned template package, when its pipeline runs with the work of this feature, then no second scaffold was run, the solution builds, the unit and acceptance tests pass with complete reports and a container image is published (ADR-0028, model/services/runtime-cloud/IaCProvisioningService.yaml). |
| AC2 | Given the service descriptor of the repository, when the contract test compares it with the hosted surface, then IaCProvisioningService/ListSpecifications, IaCProvisioningService/ListProvisioningRuns, IaCProvisioningService/GetProvisioningRun, IaCProvisioningService/PlanProvisioning, IaCProvisioningService/CancelProvisioning and IaCProvisioningService/Provisioning.GetCurrentSpecification are hosted with the scope, side-effect class, idempotency and response codes of model/services/runtime-cloud/IaCProvisioningService.yaml, and the test fails on an operation the file does not name. |
| AC3 | Given specifications and runs of two tenants and a caller of one, when an operation addresses a run or a specification of the other tenant, then the answer is 404, over gRPC NOT_FOUND, exactly as for an unknown identifier; given a caller without the scope of the operation or without a role in the project of the resource, then the answer is 403; given no token, then 401; in no case a state changes; a user token that RuntimeCloudHost forwards unchanged, whose audience is that gateway, is accepted without a token exchange (ADR-0015). |
| AC4 | Given the outbox and the inbox of the service after the acceptance suite, when their records are read, then IaCProvisioningService/SpecificationDeclared, IaCProvisioningService/ProvisioningPlanned, IaCProvisioningService/ProvisioningApplied and IaCProvisioningService/ProvisioningFailed and the audit evidence event AuditEvidenceSubmitted are the only event types the outbox holds, each written in the transaction of its command under the run event envelope, and the inbox registers the four consumed events and no handler of a deletion order (ADR-0014). |
| AC5 | Given the service starts, when liveness and readiness are probed and the acceptance suite has run, then readiness is unready until iac-provisioning-sql is migrated and while the outbox check of the messaging profile is unhealthy, the four metrics of the model are emitted with tenant and project from the instrument helper, and a scan of the captured log records, activities, metrics, events, receipts and stored artifacts finds no secret value and no plan or output content in telemetry (ADR-0019, model/services/runtime-cloud/IaCProvisioningService.yaml). |
| Traces: services | IaCProvisioningService, RuntimeCloudHost, SecretBrokerService, ArtifactService, PolicyEngineService, RunControlService |
| Traces: aggregates | IaCProvisioningService/DeploymentSpecification, IaCProvisioningService/ProvisioningRun |
| Traces: apis | IaCProvisioningService/ListSpecifications, IaCProvisioningService/ListProvisioningRuns, IaCProvisioningService/GetProvisioningRun, IaCProvisioningService/PlanProvisioning, IaCProvisioningService/CancelProvisioning, IaCProvisioningService/Provisioning.GetCurrentSpecification |
| Traces: events | IaCProvisioningService/SpecificationDeclared, IaCProvisioningService/ProvisioningPlanned, IaCProvisioningService/ProvisioningApplied, IaCProvisioningService/ProvisioningFailed |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0004, ADR-0014, ADR-0015, ADR-0019, ADR-0028 |
| Traces: requirements | FR-08, NFR-08, NFR-09, XL-04, XL-10 |
| Relates: screens | provisioning |
| Depends on | AIFACTORY-US-1071, AIFACTORY-US-1072, AIFACTORY-US-1073, AIFACTORY-US-1074, AIFACTORY-US-1075, AIFACTORY-US-1076, feature:repository-and-pipeline-conventions, feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:component-extensions-ai, feature:component-observability-factory-conventions, feature:contracts-package |
| Sources | model/services/runtime-cloud/IaCProvisioningService.yaml, docs/planes/execution/environments/services/ia-c-provisioning-service/index.md#purpose-and-responsibilities, docs/architecture/adr/0004-pulumi-over-bicep-iac.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-288 Create the repository ConnectSoft.AI.SoftwareFactory.IaCProvisioningService and scaffold it from the ConnectSoft.BaseTemplate template with the Factory profile |
implementation | The repository exists, created by the steps of the repository checklist of feature repository-and-pipeline-conventions; its first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.IaCProvisioningService --UseFactoryProfile true from the pinned template package, whose version the repository records, with the messaging service name iac-provisioning; the solution builds and the template tests pass in the repository pipeline, which publishes the container image; a deviation is corrected in the repository before the work of this feature is added. |
ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-289 Domain model: DeploymentSpecification and ProvisioningRun with the seven transitions of ProvisioningState |
implementation | The DeploymentSpecification aggregate holds the fields of the model with its configuration and secret references as references only, keeps every declared version and never edits a program; the ProvisioningRun aggregate holds the transitions Planned to AwaitingApproval, Planned to Applying, AwaitingApproval to Applying, AwaitingApproval to Rejected, Applying to Applied, Applying to Failed and Planned to Cancelled, and the move from Planned to Failed that the failure mode of a missing program version names (AIFACTORY-US-1073); receipts are immutable once written and a re-run is a new run; unit tests cover every transition, every rejected pair of states and every invariant of model/services/runtime-cloud/IaCProvisioningService.yaml. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-290 Persistence in iac-provisioning-sql: DeploymentSpecifications and ProvisioningRuns with the tenant filter and the modelled indexes |
migration | Mappings and migrations for the two modelled tables with the tenant column and row filter, the key of specification and version, the indexes IX_Specs_Env_Kind, IX_ProvRuns_Env_State and IX_ProvRuns_Promotion and a row version as optimistic concurrency token on a run; mapping tests run against an isolated test database, never a shared one. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-291 API hosting skeleton: service descriptor, REST and gRPC hosts, scope policies and problem responses of the 5 REST and 1 gRPC operations |
contract | The service descriptor file lists ListSpecifications, ListProvisioningRuns, GetProvisioningRun, PlanProvisioning, CancelProvisioning and Provisioning.GetCurrentSpecification with scope, side-effect class, idempotency and response codes; the five REST routes and the gRPC method are hosted with the scope policy of each route, problem responses for every modelled refusal code, the Idempotency-Key filter of PlanProvisioning and the workload scope check of the gRPC method; the behaviour of each operation is delivered by AIFACTORY-US-1071 to AIFACTORY-US-1075, not here. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-292 Messaging skeleton: outbox and inbox wiring of the iac-provisioning profile for 4 published and 4 consumed events |
implementation | The outbox writer enlists in the unit of work of a command, a handler and a worker step, and the dispatcher of the iac-provisioning messaging profile publishes SpecificationDeclared, ProvisioningPlanned, ProvisioningApplied, ProvisioningFailed and the audit evidence event AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted under the run event envelope of the pinned contracts package; the inbox registers EnvironmentCreated, ApprovalDecided, PromotionApproved and ReconciliationDecided with idempotency on the event id and no handler of a deletion order; what each handler does is delivered by AIFACTORY-US-1073 and AIFACTORY-US-1076. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-293 Worker hosting skeleton: triggers, partitioning and retry policies of Planner, Applier and GitOpsReconciler |
implementation | The three workers are hosted with their modelled triggers, idempotency keys and partitioning: the Planner with exponential retry, the Applier with no retry and one attempt, and the GitOpsReconciler on its schedule with fixed retry; a duplicate trigger has no second effect; what each worker does is delivered by AIFACTORY-US-1073, AIFACTORY-US-1074 and AIFACTORY-US-1076. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-294 Security, tenancy and telemetry of IaCProvisioningService |
implementation | The scopes factory.provisioning.read and factory.provisioning.apply and the roles Operator, Platform admin and Observer are enforced per route; a user token forwarded by RuntimeCloudHost is accepted with the audience of that gateway; every query is tenant-filtered so a resource of another tenant is answered 404; the iac-runner-identity and messaging-transport secrets come from secret references of the key vault and never appear in configuration files; connectsoft.factory.provisioning.runs, apply_duration, reconciliation_diffs and inbox_lag are created through the instrument helper of the observability library with tenant and project; a redaction test fails when a log record, an activity or a metric holds a secret value, a plan or an output. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-783 Verify provision-from-specification by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build in the pipeline of the repository; a run that discovers no test counts as a failure; the runs pass and prove AC1 to AC5 of AIFACTORY-US-025, that is the scaffold, the hosted surface against the service descriptor, the two-tenant matrix with its 404, 403 and 401 answers, the event types of the outbox and the inbox, readiness and the redaction scan. |
ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-US-1071: A deployment specification is declared once per program commit and read by people and by the services that compare against it¶
behavior · persona operator
As an operator, I want every desired state of an environment kept as a version that names the program commit it came from, so that I can see what is declared for an environment and every service compares against the same applied version.
A DeploymentSpecification keeps the desired state of one environment or workload: the reference to the Pulumi program (programRef, the repository and path of the InfrastructureModel project) and its commit (programVersion), the release it deploys, the strategy, the configuration references of the Config Platform and the secret references of SecretBrokerService, never a value. A new version is declared when a hand-off of AIFACTORY-US-1076 names a program commit the specification of that environment and kind does not hold yet: the version is incremented, declaredAt is set, and SpecificationDeclared is written to the outbox in the same transaction with specificationId, tenantId, environmentId, kind, version and programVersion under the run event envelope; the same commit named again declares nothing and publishes nothing. Every version is kept, and the service records which version was acted on and never edits the program. An Operator, a Platform admin or an Observer whose scope carries factory.provisioning.read lists the specifications per environment with their versions and program references through ListSpecifications, filtered to the tenant of the token and the projects in which the token holds a role, every project of the tenant for a Platform admin; secret and configuration references are listed as references. A caller without the scope is refused with 403 and nothing changes. A workload calls the internal Provisioning.GetCurrentSpecification with execution-scope-v1 naming the tenant, the project and the environment and receives the specification versions last applied to that environment, one per specification kind the environment holds, each the version of the last run of that kind of specification that reached Applied, with its kind, program reference, program commit and release; an environment can hold specifications of the kinds EnvironmentBaseline, Workload, Network, Data and Observability, but in this feature only EnvironmentBaseline and Workload are declared, by the hand-offs of AIFACTORY-US-1076, and the model gives no declaration path for the kinds Network, Data and Observability and no creation path for a run of kind Rollback, which are reported as gaps; EnvironmentPromotionService and RuntimeEnvironmentService read it in this increment and FleetInventoryService in its own increment. The token must be a workload token holding the service scope the method names; the tenant and the project the workload forwards are read only under that scope (ADR-0015 amendment D114). A call without workload identity is answered UNAUTHENTICATED, a token without the scope PERMISSION_DENIED, a request that fails validation INVALID_ARGUMENT, and an environment of another tenant NOT_FOUND, the same answer as for an unknown environment (ADR-0015 amendment D113); an environment with a declared and no applied version is answered with a reply that names no applied version. The method is a read: it writes nothing and publishes nothing. The model names ack-v1 as its reply, a descriptor that has no member for a specification version; the proto carries the reply in the shape of that schema and adds the members of the applied version beside it, and a contract test states the difference, which is reported as a correction of the descriptor row of the model.
Acceptance criteria
| AC1 | Given specifications of two projects of one tenant and of a second tenant, and a caller with factory.provisioning.read and a role in one project, when IaCProvisioningService/ListSpecifications is called, then the response is 200 with the specifications of that project per environment with every version, its program reference and commit, and secret and configuration references as references only; a Platform admin receives every project of the tenant and no row of the other tenant appears (SCN-IaCProvisioningService-001, ADR-0015). |
| AC2 | Given a caller without factory.provisioning.read, when IaCProvisioningService/ListSpecifications is called, then the response is 403 with a problem response and no state changes (SCN-IaCProvisioningService-001). |
| AC3 | Given a hand-off that names a program commit the IaCProvisioningService/DeploymentSpecification of the environment and kind does not hold, when it is handled, then a new version is written with declaredAt and the IaCProvisioningService/SpecificationDeclared outbox record in the same transaction; given the same commit named again, then no version and no record is written (SCN-IaCProvisioningService-007, ADR-0014). |
| AC4 | Given a declared version, when the dispatcher of the iac-provisioning messaging profile publishes IaCProvisioningService/SpecificationDeclared on provisioning.specifications.v1.specification-declared, then the event is sent under the run event envelope with specificationId, tenantId, environmentId, kind, version and programVersion, no secret value is in it, and a transport outage is retried with backoff so the event is neither lost nor published twice under its event id (SCN-IaCProvisioningService-007, ADR-0012). |
| AC5 | Given a workload token with the service scope of the method and an environment with an applied EnvironmentBaseline version and an applied and a newer declared Workload version, when IaCProvisioningService/Provisioning.GetCurrentSpecification is called, then the reply names the last applied version per specification kind, each with its kind, program reference, commit and release, never a declared version that was not applied, and nothing is written; given no workload identity, a token without the scope, an invalid request or an environment of another tenant, then the call is refused with UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT or NOT_FOUND and no state changes (SCN-IaCProvisioningService-006, ADR-0015). |
| Traces: services | IaCProvisioningService |
| Traces: aggregates | IaCProvisioningService/DeploymentSpecification |
| Traces: apis | IaCProvisioningService/ListSpecifications, IaCProvisioningService/Provisioning.GetCurrentSpecification |
| Traces: events | IaCProvisioningService/SpecificationDeclared |
| Traces: descriptors | execution-scope-v1, ack-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0004, ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-08, XL-04 |
| Traces: scenarios | SCN-IaCProvisioningService-001, SCN-IaCProvisioningService-006, SCN-IaCProvisioningService-007 |
| Relates: screens | provisioning |
| Depends on | feature:contracts-package, feature:component-base-template-factory-profile |
| Sources | model/services/runtime-cloud/IaCProvisioningService.yaml, docs/planes/execution/environments/services/ia-c-provisioning-service/index.md#domain-model, docs/reference/schemas/run-event-envelope.schema.json |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-327 Specifications declared once per program commit with the SpecificationDeclared outbox record |
implementation | A specification version is recorded for a program commit of an environment and kind with declaredAt and the SpecificationDeclared outbox record in one transaction; the same commit is recorded once; configuration and secret references are stored as references and a value offered in their place is refused by the aggregate; every version is kept. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-4311 ListSpecifications read model and the GetCurrentSpecification method with its proto reply |
implementation | ListSpecifications returns the specifications per environment with versions, program references and references only, filtered by the tenant row filter and the projects in which the token holds a role, every project for a Platform admin; Provisioning.GetCurrentSpecification admits a workload token with its service scope only, reads the forwarded tenant, project and environment under it and returns the last applied version per specification kind of the environment, or a reply that names no applied version, with NOT_FOUND for an environment of another tenant; the proto adds the members of the applied version beside the shape of ack-v1, and a contract test states the difference reported as a correction of the model. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-4312 Contract of SpecificationDeclared against the run event envelope of the contracts package |
contract | A golden file fixes SpecificationDeclared on the topic provisioning.specifications.v1.specification-declared under run-event-envelope-v1 with specificationId, tenantId, environmentId, kind, version and programVersion and the tenant and project in the envelope; a contract test fails when the serialised event differs from the file or from docs/reference/schemas/run-event-envelope.schema.json, and the envelope type comes from the pinned contracts package. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-4313 Verify declared-provisioning-specifications through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-IaCProvisioningService-001\|Scenario=SCN-IaCProvisioningService-006\|Scenario=SCN-IaCProvisioningService-007)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-1071, including the one declaration per commit, the publication and payload of SpecificationDeclared and the four gRPC refusals; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-US-1072: Read provisioning runs with their plan, approval and apply receipts under the tenant and the projects of the caller¶
behavior · persona operator
As an operator, I want to list the provisioning runs of my environments and open one with its plan, its approval and its apply receipt, so that I see what was planned, who approved it and what was changed before I act on an environment.
An Operator, a Platform admin or an Observer whose scope carries factory.provisioning.read lists provisioning runs through ListProvisioningRuns, filtered by environment, kind and state and paged, and receives each run with its kind, state, specification version, the promotion that requested it, and the summaries of its plan receipt and apply receipt. The list holds the runs of the tenant of the token in the projects in which the token holds a role, every project of the tenant for a Platform admin; a run of another tenant never appears. The same caller reads one run through GetProvisioningRun and receives its plan receipt (adds, changes, deletes, the hash of the inputs and the program version), the approval reference when the run waited for one, the apply receipt (outputs, duration, result and runner version) and the reference of its logs and state artifacts in ArtifactService, which a person opens through the artifact routes of its own platform under the scope of those routes. A run of another tenant is answered 404, the same answer as for an unknown provisioningRunId, and never confirmed (ADR-0015 amendment D113); a caller without the scope, or without a role in the project of the run, is refused with 403. No receipt holds a secret value: outputs the program marks as secret are absent from the stored apply receipt and are therefore absent from every reply. Both reads write nothing and publish nothing. These are the read models of the Provisioning screen of the Studio, which StudioBff reads in its own increment.
Acceptance criteria
| AC1 | Given runs of several environments, kinds and states in two projects and two tenants, and a caller with factory.provisioning.read and a role in one project, when IaCProvisioningService/ListProvisioningRuns is called with a filter of environment, kind and state and a page cursor, then the response is 200 with only the matching runs of that project, each with state, kind, specification version and receipt summaries, and no run of the other project or tenant appears (SCN-IaCProvisioningService-002, ADR-0015). |
| AC2 | Given a caller without factory.provisioning.read, when IaCProvisioningService/ListProvisioningRuns or IaCProvisioningService/GetProvisioningRun is called, then the response is 403 with a problem response and no state changes (SCN-IaCProvisioningService-002, SCN-IaCProvisioningService-003). |
| AC3 | Given an applied run whose program marked one output as secret, when IaCProvisioningService/GetProvisioningRun is called by a caller with the scope and a role in its project, then the response is 200 with the plan receipt, the approval reference, the apply receipt and the logs reference of the IaCProvisioningService/ProvisioningRun, and the secret output is absent from the reply (SCN-IaCProvisioningService-003, ADR-0019). |
| AC4 | Given a provisioningRunId of another tenant, an unknown one, and a run of a project in which the caller holds no role, when IaCProvisioningService/GetProvisioningRun is called, then the first two are answered 404 alike and the third 403, each with a problem response and no state change (SCN-IaCProvisioningService-003, ADR-0015). |
| Traces: services | IaCProvisioningService |
| Traces: aggregates | IaCProvisioningService/ProvisioningRun |
| Traces: apis | IaCProvisioningService/ListProvisioningRuns, IaCProvisioningService/GetProvisioningRun |
| Traces: adrs | ADR-0015, ADR-0019 |
| Traces: requirements | FR-08, XL-10 |
| Traces: scenarios | SCN-IaCProvisioningService-002, SCN-IaCProvisioningService-003 |
| Relates: screens | provisioning |
| Depends on | AIFACTORY-US-1071, feature:component-base-template-factory-profile |
| Sources | model/services/runtime-cloud/IaCProvisioningService.yaml, docs/planes/execution/environments/services/ia-c-provisioning-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-4314 ListProvisioningRuns and GetProvisioningRun read models with filters, paging and the project rule |
implementation | ListProvisioningRuns returns the runs paged and filtered by environment, kind and state with receipt summaries, and GetProvisioningRun one run with its plan receipt, approval reference, apply receipt and logs reference; both apply the tenant row filter and the project roles of the token, answer 404 for a run of another tenant as for an unknown id and 403 for a missing scope or project role, and never return a secret output. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-4315 Contract of the run list and the run view in the OpenAPI document of the service |
contract | The OpenAPI document of the service describes the paged run list with its filters and the run view with plan receipt, approval reference, apply receipt and logs reference as model/services/runtime-cloud/IaCProvisioningService.yaml names them, and a contract test fails when the hosted responses differ from the document. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-4316 Verify read-provisioning-runs through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-IaCProvisioningService-002\|Scenario=SCN-IaCProvisioningService-003)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1072, including the absent secret output, the 404 alike for a foreign and an unknown run and the 403 for a project without a role. |
ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-US-1073: Plan a provisioning run, record its plan receipt and route the apply by the policy decision or the approval it requires¶
behavior · persona operator
As an operator, I want to plan a specification version against an environment and read the plan before anything changes, so that an apply happens only when the policy allows it or the approval it requires was granted for exactly that plan.
An Operator or a Platform admin whose scope carries factory.provisioning.apply plans a specification version against an environment through PlanProvisioning with an Idempotency-Key. The body names the specification, its version, the environment and the kind of the run; the operation admits the three kinds its summary names, EnvironmentBaseline, Reconciliation and Decommission, while a run of kind Promotion is created only by the hand-off of a promotion (AIFACTORY-US-1076). A body that fails validation, a version the specification does not hold or a kind the operation does not admit is refused with 422; the same key with a different body is refused with 409; a caller without the scope or without the Operator or Platform admin role in the project of the specification is refused with 403; a specification of another tenant is answered 404, the same answer as for an unknown one (ADR-0015 amendment D113), a code the code list of the operation does not name, which is reported as a correction of the model. An accepted call writes the ProvisioningRun in state Planned and returns 202 with its location; the same key with the same body returns the same run and changes nothing. The Planner resolves the program version, the configuration references and the secret references by reference, runs the IaC planner and records the plan receipt (adds, changes, deletes, the hash of the inputs and the program version), stores the plan log through Artifacts.Store, and writes ProvisioningPlanned with provisioningRunId, tenantId, environmentId, kind, the optional promotionId and planSummary in the same transaction; no resource changes before the plan is recorded. A plan without adds, changes or deletes is an empty plan, and one rule holds for it in this feature: the Planner records its receipt and writes ProvisioningPlanned with an empty planSummary, and in the same transaction the run moves Planned to Cancelled with the reason no-changes, so an empty plan never reaches the gate or the runner and nothing is applied; the model gives no trigger for that end, and the use of the transition Cancel is reported as a correction (AIFACTORY-US-1074 and AIFACTORY-US-1076 follow this rule). The gate follows. A run of kind Promotion that carries the approval of a promotion moves Planned to Applying (ApprovedOrAllowed), because the promotion approval is reused for the production apply. Every other run, a Promotion run without an approval included, asks PolicyEngineService through Policy.Decide; the service never decides an approval itself. The request is a policy-decision-request-v1 with the action kind provisioning-apply, which pairs with the domain Deployment so that the service names no domain, the target provisioning-apply, the side-effect class of the plan before any raising (D127, D129), the environment of the run, the run as the resource, the hash of the plan receipt as the inputs hash, the runId of the envelope where the run has one, and as subject the workload identity of the service with the tenant and the project of the run; the engine raises the class by the class of the environment it reads through Environments.GetPolicyClass, so the service sends the class of its plan and never a class of the environment. An allow moves the run Planned to Applying (ApprovedOrAllowed). An allow-with-constraints moves it Planned to Applying only when the service can honour every listed constraint: the repository keeps a table of the constraint names it honours, each mapped to a check of the plan receipt or a setting of the apply, and the constraints are recorded on the run; a constraint outside the table applies nothing and ends the run Failed with the constraint named, writing AuditEvidenceSubmitted with the action policy-constraint-unmet and ProvisioningFailed in the same transaction (D129). On an allow and on an honoured allow-with-constraints the decisionId of the decision is recorded in the plan receipt, and AuditEvidenceSubmitted with the action policy-allowed naming the decision id is written on audit.evidence.v1.evidence-submitted in the transaction of the move Planned to Applying, which is the evidence the invariant of the model asks of a baseline or reconciliation apply. An allow-with-approval, which the seeded tenant bundle answers for a provisioning apply of the class production or external (D127, D129), moves it Planned to AwaitingApproval (ProductionWithoutApproval) and requests the approval from RunControlService through RunControl.RequestApproval with the subject kind provisioning-run and the provisioning run id as its subject, the service identity of IaCProvisioningService as the requesting service, the hash of the plan receipt as the proposal hash and the Operator or Platform admin as approvers; the approval reference is kept on the run. ApprovalDecided of RunControlService is handled by ApplyApproval idempotently on the event id. An approved decision moves the run AwaitingApproval to Applying (ApprovalGranted) only when its proposalHash equals the hash of the plan receipt, because an approval binds to the exact proposal; on a mismatch nothing is applied, the run stays AwaitingApproval and the mismatch is logged with the run and approval identifiers and without content. A rejected, expired, stale or cancelled decision moves the run AwaitingApproval to Rejected (ApprovalRejectedOrExpired), and so does a ChangesRequested decision, with the reason of the reviewer recorded on the run: a provisioning run cannot regenerate its plan, so a new plan is a new run. A decision for an approval no run holds changes nothing. A deny or a prohibited answer applies nothing and ends the run Failed with the reason policy-denied, writing AuditEvidenceSubmitted with the action policy-denied naming the decision id on audit.evidence.v1.evidence-submitted and ProvisioningFailed in the transaction that records the decision on the run (D129). The approval request names the provisioning run as its subject, so runId is optional in approval-request-v1: a run handed over from work of a Factory run carries the runId of its envelope, and a run without one, a baseline of a new environment or a run of the GitOpsReconciler (AIFACTORY-US-1076), is put to approval all the same; ApprovalDecided names the subject, so the decision returns to this service (D129, D135). PolicyEngineService and RunControlService are fail-fast dependencies: an answer INVALID_ARGUMENT, FAILED_PRECONDITION or UNAVAILABLE of Policy.Decide is treated as not allowed, and while either service gives no usable answer the Planner retries with its exponential policy and nothing is applied; a gate without a usable answer past the retries, a planner failure that outlasts the retries, and a program version that is not found, move the run to Failed with the reason, as the failure mode of the model states, a move from Planned that the state machine of the model does not list and that is reported as a correction. When the Config Platform does not answer, the planner records the configuration references as unresolved in the plan receipt and the run continues to its gate (degrade).
Acceptance criteria
| AC1 | Given a caller with factory.provisioning.apply and the Operator role in the project of a specification, when IaCProvisioningService/PlanProvisioning is called with an Idempotency-Key and a body naming that specification, a version it holds, its environment and the kind Reconciliation, then the response is 202 with the run location and the IaCProvisioningService/ProvisioningRun is in state Planned; the same call repeated returns the same run and changes nothing (SCN-IaCProvisioningService-004). |
| AC2 | Given the same key with a different body, an invalid body, a version the specification does not hold or the kind Promotion, a caller without the scope or the role, and a specification of another tenant, when IaCProvisioningService/PlanProvisioning is called, then the answers are 409, 422, 422, 422, 403 and 404 respectively, each with a problem response, and no run is written and nothing is published (SCN-IaCProvisioningService-004, ADR-0015). |
| AC3 | Given a planned run, when the Planner records its plan receipt, then the plan log is stored through ArtifactService/Artifacts.Store, the IaCProvisioningService/ProvisioningPlanned outbox record is written in the same transaction with planSummary, and the dispatcher publishes it on provisioning.runs.v1.provisioning-planned under the run event envelope with provisioningRunId, tenantId, environmentId, kind and the optional promotionId, retrying a transport outage with backoff so the event is neither lost nor published twice; no resource changed before the record; given the same specification planned again without a change, then the plan is empty, IaCProvisioningService/ProvisioningPlanned carries an empty planSummary, the run is Cancelled with the reason no-changes in the same transaction and neither the gate nor the runner was called (SCN-IaCProvisioningService-008, ADR-0012). |
| AC4 | Given fakes of PolicyEngineService/Policy.Decide that answer allow, allow-with-constraints with a constraint the table of the service holds and with one it does not, allow-with-approval, deny, INVALID_ARGUMENT, FAILED_PRECONDITION and UNAVAILABLE, when a run without a promotion approval passes its gate, then every request was a policy-decision-request-v1 with the action kind provisioning-apply, no domain, the target provisioning-apply, the side-effect class of the plan, the environment and the hash of the plan receipt as inputs hash; allow and the honoured constraints move the run to Applying with the decisionId in the plan receipt, the constraints recorded on the run and AuditEvidenceSubmitted with the action policy-allowed in the transaction of the move; the unhonoured constraint ends the run Failed with the constraint named, policy-constraint-unmet evidence and IaCProvisioningService/ProvisioningFailed; allow-with-approval moves it to AwaitingApproval and requests the approval through RunControlService/RunControl.RequestApproval with the subject kind provisioning-run, the provisioning run as subject, also for a run without a Factory run, bound to the hash of the plan receipt; deny ends the run Failed with policy-denied evidence and IaCProvisioningService/ProvisioningFailed; the three error answers apply nothing and, past the retries of the Planner, leave the run Failed with the reason; a run carrying the approval of a promotion moves to Applying without a decision (SCN-IaCProvisioningService-004, ADR-0015). |
| AC5 | Given a run in AwaitingApproval, when RunControlService/ApprovalDecided arrives approved with the hash of its plan receipt, approved with another proposalHash, rejected, expired, stale, cancelled or ChangesRequested, then the first moves the run to Applying, the second applies nothing, leaves the run AwaitingApproval and logs the mismatch without content, and the others move the run to Rejected, ChangesRequested with the reason of the reviewer recorded on the run; a repeated event changes nothing; given the planner fails past the retries of the Planner, or the program version is not found, then nothing is applied and the run is Failed with the reason (SCN-IaCProvisioningService-004, model/services/control-plane/RunControlService.yaml). |
| Traces: services | IaCProvisioningService, PolicyEngineService, RunControlService, ArtifactService |
| Traces: aggregates | IaCProvisioningService/ProvisioningRun |
| Traces: apis | IaCProvisioningService/PlanProvisioning, PolicyEngineService/Policy.Decide, RunControlService/RunControl.RequestApproval, ArtifactService/Artifacts.Store |
| Traces: events | IaCProvisioningService/ProvisioningPlanned, IaCProvisioningService/ProvisioningFailed, RunControlService/ApprovalDecided |
| Traces: descriptors | policy-decision-v1, policy-decision-request-v1, approval-request-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0004, ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-08, NFR-08, XL-04 |
| Traces: scenarios | SCN-IaCProvisioningService-004, SCN-IaCProvisioningService-008 |
| Relates: screens | provisioning |
| Depends on | AIFACTORY-US-1071, feature:policy-engine-service, feature:run-control-service, feature:artifact-service, feature:contracts-package |
| Sources | model/services/runtime-cloud/IaCProvisioningService.yaml, model/services/governance/PolicyEngineService.yaml, model/services/control-plane/RunControlService.yaml, docs/reference/schemas/policy-decision.schema.json, docs/reference/schemas/approval.schema.json, docs/planes/execution/environments/services/ia-c-provisioning-service/index.md#workers-and-jobs |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-4317 PlanProvisioning with its idempotency key, admitted kinds and refusals |
implementation | The operation validates the body, admits the kinds EnvironmentBaseline, Reconciliation and Decommission, writes the ProvisioningRun in state Planned and returns 202 with the location; the idempotent repeat, the 409 for a reused key with a different body, the 422 for an invalid body, an unknown version or an inadmissible kind, the 403 for a missing scope or project role and the 404 for a specification of another tenant are covered by acceptance tests, and none of them writes a run or an outbox record. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-4318 Planner with the plan receipt, the plan log artifact and the ProvisioningPlanned outbox record |
implementation | The Planner resolves the program version and the references by reference, runs the IaC planner, stores the plan log through Artifacts.Store, records the plan receipt and writes ProvisioningPlanned in one transaction; an empty plan writes ProvisioningPlanned with an empty planSummary and moves the run to Cancelled with the reason no-changes in that transaction, so it reaches neither the gate nor the runner; unresolved configuration references are recorded as such when the Config Platform does not answer; a planner failure past the exponential retries or a missing program version moves the run to Failed with the reason; a golden file fixes ProvisioningPlanned under run-event-envelope-v1. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-329 Gate of an apply by the policy decision, the promotion approval or the approval it requires |
implementation | A Promotion run with a promotion approval moves to Applying; every other run asks Policy.Decide with a policy-decision-request-v1 of the action kind provisioning-apply, no domain, the target provisioning-apply, the side-effect class of the plan, the environment, the run as resource, the hash of the plan receipt as inputs hash, the runId of the envelope where present and the workload identity of the service as subject; allow moves it to Applying, allow-with-constraints moves it to Applying only when every constraint is in the table of honoured constraint names and records the constraints on the run, and an unhonoured constraint ends it Failed with the constraint named, AuditEvidenceSubmitted with the action policy-constraint-unmet and ProvisioningFailed in one transaction; on allow and honoured constraints the decisionId is recorded in the plan receipt and AuditEvidenceSubmitted with the action policy-allowed naming it is written in the transaction of the move to Applying; allow-with-approval moves the run to AwaitingApproval with an approval requested through RunControl.RequestApproval with the subject kind provisioning-run, the provisioning run id as subject and the service identity as the requesting service, bound to the plan hash; deny and prohibited end the run Failed with the reason policy-denied, AuditEvidenceSubmitted with the action policy-denied naming the decision id and ProvisioningFailed in one transaction; INVALID_ARGUMENT, FAILED_PRECONDITION and UNAVAILABLE count as not allowed and follow the retry and Failed rule of the Planner; the ApplyApproval handler of ApprovalDecided moves the run to Applying only for an approved decision whose proposalHash equals the hash of the plan receipt, leaves it AwaitingApproval and logs a mismatch without content otherwise, and moves it to Rejected on rejected, expired, stale, cancelled and ChangesRequested, the last with the reason of the reviewer, idempotently on the event id; a run without a Factory run id is put to approval by its subject like any other; the service decides no approval itself. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-4319 Verify plan-a-provisioning-run-and-its-gate through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-IaCProvisioningService-004\|Scenario=SCN-IaCProvisioningService-008)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-1073 with fakes of Policy.Decide, RunControl.RequestApproval and Artifacts.Store that can answer each outcome and stop answering, a fake Policy.Decide that answers allow-with-constraints with an honoured and an unhonoured constraint and the errors INVALID_ARGUMENT, FAILED_PRECONDITION and UNAVAILABLE, and ApprovalDecided fixtures for an approval of the plan hash, an approval of another proposalHash and a ChangesRequested decision, including the empty plan of a specification planned twice, the publication and payload of ProvisioningPlanned and the policy-allowed, policy-constraint-unmet and policy-denied evidence; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-US-1074: Apply a provisioning run once through the IaC runner with brokered credentials, store its receipts and announce the outcome¶
behavior · persona operator
As an operator, I want an allowed or approved run applied once with a receipt that names what changed or which resource failed, so that a failed apply is never retried blindly and a credential of a cloud account never leaves the runner.
The Applier takes a run in state Applying, triggered by ProvisioningPlanned or by the decision that moved the run to Applying, under the idempotency key of the run and the apply, so a duplicate trigger has no second effect. It resolves the secret references of the specification through SecretBrokerService with SecretBroker.Issue at apply time, hands the issued short-lived credential to the IaC runner for this apply only and revokes the issuance through SecretBroker.Revoke when the apply ends; the runner identity itself is the iac-runner-identity reference of the key vault. The runner applies the recorded plan of the program version with the configuration references the Config Platform resolves and stops at the timeout of the option RuntimeCloud:Provisioning:ApplyTimeoutMinutes. The apply logs and the state snapshot are stored through Artifacts.Store, and the apply receipt records outputs, duration, result and runner version; outputs the program marks as secret are never recorded. When the runner succeeds the run moves Applying to Applied (RunnerSucceeded) and ProvisioningApplied is written in the same transaction with provisioningRunId, tenantId, projectId, environmentId, kind, the optional promotionId, specificationVersion and outputs; that version becomes the current specification of the environment. When the runner fails, times out or the cloud control plane does not answer, the run moves Applying to Failed (RunnerFailed) with a receipt that records the partial state and names the failing resource, and ProvisioningFailed is written in the same transaction with provisioningRunId, tenantId, environmentId, kind, the optional promotionId and a reason that holds no secret value. A failed run marks nothing as done and is never retried by the service: the Applier has no retry, a promotion rolls back through EnvironmentPromotionService, the reconciliation proposes the fix through RuntimeEnvironmentService, and a re-run is a new provisioning run. When SecretBrokerService does not answer, or a reference does not resolve, the runner is not started and the run is Failed with a receipt that names the reference and never a value (fail-fast). When ArtifactService does not answer when the logs or the state snapshot are stored, the run is settled from the result of the runner in the transaction of the service all the same: on success it moves to Applied with its apply receipt and ProvisioningApplied, on failure to Failed with ProvisioningFailed, and a logs or state artifact that could not be stored is recorded in the receipt as not stored with the reason; the store is a fail-fast dependency and such an artifact is never retried in a loop, and the cloud apply is never repeated. The model has no path to store such an artifact later, which is reported to the owner. An empty plan never reaches the Applier, because the Planner ends it Cancelled with the reason no-changes by the rule of AIFACTORY-US-1073. connectsoft.factory.provisioning.runs counts the outcome by tenant, kind and state and connectsoft.factory.provisioning.apply_duration records the duration by kind. These events are the input of EnvironmentService, EnvironmentPromotionService, RuntimeEnvironmentService, ExecutionCapacityService, StudioBff, AuditService and AlertRuleService, each in its own increment and PBIs; this PBI proves what the publisher can prove.
Acceptance criteria
| AC1 | Given a run in Applying, when the Applier applies it against a fake runner that succeeds, then the secret references were issued through SecretBrokerService/SecretBroker.Issue and revoked through SecretBrokerService/SecretBroker.Revoke, the logs and the state snapshot were stored through ArtifactService/Artifacts.Store, the run is Applied with its apply receipt and the IaCProvisioningService/ProvisioningApplied outbox record is written in the same transaction; a duplicate trigger applies nothing a second time (SCN-IaCProvisioningService-009, ADR-0004). |
| AC2 | Given a fake runner that fails on one resource, one that exceeds the apply timeout and an unreachable cloud control plane, when the Applier applies, then each run is Failed with a receipt that records the partial state and names the failing resource, the IaCProvisioningService/ProvisioningFailed outbox record is written in the same transaction, and the runner was called once per run and never again (SCN-IaCProvisioningService-010, model/services/runtime-cloud/IaCProvisioningService.yaml). |
| AC3 | Given an applied and a failed run, when the dispatcher publishes IaCProvisioningService/ProvisioningApplied on provisioning.runs.v1.provisioning-applied and IaCProvisioningService/ProvisioningFailed on provisioning.runs.v1.provisioning-failed, then each is sent under the run event envelope with the payload of the model, specificationVersion and outputs for the first and reason for the second, and a transport outage is retried with backoff so neither event is lost or published twice under its event id (SCN-IaCProvisioningService-009, SCN-IaCProvisioningService-010, ADR-0012). |
| AC4 | Given a program output marked secret and a secret reference issued for the apply, when the receipts, the events, the stored artifacts, the log records and the activities of the apply are scanned, then no secret value is found in any of them; given SecretBrokerService/SecretBroker.Issue does not answer, then the runner is not started and the run is Failed with a receipt naming the reference (SCN-IaCProvisioningService-010, ADR-0019). |
| AC5 | Given ArtifactService/Artifacts.Store does not answer when the Applier stores the logs and the state of a run whose fake runner succeeded and of a run whose fake runner failed, when the Applier settles them, then the first is Applied with IaCProvisioningService/ProvisioningApplied and the second Failed with IaCProvisioningService/ProvisioningFailed, each written once in the transaction of the service, each receipt records the logs and the state artifact as not stored with the reason, the store was called once per artifact and never again, and the cloud apply was not repeated (SCN-IaCProvisioningService-009, model/services/runtime-cloud/IaCProvisioningService.yaml). |
| Traces: services | IaCProvisioningService, SecretBrokerService, ArtifactService |
| Traces: aggregates | IaCProvisioningService/ProvisioningRun |
| Traces: apis | SecretBrokerService/SecretBroker.Issue, SecretBrokerService/SecretBroker.Revoke, ArtifactService/Artifacts.Store |
| Traces: events | IaCProvisioningService/ProvisioningApplied, IaCProvisioningService/ProvisioningFailed |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0004, ADR-0012, ADR-0014, ADR-0019 |
| Traces: requirements | FR-08, NFR-08, NFR-09 |
| Traces: scenarios | SCN-IaCProvisioningService-009, SCN-IaCProvisioningService-010 |
| Relates: screens | provisioning |
| Depends on | AIFACTORY-US-1073, feature:secret-broker-service, feature:artifact-service, feature:contracts-package |
| Sources | model/services/runtime-cloud/IaCProvisioningService.yaml, docs/architecture/adr/0004-pulumi-over-bicep-iac.md, docs/architecture/adr/0019-data-governance.md, docs/planes/execution/environments/services/ia-c-provisioning-service/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-328 Applier with brokered credentials, the runner timeout and the apply receipt |
implementation | The Applier takes runs in Applying under the key of run and apply, issues the secret references through SecretBroker.Issue for this apply only and revokes them through SecretBroker.Revoke, runs the IaC apply of the recorded plan with the runner workload identity and the apply timeout of the option, stores logs and state through Artifacts.Store, records outputs without secret outputs, duration, result and runner version, and moves the run to Applied or Failed with ProvisioningApplied or ProvisioningFailed in the same transaction; it never retries an apply, and an unavailable ArtifactService does not hold the run: the run is settled from the result of the runner and the receipt records each artifact that could not be stored as not stored with the reason, never retried in a loop. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-4320 Fake IaC runner, fake cloud control plane and the secret scan of the acceptance suite |
fixture | The acceptance suite holds a fake runner that succeeds, fails on a named resource with a partial state, exceeds the timeout and returns an output marked secret, a switch that makes the cloud control plane unreachable, fakes of SecretBroker.Issue, SecretBroker.Revoke and Artifacts.Store that record calls and can stop answering, and a scan of receipts, events, stored artifacts, log records and activities for the planted secret value. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-4321 Contracts of ProvisioningApplied and ProvisioningFailed against the run event envelope |
contract | Golden files fix ProvisioningApplied on provisioning.runs.v1.provisioning-applied and ProvisioningFailed on provisioning.runs.v1.provisioning-failed under run-event-envelope-v1 with the payload of model/services/runtime-cloud/IaCProvisioningService.yaml; a contract test fails when a serialised event differs from its file. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-4322 Verify apply-a-provisioning-run-with-receipts through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-IaCProvisioningService-009\|Scenario=SCN-IaCProvisioningService-010)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-1074 against the fakes of AIFACTORY-TASK-4320, including the single runner call per run, the secret scan, the fail-fast of the broker and the settlement with artifacts recorded as not stored while the artifact store does not answer; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-US-1075: Cancel a planned provisioning run before anything is applied¶
behavior · persona operator
As an operator, I want to cancel a provisioning run that was planned and not yet applied, so that a plan I no longer want, or one the policy denied, never reaches a cloud account.
An Operator or a Platform admin whose scope carries factory.provisioning.apply cancels a run through CancelProvisioning with its provisioningRunId. A run in state Planned moves to Cancelled (Cancel) and the response is 200 with the run; nothing was applied and nothing will be, so the Applier never takes it. The operation is naturally idempotent: cancelling a run that is already Cancelled returns 200 with the same run and changes nothing. A run in any other state is refused with 409 and a problem response that names its state, because the model cancels only before apply: a run in AwaitingApproval, Applying, Applied, Failed or Rejected cannot be cancelled, and an approval that is still pending is decided or expires in RunControlService. A run of another tenant is answered 404, the same answer as for an unknown provisioningRunId (ADR-0015 amendment D113); a caller without the scope, or without the Operator or Platform admin role in the project of the run, is refused with 403. The model gives the command no event, so a cancellation publishes nothing; connectsoft.factory.provisioning.runs counts it under the state Cancelled. This is also how an Operator ends a run the policy denied, or one with a constraint the service cannot honour, which stays Planned (AIFACTORY-US-1073).
Acceptance criteria
| AC1 | Given a run in state Planned and a caller with factory.provisioning.apply and the Operator role in its project, when IaCProvisioningService/CancelProvisioning is called, then the response is 200, the IaCProvisioningService/ProvisioningRun is Cancelled, the Applier never takes it and no event is written; the same call repeated returns 200 and changes nothing (SCN-IaCProvisioningService-005). |
| AC2 | Given runs in AwaitingApproval, Applying and Applied, when IaCProvisioningService/CancelProvisioning is called, then each answer is 409 with a problem response that names the state and the run is unchanged (SCN-IaCProvisioningService-005, model/services/runtime-cloud/IaCProvisioningService.yaml). |
| AC3 | Given a caller without factory.provisioning.apply or without a role in the project, a run of another tenant and an unknown provisioningRunId, when IaCProvisioningService/CancelProvisioning is called, then the first is answered 403 and the other two 404 alike, each with a problem response and no state change (SCN-IaCProvisioningService-005, ADR-0015). |
| Traces: services | IaCProvisioningService |
| Traces: aggregates | IaCProvisioningService/ProvisioningRun |
| Traces: apis | IaCProvisioningService/CancelProvisioning |
| Traces: adrs | ADR-0015 |
| Traces: requirements | FR-08 |
| Traces: scenarios | SCN-IaCProvisioningService-005 |
| Relates: screens | provisioning |
| Depends on | AIFACTORY-US-1073 |
| Sources | model/services/runtime-cloud/IaCProvisioningService.yaml, docs/planes/execution/environments/services/ia-c-provisioning-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-4323 CancelProvisioning with the transition Planned to Cancelled and its refusals |
implementation | The operation moves a Planned run to Cancelled under the row version of the run, returns 200 and repeats idempotently, answers 409 naming the state for any other state, 404 for a run of another tenant as for an unknown id and 403 for a missing scope or project role, writes no outbox record and counts the run under the state Cancelled. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-4324 Verify cancel-a-planned-provisioning-run through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-IaCProvisioningService-005"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1075, including a cancel that races the move of the gate from Planned to Applying, which loses on the row version and leaves the run in the state the winner wrote. |
ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-US-1076: Plan runs from the hand-offs of a new environment, a promotion and an accepted reconciliation, and re-plan the declared state on a schedule¶
behavior · persona operator
As an operator, I want new environments, approved promotions and accepted reconciliations to become provisioning runs without anyone planning them by hand, so that the declared state is planned through one path and a destructive difference never reaches a cloud account automatically.
Three consumed events and one schedule start provisioning runs; each handler is idempotent on the event id through the inbox of the iac-provisioning profile, and every run they start passes the gate of AIFACTORY-US-1073. EnvironmentCreated of EnvironmentService is handled by ProvisionBaseline: the new environment gets a specification of kind EnvironmentBaseline declared for the program of the environment stack of the estate (feature component-platform-template-environment-stack) and a run of kind EnvironmentBaseline planned against it. The event carries the environment, the project, the tenant and the class and no program reference; where the handler takes the program reference and commit of the baseline from is not decided by the model and is reported to the owner, and until it is decided the acceptance suite proves the handler with a fixture reference, while a reference that does not resolve fails the run with the reference named, as for a program version that is not found. PromotionApproved of EnvironmentPromotionService is handled by ProvisionPromotion: its desiredStateRef declares a Workload specification version with the releaseId and the strategy of the event when it names a new commit, and a run of kind Promotion with the promotionId of the promotion is planned. approvalId is optional in the event, because only a production promotion carries an approval: a run that carries one has it reused for the production apply and no second approval is requested, and a run without one, a non-production promotion, is gated by Policy.Decide like every other run, the runId of the envelope being the run an approval request names. ReconciliationDecided of RuntimeEnvironmentService is handled by ProvisionReconciliation: an accepted proposal carries the provisioningRunId that RuntimeEnvironmentService assigned on acceptance, and the handler creates a run of kind Reconciliation of the current specification of the environment under that id, idempotently, so a run that already holds the id is not created again and RuntimeEnvironmentService relates the outcome to the proposal by that id in ProvisioningApplied; an accepted decision without a provisioningRunId creates nothing and is logged; a rejected one changes nothing. The model gives RuntimeEnvironmentService an outbound gRPC dependency on this service to plan accepted proposals, but this service has no gRPC method to plan, so the hand-off goes through the event and the missing method is reported as a gap. The event carries neither the direction of the proposal nor a specification version, so the handler always plans the declared state; adopting an observed state is a change of the program in Git, and the missing members are reported as a correction of the model. The two producers of these events are delivered in this increment and depend on this service, so their event types are taken from the pinned contracts package and proven against fixture events; their own suites prove the publication. The GitOpsReconciler re-plans the declared specification of every environment on its schedule, once per environment and window: it records a run of kind Reconciliation with its plan receipt and ProvisioningPlanned, and counts the differences in connectsoft.factory.provisioning.reconciliation_diffs by tenant and whether they are destructive. An empty plan ends Cancelled with the reason no-changes by the rule of AIFACTORY-US-1073. The reconciler plans no run for an environment that already has a Reconciliation run of the reconciler still Planned or AwaitingApproval, so a waiting run is never joined by a second one. A plan whose differences are only adds and changes goes to the gate when the option RuntimeCloud:Provisioning:AutoApplyNonDestructive is true and is applied only when the policy decision allows it; with the option false the reconciler applies nothing automatically. Under the seeded tenant bundle the decision for these runs is allow-with-approval for a plan of the class production or external, and a reconciler run is put to approval with the provisioning run as its subject although it has no Factory runId (D129, D135, AIFACTORY-US-1073); at most one of its runs waits per environment, as stated above, and the option applies a run without an approval once the tenant bundle answers allow for it. A plan with deletes, and any plan against a production environment, is never applied by the reconciler: the run stays Planned with its receipt as the record of the difference, and the reviewable correction is the reconciliation proposal that RuntimeEnvironmentService raises from its own drift findings; whether the reconciler should cancel such a run is reported as an open point.
Acceptance criteria
| AC1 | Given a fixture EnvironmentService/EnvironmentCreated for a new environment and a fixture baseline program reference, when ProvisionBaseline handles it, then a specification of kind EnvironmentBaseline is declared with IaCProvisioningService/SpecificationDeclared, a run of kind EnvironmentBaseline is planned with IaCProvisioningService/ProvisioningPlanned, and the same event delivered again changes nothing; given a reference that does not resolve, then the run is Failed with the reference named (model/services/runtime-cloud/IaCProvisioningService.yaml). |
| AC2 | Given fixtures PromotionApproved from the pinned contracts package naming a new commit, one with an approvalId and one without, when ProvisionPromotion handles them, then each declares a Workload specification version with the releaseId and the strategy of the event and plans a run of kind Promotion with its promotionId; the run with the approval passes its gate without a policy decision or a second approval, the run without it asks PolicyEngineService/Policy.Decide like every other run and, on allow-with-approval, requests the approval naming the runId of the envelope; IaCProvisioningService/ProvisioningPlanned carries the promotionId (model/services/runtime-cloud/IaCProvisioningService.yaml, ADR-0014). |
| AC3 | Given a fixture ReconciliationDecided accepted with a provisioningRunId, the same event delivered again, and one rejected, when ProvisionReconciliation handles them, then the accepted one creates a run of kind Reconciliation of the current specification under that provisioningRunId and announces it with IaCProvisioningService/ProvisioningPlanned carrying that id, the repeat creates nothing, and the rejected one changes nothing (ADR-0014, model/services/runtime-cloud/RuntimeEnvironmentService.yaml). |
| AC4 | Given environments whose declared state differs from the observed resources by adds only, by a delete, and an environment of class Production, when the GitOpsReconciler runs twice in one window, then each environment gets one run with IaCProvisioningService/ProvisioningPlanned, the adds-only plan is applied when the option is true and the fake policy answers allow, the plans with a delete and against Production stay Planned and apply nothing, and the differences are counted by tenant and destructive; given the fake policy answers allow-with-approval, then the adds-only run waits in AwaitingApproval with an approval requested through RunControlService/RunControl.RequestApproval for the subject kind provisioning-run, nothing is applied and the next window plans no second run of that environment while it waits (model/services/runtime-cloud/IaCProvisioningService.yaml). |
| Traces: services | IaCProvisioningService, EnvironmentService, EnvironmentPromotionService, RuntimeEnvironmentService |
| Traces: aggregates | IaCProvisioningService/DeploymentSpecification, IaCProvisioningService/ProvisioningRun |
| Traces: apis | PolicyEngineService/Policy.Decide, RunControlService/RunControl.RequestApproval |
| Traces: events | EnvironmentService/EnvironmentCreated, IaCProvisioningService/SpecificationDeclared, IaCProvisioningService/ProvisioningPlanned |
| Traces: adrs | ADR-0004, ADR-0012, ADR-0014 |
| Traces: requirements | FR-08, XL-10 |
| Depends on | AIFACTORY-US-1071, AIFACTORY-US-1073, feature:policy-engine-service, feature:run-control-service, feature:environment-service, feature:component-platform-template-environment-stack, feature:contracts-package |
| Sources | model/services/runtime-cloud/IaCProvisioningService.yaml, model/services/control-plane/EnvironmentService.yaml, model/services/devops-gitops/EnvironmentPromotionService.yaml, model/services/runtime-cloud/RuntimeEnvironmentService.yaml, docs/planes/execution/environments/services/ia-c-provisioning-service/index.md#sagas-and-long-running-flows |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-4325 Inbox handlers ProvisionBaseline, ProvisionPromotion and ProvisionReconciliation |
implementation | ProvisionBaseline declares an EnvironmentBaseline specification for the program reference of the estate and plans a baseline run; ProvisionPromotion declares a Workload version with the releaseId and the strategy of the event for a new commit of desiredStateRef and plans a Promotion run carrying the promotionId and, where present, the approvalId, a run without an approvalId passing the policy gate of AIFACTORY-US-1073 with the runId of the envelope; ProvisionReconciliation creates a Reconciliation run of the current specification under the provisioningRunId of an accepted decision, creates nothing for an id that already exists or an accepted decision without one, and ignores a rejected one; each handler is idempotent on the event id and takes its event type from the pinned contracts package. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-4326 GitOpsReconciler with the window key, the option and the destructive rule |
implementation | The GitOpsReconciler plans one Reconciliation run per environment with a declared specification and window, and none for an environment that still has a reconciler run Planned or AwaitingApproval; it counts differences in connectsoft.factory.provisioning.reconciliation_diffs by tenant and destructive, ends an empty plan Cancelled with the reason no-changes, sends an adds-and-changes plan to the policy gate only when RuntimeCloud:Provisioning:AutoApplyNonDestructive is true, puts a run the gate answers with allow-with-approval to approval with the subject kind provisioning-run and leaves it in AwaitingApproval, and never lets a plan with deletes or against a production environment reach the Applier. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-4327 Fixture events of the three hand-offs and a fixture baseline program reference |
fixture | The acceptance suite holds fixture events EnvironmentCreated, PromotionApproved with and without an approvalId, and ReconciliationDecided accepted with a provisioningRunId and rejected, built from the event types of the pinned contracts package under the run event envelope with a correlation id, a fake Policy.Decide that answers allow and allow-with-approval, a fixture baseline program reference and commit for the environment stack, and a fake planner whose differences are configured per environment. | ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |
AIFACTORY-TASK-4328 Verify provisioning-hand-offs-and-gitops-reconciliation through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Feature=HandOffsAndReconciliation"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1076, including the repeated delivery of each hand-off, the unresolved baseline reference, the reuse of the promotion approval and the policy gate of a promotion without one, the run created under the provisioningRunId of the decision, the two reconciler runs in one window and the run waiting in AwaitingApproval under allow-with-approval with no second run planned beside it. |
ConnectSoft.AI.SoftwareFactory.IaCProvisioningService |