quinzee.cloud

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.

Developer’s guide

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.