Documentation by ClonePartner

Start typing to search.

Deployment

Azure

View Markdown

Deploy an isolated Envoy environment with Azure Container Apps, Azure SQL, Blob Storage, Key Vault, and ACR via Terraform or deploy-azure.sh.

Azure

The Azure topology provisions one isolated Envoy environment inside a resource group. It uses the same control-plane and executor roles as remote Docker, with managed Azure services for ingress, state, files, images, and secrets.

flowchart TD user["Browser"] --> cp["Control plane<br/>external HTTPS ingress"] cp <--> ex["Executor<br/>internal ingress"] cp --> sql["Azure SQL"] cp --> kv["Azure Key Vault"] ex --> blob["Azure Blob Storage"] acr["Azure Container Registry"] --> cp acr --> ex
Azure topology

Resources

The Terraform module in terraform/azure creates:

  • an Azure resource group;
  • a Container Apps environment with external control-plane and internal executor Container Apps;
  • Azure Container Registry, or access to a configured source registry (source_acr_server, source_acr_username, source_acr_password);
  • an Azure Storage account with a Litestream container and a data container;
  • an Azure SQL logical server and database;
  • Azure Key Vault when selected as the secret provider (key_vault_name, secrets_default, akv_name_prefix).

Registry, storage account, SQL server, and vault names must be globally unique.

Requirements

  • Contributor access to the target Azure subscription.
  • Terraform for the module workflow, or Azure CLI (az) plus Bun for the shell workflow.
  • An Envoy image available to the selected ACR path, or build access.
  • Three deployment secrets: envoy_encryption_key, envoy_executor_key, and sql_admin_password (script equivalents: ENVOY_ENCRYPTION_KEY, ENVOY_EXECUTOR_KEY, SQL_ADMIN_PASSWORD).
  • Optional OAuth credentials (oauth_microsoft_client_id, oauth_microsoft_client_secret, oauth_microsoft_tenant_id) and an Anthropic API key for the AI assistant.

Terraform workflow

cd terraform/azure
cp terraform.tfvars.example terraform.tfvars

Fill at least:

envoy_encryption_key = "<high-entropy-key>"
envoy_executor_key   = "<different-high-entropy-key>"
sql_admin_password   = "<strong-password>"
image_tag            = "<tag-that-exists-in-acr>"

Then review and apply:

terraform init
terraform plan
terraform apply

Outputs include the control-plane HTTPS URL, executor internal FQDN, image reference, SQL FQDN, storage account, and Key Vault URL.

Shell deployment workflow

scripts/deploy-azure.sh reads .env.deploy when present and deploys with the Azure CLI:

./scripts/deploy-azure.sh
FORCE_DEPLOY=true ./scripts/deploy-azure.sh
DEPLOY_SCOPE=cp ./scripts/deploy-azure.sh
DEPLOY_SCOPE=ex ./scripts/deploy-azure.sh

Like the remote Docker script, it diffs against a git tag (azure-deployed) to decide what to rebuild and redeploy. The first deploy requires ENVOY_ENCRYPTION_KEY, ENVOY_EXECUTOR_KEY, and SQL_ADMIN_PASSWORD; later runs reuse deployed secrets when they are not supplied again. Defaults include ENVOY_STORE_TYPE=mssql, ENVOY_SECRETS_DEFAULT=azure_key_vault, ENVOY_AKV_NAME_PREFIX=envoy-, control plane on port 3000, and executor on 9090 with EX_MAX_CONCURRENT=10.

State and logs

The supplied Azure configuration uses Microsoft SQL Server for application state (store.type: mssql) with encrypted transport and a configurable pool (ENVOY_MSSQL_POOL_SIZE, default 20). Azure SQL is also available as a task connector, but application state and business data are separate concerns — do not let Tasks modify Envoy's own state tables.

Key Vault

With the Key Vault secrets backend configured in envoy-server.yaml:

secrets:
  default: azure_key_vault
  azure_key_vault:
    vault_url: https://my-vault.vault.azure.net/
    name_prefix: envoy-

connector configurations and TOTP secrets are stored in the vault; the database keeps only provider and handle metadata. vault_url is required — boot fails with secrets.azure_key_vault.vault_url is required without it. name_prefix prefixes the secret names Envoy creates, which lets one vault partition several environments, though a dedicated vault per environment is simpler to reason about.

The control plane needs Key Vault data-plane permission to list, read, create, update, and delete the secrets Envoy owns.

OAuth redirect URIs

Register the final control-plane URL with the identity provider:

https://<control-plane-fqdn>/api/auth/oauth/microsoft/callback
https://<control-plane-fqdn>/api/auth/oauth/google/callback

Leave a provider's client ID empty to keep it disabled. See OAuth redirect URIs.

Post-deploy checks

  1. Open the Terraform control_plane_url and complete the first administrator setup.
  2. Verify that the executor registers on the Executors page.
  3. Create a Connector using a vault reference and test it.
  4. Run a bounded Task and confirm logs and metrics reach Azure SQL.
  5. Confirm Azure SQL backup retention and Key Vault recovery settings meet your policy.