Automating Azure Container Apps custom domains with OctoDNS + aspire do

[zortracks]

Automating Azure Container Apps custom domains with OctoDNS + aspire do

---

TL;DR

I built a NuGet hosting package that wires custom domains for Azure Container Apps into the Aspire deploy pipeline. It handles DNS through OctoDNS (config generated in-process, sync in Docker), then managed certificates (inventory → create → bind) — all as named aspire do steps that sit around aspire deploy.

📦 Neox.Aspire.Hosting.Azure.CustomDomains
📂 Source: neox-technology/aspire

---

The problem I kept hitting

ConfigureCustomDomain on ACA is a great start, but getting a real hostname live still meant a lot of manual glue for me:

1. Create the right DNS records (A + asuid TXT)
2. Wait for DNS / DigiCert HTTP validation
3. Create the managed certificate
4. Bind it to the Container App
5. Redeploy so Bicep sees the certificate name

I wanted that whole flow to feel like the rest of Aspire — discoverable with aspire do --list-steps, runnable interactively or in CI, and required by aspire deploy when domains are in the model.

---

What I built

Calling WithAzureCustomDomainOps on a compute resource registers a DomainOps pipeline. Same DNS zone across multiple apps shares one zone plan/provision pair. Multiple hostnames on one app get distinct steps with serialized ARM PATCHes.

DNS providers are source-generated from the OctoDNS catalogue (Cloudflare, OVH, Route53, Azure DNS, …), so the fluent API stays aligned with official octodns/* images.

---

Pipeline steps (in order)

Here’s the full chain. You can list it anytime with aspire do --list-steps. Zone / hostname slugs replace . with - (e.g. example.com → example-com).

1. Prerequisites

Step	Role
prereq-domain	Shared gate: ACA environment must already be provisioned (provision-{acaEnv})
prereq-domain-{provider}	docker pull for that provider’s OctoDNS image (e.g. octodns/cloudflare)

2. DNS plan & provision (per provider / per zone)

Step	Role
plan-domain-{provider}	Writes octodns.yaml in-process (auth only as env/VAR refs — never raw secrets)
plan-domain-{zone}	Discovers ACA env verification ID / static IP via ARM, upserts zone YAML (A + asuid TXT). Depends on provider plan and the Container Apps for that zone being provisioned
provision-domain-{zone}	Runs OctoDNS sync in Docker (dry-run first). Upsert-only: if the plan would delete records, the step fails

Apps that share a zone share these zone steps — I didn’t want every hostname to re-sync the same zone.

3. Hostname on the Container App (no cert yet)

Step	Role
plan-{resource}-domain-{dom}	Validates the domain model for that binding
provision-{resource}-domain-{dom}	Adds the custom hostname via ARM (certificate not required yet). Sibling hostnames on the same app are ordered so ARM PATCHes don’t race
provision-{env}-domains	Env-level gate: all hostname provisions for that ACA env succeeded

4. Managed certificates

Step	Role
plan-{env}-certificates	Loads managed-cert inventory from the ACA environment
provision-{env}-certificates	Creates missing managed certs in parallel (DigiCert HTTP validation). Depends on hostnames already being present

5. Bind & deploy gate

Step	Role
deploy-{resource}-domain-{dom}	Binds the managed certificate to the hostname
deploy-domains	Final gate over all bind steps — RequiredBy Aspire’s deploy, so a normal aspire deploy waits for domains to finish

Bootstrap vs steady-state is intentional:

1. aspire deploy with an empty certificate parameter (Bicep can deploy without the cert name yet)
2. DomainOps runs DNS → hostname → cert create → bind
3. Redeploy with Parameters__{resource}-certificate (or your explicit cert param) set

In CI I pass Parameters__* / Azure__* and use --non-interactive. Locally, unresolved parameters open Aspire’s Set parameter modal.

---

AppHost sketch

var dns = builder.AddDomainOpsProvider("dns")
    .Cloudflare(); // or .Ovh(), .Route53(), …

builder.AddAzureContainerAppEnvironment("env");

#pragma warning disable ASPIREACADOMAINS001
builder.AddProject<Projects.Api>("api")
    .WithExternalHttpEndpoints()
    .PublishAsAzureContainerApp((infrastructure, app) =>
    {
        var (customDomain, certificateName) =
            AzureCustomDomainOpsExtensions.EnsureAzureCustomDomainParameters(
                builder, "api", "www.example.com");
        app.ConfigureCustomDomain(customDomain, certificateName);
    })
    .WithAzureCustomDomainOps("www.example.com", dns, options =>
    {
        options.DnsZoneName = "example.com";
        options.OctoDnsConfigPath = "dns/octodns.yaml";
        options.OctoDnsZoneDirectory = "dns/zones";
    });
#pragma warning restore ASPIREACADOMAINS001

aspire do --list-steps
aspire deploy
# then DomainOps provision/bind steps as listed above
aspire deploy  # with certificate parameter populated

ARM goes through ITokenCredentialProvider — DomainOps does not shell out to az. Docker is only needed for OctoDNS sync.

---

Design choices I care about

• Complements experimental ConfigureCustomDomain — I don’t replace it; consumers still own that call
• Upsert-only DNS — refuse destructive OctoDNS plans
• DigiCert-friendly: plan A to the ACA env static IP + asuid TXT; don’t orange-cloud proxy during issuance/renewal
• Docker for OctoDNS so you don’t need a Python toolchain on the agent
• Named pipeline steps instead of dashboard-only commands, so CI and interactive use the same graph

---

Links

• Package: https://www.nuget.org/packages/Neox.Aspire.Hosting.Azure.CustomDomains
• README: https://github.com/neox-technology/aspire/blob/main/src/hosting/Neox.Aspire.Hosting.Azure.CustomDomains/README.md
• Repo: https://github.com/neox-technology/aspire

I’d love feedback from anyone who’s already wrestled with ACA custom domains — especially on the bootstrap/redeploy loop, multi-hostname apps, and whether something like this belongs closer to upstream hosting.