Configuration Reference

All configuration is provided through environment variables with the VENDING_ prefix.
Variables can also be placed in a .env file in the project root (loaded automatically by Pydantic Settings).

Copy .env.example to .env and fill in the values before starting the service.

For guidance on which variables are secrets and how to handle them securely in each deployment context, see secrets.md.

Azure credentials

When both VENDING_AZURE_CLIENT_ID and VENDING_AZURE_CLIENT_SECRET are populated the service uses ClientSecretCredential. If either is empty, ManagedIdentityCredential is used instead. Managed Identity is recommended for all Azure-hosted deployments.

Management group placement

Environment → Management Group mapping

VENDING_ENVIRONMENT_MG_MAPPING accepts a JSON object where each key is an itl-environment tag value and each value is the target management group name.

Default mapping:

VENDING_ENVIRONMENT_MG_MAPPING='{
  "production": "ITL-Production",
  "staging": "ITL-Staging",
  "development": "ITL-Development",
  "sandbox": "ITL-Sandbox"
}'

Any number of additional environments can be added:

VENDING_ENVIRONMENT_MG_MAPPING='{
  "production":  "ITL-Production",
  "staging":     "ITL-Staging",
  "development": "ITL-Development",
  "sandbox":     "ITL-Sandbox",
  "acceptance":  "ITL-Acceptance",
  "test":        "ITL-Test",
  "customer-a":  "CustomerA-Prod",
  "customer-b":  "CustomerB-Prod"
}'

If the itl-environment tag value is not found in the mapping, the subscription falls back to the sandbox management group (or ITL-Sandbox if that key is also absent from the mapping). If the JSON value is malformed, the entire mapping falls back to {"sandbox": "ITL-Sandbox"}.

RBAC role assignments

The following variables control which Azure AD principals receive default role assignments on each new subscription. Leave a variable empty to skip the corresponding role assignment.

Note: These values are Azure AD object IDs, not display names or client IDs. You can look up object IDs in the Azure Portal under Azure Active Directory → Groups / Enterprise applications.

Budget alerts

Authorization service

Keycloak

Event Grid

Feature flags

Extensions

These variables are read by the built-in extension modules in extensions/. They are optional — leave them unset to disable the corresponding extension.

Webhook notify (extensions/webhook_notify.py)

Posts the provisioning result as JSON to a plain HTTPS endpoint after each workflow run.

API notify (extensions/api_notify.py)

Posts the provisioning result as JSON to a REST API endpoint using Bearer token authentication.

Both extensions are auto-discovered at startup. They activate when their controlling env var is set (VENDING_WEBHOOK_URL or VENDING_API_NOTIFY_URL respectively). No code changes are required — set the env var and the extension registers itself.

ServiceNow check (extensions/servicenow_check.py)

Gate check that validates a ServiceNow ticket before any provisioning step runs. The check is read-only and runs even during dry-run.

ServiceNow feedback (extensions/servicenow_feedback.py)

Provisioning step that PATCHes the ServiceNow ticket with the outcome after STEP_NOTIFY. Feedback failures are non-fatal.

Retry strategy (retry/)

Controls how the service handles provisioning failures. Select a strategy via VENDING_RETRY_STRATEGY.

Soft dependency: The azure-storage-queue package is required when VENDING_RETRY_STRATEGY=queue. It is wrapped in a try/except import — the service starts normally without it, but the queue strategy will raise a RuntimeError at first dispatch if the package is missing. Install it with pip install azure-storage-queue.

Tag-based provisioning

Azure subscription tags are read at the start of the provisioning workflow. They override defaults derived from environment variables.

| Tag | Expected values | Effect | Fallback | |—–|—————-|——–|———| | itl-environment | Any string (e.g. production, staging, acceptance, customer-a) | Selects the target management group via VENDING_ENVIRONMENT_MG_MAPPING. Also determines policy enforcement mode (Default for production, DoNotEnforce for all others). | sandbox MG | | itl-aks | true, false | Marks the subscription for AKS/Flux base chart installation. | false | | itl-budget | Integer (e.g. 500) | Creates a monthly Azure Cost Management budget at the specified EUR amount with e-mail alerts at 80 % and 100 %. | No budget alert | | itl-owner | E-mail address | Contact address for budget alert notifications. Overrides VENDING_DEFAULT_ALERT_EMAIL. | VENDING_DEFAULT_ALERT_EMAIL || itl-snow-ticket | Ticket number (e.g. RITM0041872) | Validated by the ServiceNow gate check before provisioning starts. Required when servicenow_check extension is active. Updated with the provisioning outcome by the servicenow_feedback extension. | (gate skipped if absent and SNOW not configured) | Invalid tag values are silently ignored and the corresponding default is used, so provisioning always continues even when tags are malformed.

Configurable tag key names

The tag key names shown above are defaults. You can override them to match your own tagging conventions using the following environment variables:

For example, to use myorg-environment instead of itl-environment:

VENDING_TAG_ENVIRONMENT=myorg-environment
VENDING_TAG_AKS=myorg-aks
VENDING_TAG_BUDGET=cost-budget
VENDING_TAG_OWNER=cost-owner