Neox.Aspire.Hosting.Azure.CustomDomains 1.0.0-preview.26403.7

Neox.Aspire.Hosting.Azure.CustomDomains

Aspire hosting helpers for Azure Container Apps custom domains: DNS via OctoDNS (config generated in-process; sync via Docker), and managed certificates (inventory → create → bind).

Install

dotnet add package Neox.Aspire.Hosting.Azure.CustomDomains

<PackageReference Include="Neox.Aspire.Hosting.Azure.CustomDomains" Version="1.0.0-preview.*" />

Naming

Prerequisites

• Aspire CLI
• Azure auth for deploy / DomainOps (ITokenCredentialProvider; local: az login or Azure__CredentialSource; CI: OIDC / SP). The Azure CLI binary is not required for DomainOps ARM calls.
• Docker to pull the provider image (e.g. octodns/cloudflare, octodns/ovh)

Credentials are never written into generated octodns.yaml (only env/VAR refs).

DigiCert: DomainOps plans an A record to the ACA environment static IP plus asuid TXT, and creates managed certs with HTTP validation. Do not put an orange-cloud proxy in front of the hostname during issuance/renewal.

Usage

Shorthand (dash parameter names)

var dns = builder.AddDomainOpsProvider("dns")
    .Cloudflare(); // or .Ovh(), .Route53(), … — auth from Parameters__dns-* when options are omitted

builder.AddAzureContainerAppEnvironment("env");

// Optional: same params for consumer-owned ConfigureCustomDomain
var (customDomain, certificateName) = AzureCustomDomainOpsExtensions.EnsureAzureCustomDomainParameters(
    builder, "api", "www.example.com");
// → Parameters__api-domain / Parameters__api-certificate

#pragma warning disable ASPIREACADOMAINS001
builder.AddProject<Projects.Api>("api")
    .WithExternalHttpEndpoints()
    .PublishAsAzureContainerApp((infrastructure, app) =>
    {
        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

Additional hostnames on the same resource need distinct domain parameter names (string overload is primary-only).

Explicit parameters

var customDomain = builder.AddParameter("customDomain");
var certificateName = builder.AddParameter("certificateName");

var dns = builder.AddDomainOpsProvider("dns")
    .Cloudflare();

builder.AddAzureContainerAppEnvironment("env");

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

Same provider can serve multiple bindings. Apps in the same DNS zone share one plan-domain-{zone} / provision-domain-{zone} pair. List steps with aspire do --list-steps.

Fluent provider APIs include .Cloudflare(), .Ovh(), .Route53(), .Azure(), .Digitalocean(), and other OctoDNS-backed providers. Auth is taken from Parameters__{providerName}-* when options are omitted.

Pipeline steps

Zone / hostname slug: . → - (e.g. example.com → example-com).

DNS DomainOps is upsert-only. Unresolved parameters open Aspire’s Set parameter modal for interactive aspire do; CI must supply Parameters__*.

CI flows

Pass Parameters__* and Azure__* non-interactively. Set the certificate parameter yourself for the Bicep redeploy (e.g. Parameters__api-certificate or Parameters__certificateName).

Bootstrap (empty cert): aspire deploy → run DomainOps provision/bind steps (see aspire do --list-steps) → aspire deploy with certificate name set.

Steady-state: aspire deploy --non-interactive with all parameters populated.

Notes

• This is an Aspire hosting package: wire providers and bindings on IDistributedApplicationBuilder, then run DomainOps via aspire do / aspire deploy.
• Credentials must stay in Aspire parameters / environment variables — they are never written into generated octodns.yaml.
• License: MIT.