Container Apps custom domain

Understand the concept

In plain English

Container Apps custom domain is the hostname you map to a container app so users reach app.contoso.com instead of the default azurecontainerapps.io address. The app needs ingress enabled, DNS has to prove ownership and route traffic, and the hostname must be associated with a TLS certificate. In production, this setting is more than branding. It is where DNS, certificates, Container Apps ingress, managed environment ownership, revisions, and customer cutover plans meet. A healthy container can still look offline when the domain, certificate, or DNS record is wrong.

Why it matters

Container Apps custom domain matters because users and partner systems depend on stable hostnames, not Azure-generated default names. During a launch, migration, or incident, the custom domain is often the difference between a working container and a service people cannot reach. Misconfigured DNS sends traffic to the wrong place. Missing verification blocks the binding. Expired or mismatched certificates create browser and client failures. Weak ownership records can create takeover risk when domains are reused. Treating the domain as operational configuration gives teams clearer release gates, rollback plans, support evidence, and certificate renewal ownership. It also keeps architecture diagrams honest about how customers actually enter the workload.

Technical context

Technically, a Container Apps custom domain is stored on the container app ingress configuration and validated with DNS ownership records. External apps usually use CNAME or A records plus TXT verification, while private environments may involve internal DNS and controlled resolution. The binding also needs a certificate, either a managed certificate or an uploaded certificate available to the managed environment. Operators inspect the app FQDN, custom hostname, certificate name, ingress mode, target port, revision routing, and environment scope together because a correct host binding still fails if DNS, TLS, or ingress points somewhere else.

Exam context

Compare with

Container Apps ingress App Service custom domain Front Door route Application Gateway listener

Where it is used

Where you see it

You see Container Apps custom domain in Container Apps ingress blades, DNS records, certificate bindings, and validation output when confirming hostname, verification record, certificate, ingress target, and traffic route for release, audit, or incident evidence.
You see Container Apps custom domain during troubleshooting when users reach default URLs instead of branded domains and operators must connect portal state, CLI output, logs, metrics, owners, and rollback notes.
You see Container Apps custom domain in architecture reviews when teams decide how public hostnames map to container app ingress, how evidence is gathered, and how it affects security, reliability, operations, cost, and performance.

Common situations

Bind a branded customer or partner hostname to Container Apps ingress instead of exposing the generated default FQDN.
Validate DNS ownership, hostname binding, certificate assignment, ingress mode, and target port before a production cutover.
Troubleshoot browser, client, or webhook failures caused by DNS drift, certificate mismatch, propagation delay, or stale bindings.
Document who owns DNS, certificate renewal, Container Apps ingress, rollback instructions, and support escalation for the hostname.
Create CLI and release checks that stop domain, certificate, and revision routing from drifting across environments.

Illustrative Azure scenarios

These examples show how the concept can affect design and operations. They are illustrative scenarios, not customer claims.

Scenario 01 Retail checkout hostname cutover without customer confusion Scenario, objectives, solution, measured impact, and takeaway.

Scenario

Contoso Market moved its checkout API from App Service to Azure Container Apps, but customers and mobile apps still called checkout.contoso.com. The platform team needed a controlled cutover that proved DNS ownership, bound the hostname, attached a valid certificate, and preserved rollback to the old endpoint while the new container app revisions warmed up.

Goals

Keep the customer-facing checkout hostname unchanged during migration.
Validate DNS ownership and TLS before routing production traffic.
Preserve a fast rollback path to the previous checkout endpoint.
Capture evidence for support, security, and release approval.

Approach using Container Apps custom domain

The team enabled external ingress on the checkout container app, recorded the default app FQDN and verification ID, and created DNS records in the corporate zone before the change window. They uploaded the approved certificate to the Container Apps environment, bound checkout.contoso.com to the app, and verified the binding with CLI output, portal screenshots, and synthetic tests from the public hostname. Traffic was shifted only after the DNS record, certificate chain, target port, and revision split were confirmed. The rollback notes kept the old endpoint and DNS target available until post-release monitoring showed clean transactions for two hours.

Potential outcomes

