SSLZ Agent documentation · Launch the agent · Classic direct-operator site
Approved Deployment Integration
Signed single-use approval for one immutable existing SSLZ platform deployment
Evidence status
The write-capable path and workflow gates are implemented and covered by local synthetic and hosted CI tests. This
repository does not contain or identify a successful approved Phase 6 apply and postcheck record for current main.
Historical Integration Test what-if/plan success predates this path’s later hardening and is not live deployment evidence.
See the implementation and evidence matrix.
Roadmap: live validation of this path is planned and not done yet. It needs a nonproduction run on a protected
sslz-deployment runner with signed approval, apply, postchecks, and rollback review. Until that record exists, treat
this path as implemented and tested locally, not proven live. For a tested deployment today, use the Classic Terraform
or Bicep workflows in the CI/CD guide.
Purpose
Phase 6 is the only landing-zone write path exposed by deploy-bicep.yml and deploy-terraform.yml. Both workflows are
manual-dispatch-only wrappers over the existing infra/bicep and infra/terraform roots and require protected
self-hosted runners. Phase 6 does not deploy workload modules, register providers, change roles outside the existing
root, or add a second region. Only an approved primary single-region-ready platform baseline is executable.
The versioned contracts are:
iac-plan-input-v2.schema.jsoniac-plan-input-v3.schema.jsonreadiness-evidence.schema.jsonaks-ingress-decision.schema.jsonaks-ingress-postcheck.schema.jsonsubscription-topology-decision.schema.jsondeployment-execution-manifest.schema.jsondeployment-approval.schema.jsondeployment-result.schema.jsonregional-attempt.schema.jsonterraform-plan-provenance.schema.json
Prepare the reviewed Phase 4 artifact
Generate an approved Phase 4 plan with a real command preview. Terraform requires an explicit raw-artifact directory so the reviewed saved plan is available:
Use the 3.0.0 IaC input contract for plans intended for Phase 6. It requires the exact remote-backend subscription and
the current readiness-evidence artifact. Versions 1.0.0 and 2.0.0 remain accepted by the standalone Phase 4 planner
for compatibility but are not eligible for approved execution.
SSLZ_TERRAFORM_PROVENANCE_PRIVATE_KEY_FILE=/protected/sslz-terraform-builder.key \
SSLZ_TERRAFORM_EXECUTABLE=/opt/hashicorp/terraform \
./scripts/startup-iac-plan.sh generate \
--input <approved-iac-plan-input.json> \
--provider terraform \
--output-dir .sslz/generated/my-plan \
--preview \
--raw-artifact-dir .sslz/generated/my-plan/raw \
--notification-contacts-file /protected/sslz-notification-contacts.json
The Phase 6 preview rejects fixture, missing, failed, destructive, secondary-region, expired, or changed Phase 4
artifacts. Resource Manager Defender must remain selected because the existing roots deploy it as Standard. Storage
Defender is review-bound but may be false; generated Bicep and Terraform inputs carry that decision exactly and only
select Standard with DefenderForStorageV2 after explicit opt-in.
Terraform also requires the builder-signed provenance emitted by Phase 4. It proves that the exact saved plan was
generated inside an atomic protected snapshot of the reviewed source, parameters, backend, provider lock, Terraform
executable digest and platform/version, and complete plan semantics. Preview and apply must resolve the exact same
Terraform executable digest through SSLZ_TERRAFORM_EXECUTABLE or a documented trusted installation path.
Zero-write preview
SSLZ_TERRAFORM_PROVENANCE_PUBLIC_KEY_FILE=/protected/sslz-terraform-builder.pub \
./scripts/startup-deployment-integration.sh preview \
--plan .sslz/generated/my-plan/<attempt>/plan-summary.json \
--provider terraform \
--environment prod \
--output json
Preview performs no Azure or local write. It:
- validates the approved Phase 4 plan, readiness artifact and topology decision digests/scopes/freshness, and expiry;
- selects exactly one primary provider and environment;
- hashes the complete plan artifact, selected parameters, current SSLZ source tree, controlled Terraform CLI configuration, and Terraform lock file;
- compiles and semantically inspects the exact Bicep source and concrete parameter values before rerunning what-if, or inspects the exact saved Terraform plan;
- rejects destructive or unclassified changes; Bicep resources outside the exact existing type/count/scope graph, external templates/modules, deployment scripts, or unexpected role/principal bindings; and any Terraform provider, external module, provisioner/action hook, resource address/type, role, managed-identity principal, or subscription scope outside the existing SSLZ graph;
- emits a byte-deterministic immutable manifest inside the sanitized result.
The same validation rechecks the Defender workspace decision and binds its ID/digest, effective region, placement mode, scope/reference digest, policy-evidence digest/freshness, and paid-plan selection digest. Missing fields, changed or stale evidence, default-region fallback, or a tenant/subscription mismatch fails before execution is accepted.
Raw what-if, Terraform JSON, environment values, contact values, and approval identities are discarded. Only hashes,
change counts, fixed commands, targets, and schema-defined status are retained. Bicep local modules must resolve inside
the approved source snapshot; imports, registry/template-spec modules, dynamic file/environment reads, copy loops,
external templates, and cross-subscription scopes are rejected. The manifest binds the compiled template, concrete
parameters, and exact semantic resource graph digests. For Terraform, it includes a semantic attestation of the
canonical configuration, provider graph, planned values, changes, variables, exact resource graph/scopes, backend,
source, parameters, and saved plan. The review system stores the nested manifest as the reviewed deployment-manifest
artifact, and its signature binds every attestation digest.
The manifest and approval expose a dedicated privacy-preserving digest of the budget and security notification recipients. Before signing, the approval service must recompute that digest from its authorization-controlled recipient policy and reject any mismatch. This permits real contacts without writing personal addresses into the manifest, approval, result, audit state, or logs.
Trusted approval
Apply accepts only an Ed25519-signed approval. The signed payload uses canonical JSON with sorted object keys, excludes
only signature, and is prefixed with sslz-deployment-approval-v1 plus a NUL byte. keyId is the SHA-256 digest of
the trusted public key’s SPKI DER representation.
The approval duplicates and binds the manifest digest, plan identity, readiness evidence version/opaque ID/digest/expiry, topology decision ID/digest/expiry and exact environment mapping, provider, environment, primary region, tenant, subscription, exact subscription scope, protected durable-store identity, parameter/source/saved-plan hashes, Terraform authentication choice, notification-recipient commitment, unique nonce, and validity window. The window cannot exceed 24 hours. It also duplicates every Defender workspace binding from the manifest, so omission or mutation invalidates the signature and replay record.
For AKS plans, the manifest and signed approval also duplicate the ingress mode, normalized decision digest, and expected
postcheck digest. Omission, mutation, mode switching, or replay against a different ingress mapping fails before any
write. Planning postchecks contain only not-observed placeholders. Acceptance or recovery requires fresh supplied
health and TCP/HTTP reachability evidence with timestamps and an opaque reference; deployment output alone is not a live
connectivity claim.
The approval also binds the regional attempt ID, attempt digest and number, original and target regions, and reviewed Terraform state key. Switching regions therefore invalidates the prior manifest and approval even if every other target field is unchanged.
Regional failure, cleanup, and replan
Regional attempts form an append-only 1.0.0 chain. Each attempt records its original and target region, attempt number,
plan and artifact digests, deterministic deployment/resource/policy names, Terraform state/workspace identity, immutable
failure-evidence hash, and lifecycle state. Bicep and Terraform derive the same attempt key, while retaining
provider-specific artifact roots.
After a deployment write starts, a failure moves the attempt to cleanup-required. Preserve the original sanitized
failure evidence and perform only a reviewed, bounded cleanup of resources proven to belong to that attempt. There is no
automatic rollback and no broad resource-group deletion. A failed cleanup remains visible and blocks both replan and
alternate-region execution. Only a successful cleanup record can move the chain to cleaned and permit replanned.
Changing the target region requires a new attempt number and fresh Phase 4 plan, previews, saved Terraform plan or Bicep
what-if, manifest, and signed approval. Never copy a .tfplan, workspace, what-if result, manifest, or approval from the
failed region. Terraform retains the reviewed chain backend key only to preserve ownership of subscription-level
singletons; the cleaned predecessor record, chain lock, fresh provenance, and new approval gate every reuse. Later
attempts use collision-safe nested deployment names, policy-assignment names, resource suffixes, workspaces, and artifact
paths. Policy assignments retain their existing system-assigned
identity architecture, so their location-bound identities are never adopted across regions: cleanup and recreation are
mandatory. An unchanged-region retry may reuse the chain only when safeSameRegionRetry is explicitly evidenced; it
still receives a new attempt record and cannot mutate prior evidence.
Provision the trusted public-key file outside the repository through the protected runner configuration:
export SSLZ_DEPLOYMENT_APPROVAL_PUBLIC_KEY_FILE=/protected/sslz-deployment-approver.pub
The CLI does not accept a trust-key override. The approval system must protect the signing key and authorize the human review. The repository stores neither key material nor approval identity.
Apply
SSLZ_TERRAFORM_PROVENANCE_PUBLIC_KEY_FILE=/protected/sslz-terraform-builder.pub \
SSLZ_DEPLOYMENT_APPROVAL_PUBLIC_KEY_FILE=/protected/sslz-deployment-approver.pub \
./scripts/startup-deployment-integration.sh apply \
--plan .sslz/generated/my-plan/<attempt>/plan-summary.json \
--manifest <reviewed-deployment-manifest.json> \
--approval <signed-deployment-approval.json> \
--output json
Apply atomically reserves the approval beneath .sslz/deployment-state/, rehashes every artifact, verifies the
signature and expiry again, and copies the exact verified source, parameters, controlled CLI configuration, and saved
plan into a random owner-only execution snapshot. Bicep template and parameters are compiled together exactly once
from that snapshot; all three semantic digests must still match, and only the resulting read-only ARM JSON files are
passed to Azure. Terraform executes only the protected saved-plan snapshot. A concurrent worktree replacement therefore
cannot change the approved bytes. The snapshot is removed on every result path and is never written to deployment state
or output. The exact enabled tenant and subscription are rechecked immediately before execution. Every Azure CLI
resource operation includes --subscription, uses a fixed argument array, and runs without a shell.
- Bicep: executes
az deployment sub createwith the exact reviewed parameters. Azure subscription-scope deployments are incremental-only; the CLI exposes no complete-mode option, and Phase 6 accepts no mode override. Effective policy role assignments, including parent-scope inheritance, are read back after deployment; extra roles for those managed identities fail the workload gate. - Terraform: initializes the exact reviewed remote backend subscription with Azure AD data-plane authentication,
-lockfile=readonly, a repository-controlled direct-only provider installation configuration, and a case-insensitive allowlist of required environment variables. AmbientTF_CLI_ARGS*,TF_VAR_*, provider reattachment, plugin-cache, and custom CLI configuration values are not inherited. Both AzureRM legacy and additive automatic provider registration are disabled and rejected in inspected plans; Phase 5 remains the only approved registration path. The default provider and the tightly scoped Defender workspace alias must reference the exact reviewedsubscription_idvariable; the alias may bind only the singleton workspace association and is the only surface permitted to reconcile an existing remote resource. Terraform’s builtin provider may bind only the passing workspace-placement guard. Any resolved resource ID or scope in another subscription is rejected. Every role principal must already resolve in the saved plan to the exact policy-assignment managed identity; an unknown principal fails closed before approval. CLI and OIDC authentication modes are forced in the sanitized child environment, and the live Terraform version and platform are verified before the single-use approval is reserved. It then applies the exact saved.tfplan; apply never runsterraform plan.
Apply fails closed unless .sslz/deployment-state/ is a pre-provisioned owner-protected local directory containing an
owner-protected .durable-store.json marker with exactly:
{
"schemaVersion": "1.0.0",
"durable": true,
"storeId": "00000000-0000-4000-8000-000000000000"
}
Use a provisioned unique UUID for storeId; do not use the example. Keep the store only at the fixed
repository-relative .sslz/deployment-state path. The manifest and signed approval bind a privacy-preserving effective
identity derived from the marker UUID and the mounted directory and marker filesystem identities, so copying the marker
to a fresh directory cannot create a new replay namespace. Preview and apply for an approval must run on the same protected executor and unchanged local filesystem identity. Apply
never creates or silently substitutes the durable store. Atomic single-use records block replay and concurrent use on
that executor. Workflow concurrency is shared across Bicep and Terraform for the whole environment, regardless of
regional-attempt chain, so provider or chain switching cannot create parallel attempts. The state stores only allowlisted hashes, targets, phases,
timestamps, and result codes.
Post-deployment gate
A successful deployment command does not count as success on its own. Phase 6 checks the expected resource groups, Log Analytics retention and quota, Activity Log destination and categories, exact policy assignments and regional parameters, selected Defender tiers, monthly budget and notification thresholds, the approved live budget and Defender recipient commitment, and the expected VNet. Reads are retried for bounded Azure propagation.
workloadDeploymentAllowed remains false until every check passes. A deployment or validation failure consumes the
approval, records a rollback-review code, and performs no workload deployment or automatic rollback. Review the
sanitized result, correct the platform or revert the existing IaC, then create a new Phase 4 plan, manifest, and
approval.
The repository’s separate integration-test apply is limited to a dedicated disposable subscription and
integration-nonprod environment. Its Terraform destroy step runs after every started apply, including partial apply
failure. Cleanup is reported separately and never replaces the original apply diagnostic.
Privilege and rollback boundaries
Grant only the permissions already required by the selected SSLZ root at the exact target subscription, plus read access for the postchecks and remote Terraform backend. Phase 6 never creates an extra role, elevates itself, changes billing or entitlements, registers features or providers, unregisters providers, verifies domains, or runs arbitrary commands.
Disable deployment by removing the sslz-deployment runner label or access to
startup-deployment-integration.sh. There is no direct workflow fallback: a new write requires a current Phase 4 v3
plan, readiness evidence, reviewed immutable manifest, and matching signed single-use approval.
Direct operator use of infra/bicep, infra/terraform, or the example deployment commands remains outside these
agent-gated workflows. Those commands can write Azure without a Phase 6 artifact; the operator is responsible for access,
plan review, change approval, state protection, postchecks, and rollback.