Development edition · 16 November 2026. Commands using repository paths, Make targets or sample projects require access to the Quinzee source checkout. No public installer is available. Examples use disposable local environments.
24. Turn infrastructure into repeatable deployments
Your application needs more than executable code. It needs named storage,
queues, identities and endpoints. Infrastructure as code records those choices
in a file so that the next developer can build the same environment. In this
workshop, Bicep is the source language and ARM JSON is the document sent to
Quinzee. You can author either; you do not deploy a .bicep file directly.
Step 1: create a small ARM template by hand
Create .local/book-iac with mkdir -p .local/book-iac, then save this complete
file as .local/book-iac/storage.json. The resource group is the deployment
boundary; the template does not create the subscription or group itself.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"accountName": { "type": "string", "defaultValue": "bookhandstore" }
},
"resources": [
{
"type": "Microsoft.Storage/storageAccounts",
"apiVersion": "2023-05-01",
"name": "[parameters('accountName')]",
"location": "[resourceGroup().location]",
"kind": "StorageV2",
"sku": { "name": "Standard_LRS" }
}
],
"outputs": {
"accountName": { "type": "string", "value": "[parameters('accountName')]" }
}
}
type identifies the provider and resource. apiVersion identifies the contract,
not the installed software version. The expression in name reads an input;
resourceGroup().location uses the group's location. outputs return useful
results to the next step. Outputs are readable deployment metadata, so never
put a password or client secret there.
Step 2: express the same intention in Bicep
Save .local/book-iac/storage.bicep:
targetScope = 'resourceGroup'
param accountName string = 'bookhandstore'
resource account 'Microsoft.Storage/storageAccounts@2023-05-01' = {
name: accountName
location: resourceGroup().location
kind: 'StorageV2'
sku: { name: 'Standard_LRS' }
}
output accountName string = account.name
Compile it on the host:
python3 scripts/deps/bicep.py build .local/book-iac/storage.bicep \
--outfile .local/book-iac/storage.json
Open the resulting JSON. Find the same resource type, version, name expression and SKU. The compiler may add metadata and explicit dependency expressions; these are normal. Keep Bicep as the file you edit, and compile after every change. The repository helper verifies and caches the official compiler. It does not log in to Azure or send the template to Microsoft.
Step 3: deploy to a deliberately chosen environment
For this separate workshop, run make qhq-run on the host and leave it running.
It creates a default local cloud and trusted certificate material. It is separate
from the browser application's environment used earlier in the book. Open a
second host terminal. The following command uses a new book-iac resource group;
change the name if it already contains work you want to keep separate.
python3 examples/book-iac/deploy.py \
--endpoint https://localhost:11443 \
--ca .local/certificates/ca/quinzee-dev-root-ca.crt \
--credentials .local/quinzee/credentials.json \
--group book-iac --name hand-storage \
--template .local/book-iac/storage.json \
--outputs .local/book-iac/hand-storage-outputs.json
The deployment client below is printed in full so you can understand and adapt
it. It reads a private credential file, obtains an ARM token, creates the group
if absent, validates the template, submits an Incremental deployment, polls to
completion and writes outputs with mode 0600. It chooses a subscription only
when exactly one exists; otherwise supply --subscription <UUID>. It rejects
redirects and verifies the supplied CA. No secret appears in a command argument.
#!/usr/bin/env python3
"""Deploy a compiled ARM template to a chosen local HTTPS environment.
Credentials and secure parameters stay in private files; no Azure login required.
"""
import argparse
import json
import os
from pathlib import Path
import ssl
import time
import urllib.error
import urllib.parse
import urllib.request
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--endpoint', required=True)
parser.add_argument('--ca', type=Path, required=True)
parser.add_argument('--credentials', type=Path, required=True)
parser.add_argument('--subscription')
parser.add_argument('--group', required=True)
parser.add_argument('--location', default='westeurope')
parser.add_argument('--name', default='book')
parser.add_argument('--template', type=Path, required=True)
parser.add_argument('--parameters', type=Path)
parser.add_argument('--outputs', type=Path, required=True)
parser.add_argument('--validate-only', action='store_true')
args = parser.parse_args()
origin = args.endpoint.rstrip('/')
parsed = urllib.parse.urlsplit(origin)
if parsed.scheme != 'https' or not parsed.hostname or parsed.path or parsed.query or parsed.fragment or parsed.username:
parser.error('endpoint must be an HTTPS origin without credentials or a path')
for name in (args.group, args.name):
if not name or any(c not in 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.()' for c in name):
parser.error('group and deployment names must be simple ASCII identifiers')
trust = ssl.create_default_context(cafile=str(args.ca))
# Reject HTTP redirects rather than sending a token to another destination.
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
client = urllib.request.build_opener(urllib.request.HTTPSHandler(context=trust), NoRedirect())
token = ''
def request(method, path, body=None):
headers = {'Authorization': 'Bearer ' + token} if token else {}
if isinstance(body, dict):
body = json.dumps(body).encode()
headers['Content-Type'] = 'application/json'
elif isinstance(body, str):
body = body.encode()
headers['Content-Type'] = 'application/x-www-form-urlencoded'
with client.open(urllib.request.Request(origin + path, data=body, headers=headers, method=method), timeout=30) as response:
raw = response.read()
return json.loads(raw) if raw else {}
credentials = json.loads(args.credentials.read_text())
token = request('POST', '/' + credentials['tenantId'] + '/oauth2/v2.0/token', urllib.parse.urlencode({
'grant_type': 'client_credentials', 'client_id': credentials['clientId'],
'client_secret': credentials['clientSecret'], 'scope': 'https://management.azure.com/.default'}))['access_token']
subscription = args.subscription
if not subscription:
subscriptions = request('GET', '/subscriptions?api-version=2023-05-01')['value']
if len(subscriptions) != 1:
parser.error('specify --subscription when the environment has multiple subscriptions')
subscription = subscriptions[0]['subscriptionId']
import uuid
subscription = str(uuid.UUID(subscription))
group = '/subscriptions/' + subscription + '/resourceGroups/' + args.group
try:
request('GET', group + '?api-version=2023-05-01')
except urllib.error.HTTPError as error:
if error.code != 404: raise
if args.validate_only:
parser.error('create the group before validating, or deploy without --validate-only')
request('PUT', group + '?api-version=2023-05-01', {'location': args.location})
parameters = json.loads(args.parameters.read_text()) if args.parameters else {}
parameters = parameters.get('parameters', parameters)
body = {'properties': {'mode': 'Incremental', 'template': json.loads(args.template.read_text()), 'parameters': parameters}}
path = group + '/providers/Microsoft.Resources/deployments/' + args.name
request('POST', path + '/validate?api-version=2022-09-01', body)
print('Template validation succeeded.')
if args.validate_only: return
request('PUT', path + '?api-version=2022-09-01', body)
deadline = time.monotonic() + 240
while time.monotonic() < deadline:
result = request('GET', path + '?api-version=2022-09-01')['properties']
state = result['provisioningState']
if state == 'Failed':
raise RuntimeError('Deployment failed; inspect its operations in QHQ. Completed resources remain.')
if state == 'Succeeded':
args.outputs.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
fd = os.open(args.outputs, os.O_WRONLY | os.O_CREAT | os.O_TRUNC | os.O_NOFOLLOW, 0o600)
with os.fdopen(fd, 'w') as out:
os.fchmod(out.fileno(), 0o600)
json.dump(result.get('outputs', {}), out, indent=2)
out.write('\n')
print('Deployment succeeded. Outputs saved privately to', args.outputs)
return
time.sleep(1)
raise TimeoutError('Deployment still running; inspect QHQ before retrying.')
if __name__ == '__main__':
try: main()
except urllib.error.HTTPError as error:
raise SystemExit(f'HTTP {error.code}; check the endpoint, permissions and deployment operations.') from None
The expected result is “Template validation succeeded” followed by “Deployment
succeeded”. In QHQ open Resource Manager → Deployments, select book-iac,
refresh, and inspect hand-storage. The storage page should contain
bookhandstore. The outputs file contains the resolved account name.
Step 4: use parameters without baking secrets into source
A parameters file maps names to value objects. Save this as
.local/book-iac/parameters.json:
{ "accountName": { "value": "booksecondstore" } }
Add --parameters .local/book-iac/parameters.json and use a new deployment name.
This creates another named resource: changing a name does not rename the old
one. For database examples, generate the password in a private file:
umask 077
python3 - <<'PYSECURE'
from pathlib import Path
import json, secrets
p = Path('.local/book-iac/database-parameters.json')
p.write_text(json.dumps({'password': {'value': secrets.token_urlsafe(24)}}))
p.chmod(0o600)
PYSECURE
Bicep @secure() becomes ARM secureString. Quinzee omits those input values
from deployment history, but the local parameter file still contains a secret.
Protect it, back it up only with private backups, and never put it in Git.
Step 5: reason about dependencies and failure
A Bicep parent makes a child resource's full name and dependency explicit.
Using another resource's properties usually creates an implicit dependency;
dependsOn expresses an additional ordering requirement. ARM JSON carries
those relationships in dependsOn. A resource reference reads the provisioned
result, such as an identity's generated principal ID. It cannot substitute for
an unsupported cross-scope or external deployment.
Validation catches template syntax, unsupported expressions, API versions and dependency mistakes. It does not prove that an external runtime is reachable or that every service property will pass provider validation. A later failure can leave earlier resources created. Inspect the per-resource operation, fix the cause, and redeploy the same intended resource names. Incremental redeployment preserves resources omitted from the new file. Deleting deployment history also preserves resources. Deleting a resource group removes its resources and data.
Quinzee accepts resource-group, inline, Incremental templates. It rejects Complete mode, linked/nested templates, resource loops, resource conditions and arbitrary ARM functions. Use the examples' supported expressions rather than assuming any Bicep feature will work merely because the compiler accepts it.
Know what belongs outside an ARM template
ARM describes resources exposed by a resource provider. It does not configure every process or directory object in Quinzee. Keep these boundaries explicit:
| Task | Interface to use |
|---|---|
| Storage, vaults, configuration, events, messaging, SQL/cache, monitoring, hosted apps | The Bicep/ARM service lessons that follow |
| User-assigned managed identities and Azure resource role assignments | Microsoft.ManagedIdentity and Microsoft.Authorization resources |
| App registrations, service principals, people, groups and API app roles | Graph-shaped directory APIs or QHQ, as practiced in the identity chapter |
| LDAP listener, dedicated directory PostgreSQL, certificates and helper processes | Operator configuration; these are prerequisites, not template resources |
| Local DNS records and module loading | Quinzee management controls; no Azure DNS zone provider is implied |
In particular, an application registration is not a Microsoft.Web site. Creating a site gives you hosting; registering an application gives OAuth a client/API identity. The identity chapter connects them through a service principal and explicit permissions. Do not invent an ARM resource type to replace that step.
Step 6: work through the service lessons
The following chapters contain complete Bicep files plus the corresponding ARM
resource objects. To hand-author ARM, place those objects in the complete
resources array shown above and include the stated parameters. Compiling the
Bicep creates the complete executable ARM document automatically, including
parameters, dependencies and outputs. Each lesson states the expected result,
runtime prerequisites and what you should deliberately change next.