Checkout stayed on the same branded hostname during the move.
Synthetic tests caught a staging DNS mistake before production traffic moved.
Support had one evidence packet covering DNS, certificate, ingress, and rollback state.
The old endpoint was retired after monitoring confirmed stable production traffic.

What to learn

A Container Apps custom domain should be treated as release-critical ingress configuration. The hostname, DNS record, certificate, revision routing, and rollback target all need evidence before a customer-facing cutover.

Scenario 02 Certificate ownership cleanup for a regulated portal Scenario, objectives, solution, measured impact, and takeaway.

Scenario

Northwind Health hosted a patient notification portal in Azure Container Apps with portal.northwindhealth.example as the public entry point. The application team owned the container image, but a central platform team owned DNS and certificates. Audit reviewers could not tell who renewed the certificate, who approved the hostname binding, or whether the default FQDN was still being used by partner scripts.

Goals

Create clear ownership for DNS, certificate renewal, and hostname binding.
Prove that the custom domain used the approved TLS certificate.
Remove partner dependence on the default Container Apps FQDN.
Make certificate expiry visible before audit and renewal deadlines.

Approach using Container Apps custom domain

The platform team documented the domain binding in the production runbook with the resource group, container app name, managed environment, certificate name, expiration date, and DNS zone owner. They replaced partner references to the default app FQDN with the approved custom hostname and added a release check that fails when hostname evidence is missing. CLI checks listed the custom domain, certificate binding, and recent activity log updates. The security team kept certificate renewal reminders in the same change calendar as other public endpoints, so the Container Apps domain was no longer an exception hidden inside application deployment notes.

Potential outcomes

The audit packet named a single owner for DNS and certificate renewal.
Partner scripts stopped using the generated Azure hostname.
Renewal reminders appeared before the certificate entered the high-risk window.
The release checklist blocked future deployments without hostname evidence.

What to learn

Custom domains on Container Apps cross team boundaries. Naming, certificate, DNS, app ingress, and partner usage must be documented together or each team will assume another team owns the risk.

Scenario 03 Partner webhook domain stabilized after DNS drift Scenario, objectives, solution, measured impact, and takeaway.

Scenario

Fabrikam Logistics received partner events at webhook.fabrikam.example, which pointed to a Container Apps workload that scaled on HTTP requests. After a rushed test environment cleanup, the production CNAME was changed to the wrong container app FQDN. The container app was healthy, but partners saw intermittent failures, and the incident bridge initially chased image, replica, and scale-rule symptoms instead of hostname routing.

Goals

Identify whether failures came from the container app or the hostname path.
Restore the production DNS target without changing application code.
Add checks that detect hostname drift before partner traffic is affected.
Record the relationship between custom domain, environment, app, and revision.

Approach using Container Apps custom domain

Operators compared the custom domain binding on the production container app with DNS records, certificate details, ingress settings, and revision traffic. The evidence showed that the hostname binding was valid, but the CNAME pointed to a test app FQDN. DNS was restored to the production target, and synthetic probes were switched from the generated FQDN to webhook.fabrikam.example so future tests used the partner path. The team added a weekly CLI inventory of hostnames and certificate bindings, plus a change approval step requiring DNS owner confirmation before any environment cleanup.

Potential outcomes

The incident was resolved by correcting DNS instead of redeploying containers.
Synthetic probes began testing the real partner hostname.
Cleanup requests now verify production domain dependencies first.
The runbook clearly separates app health from custom-domain routing health.

What to learn

When Container Apps is healthy but clients fail, inspect the custom domain path before redeploying. DNS drift, certificate mismatch, or hostname binding mistakes can imitate application outages.

Azure CLI

Use Azure CLI for Container Apps custom domain when you need repeatable hostname, ingress, DNS, and certificate evidence instead of relying on one portal view during release or incident work.

Useful for

List hostnames and certificate bindings for repeatable release evidence.
Compare app ingress settings with DNS records during a domain cutover.
Capture command output for incidents where users can reach one hostname but not another.

Before you run a command

Confirm the active subscription and resource group before inspecting the app.
Have DNS owner approval and certificate details available before changing bindings.
Use read-only commands first when troubleshooting a production hostname incident.

What the output tells you

Hostname output shows which custom domains are attached to the container app.
Ingress output shows whether the app exposes the expected target port and external mode.
Certificate output helps confirm the certificate name and expiration context for the binding.

Mapped commands

Inspect Container Apps custom domain state

az containerapp show --name <container-app> --resource-group <resource-group>

az containerappdiscoverContainers

Show the container app, including ingress and generated FQDN details.

az containerapp hostname list --name <container-app> --resource-group <resource-group>

az containerapp hostnamediscoverContainers

List custom hostnames bound to the container app.

az containerapp env certificate list --name <environment-name> --resource-group <resource-group>

az containerapp env certificatediscoverContainers

List certificates available in the Container Apps environment.

Change custom domain bindings deliberately

az containerapp hostname add --hostname <hostname> --name <container-app> --resource-group <resource-group>

az containerapp hostnameconfigureContainers

Add a custom hostname binding to a container app after ownership is ready.

az containerapp ssl upload --hostname <hostname> --name <container-app> --resource-group <resource-group> --certificate-file <certificate-file> --certificate-password <password>

az containerapp ssloperateContainers

Upload and bind a certificate for a hostname when using an uploaded certificate workflow.

Architecture context

Security: Security for Container Apps custom domain starts with proving that the team controls the hostname and certificate used for the public or private endpoint. Operators should confirm DNS ownership records, certificate source, expiration date, private key handling, and RBAC permissions on the container app and managed environment. A custom domain can expose an app more visibly than the default hostname, so ingress mode, allowed origins, authentication, API gateway placement, and network isolation still matter. Certificate upload workflows should protect secrets, and managed certificates should have a clear renewal owner. During cleanup, remove stale domain bindings and DNS records so abandoned names cannot point at unexpected services.
Cost: Cost for Container Apps custom domain is usually indirect, but it still deserves review because domain choices can change surrounding architecture. A branded hostname may require certificates, DNS zones, Front Door, Application Gateway, API Management, monitoring, or additional environments for blue green release. Failed bindings and long cutovers can leave old resources running while the new app also serves traffic. Certificate management may add operational overhead, especially when teams use uploaded certificates across many apps. Cost reviews should connect the hostname to ingress exposure, revision traffic, logging volume, edge services, and idle environments so a simple domain request does not hide duplicated capacity.
Reliability: Reliability for Container Apps custom domain depends on DNS, TLS, ingress, and revision routing staying aligned over time. A revision can be healthy while users still fail because the CNAME points to an old target, the A record references the wrong address, the certificate is expired, or propagation is incomplete. Release runbooks should check hostname binding status, DNS records, certificate health, ingress target port, and traffic split before cutover. Rollback plans should include DNS time to live decisions and whether the previous endpoint remains valid. Monitoring should distinguish app failure from edge, certificate, or name resolution failure so incidents are routed quickly.
Performance: Performance for Container Apps custom domain is mostly about the request path that the hostname creates. DNS resolution, TLS negotiation, edge services, ingress configuration, target port, revision scale, cold starts, and backend dependencies can all affect user latency. A custom domain itself does not make the container faster, but it is often the name clients use for synthetic tests, load tests, and production monitoring. Operators should measure from the custom hostname, not only the default FQDN, because certificate errors, redirects, proxy hops, and DNS behavior appear only on the real path. Keep DNS changes deliberate and validate latency after cutover.
Operations: Operationally, Container Apps custom domain belongs in deployment checklists, certificate inventories, DNS change tickets, incident runbooks, and environment ownership records. Teams should know who can change DNS, who owns the certificate, which resource group contains the container app, and whether the hostname is used by customers, partners, or internal systems. CLI and portal evidence should show current hostnames, verification IDs, ingress settings, certificate bindings, and recent activity log changes. Before a migration, capture the old and new targets, expected DNS records, rollback instructions, and validation commands. After release, confirm traffic, certificate expiry monitoring, support documentation, owner reminders, and escalation contacts.

Common mistakes

Testing only the generated FQDN and assuming the branded hostname uses the same request path.
Changing DNS before certificate binding, ingress target, and rollback instructions are ready.
Leaving stale DNS records or custom domain bindings after an environment migration or cleanup.