Custom domain names and free managed certificates in Azure Container Apps

Azure Container Apps allows you to bind one or more custom domains to a container app. You can automatically configure a free managed certificate for your custom domain.

If you want to set up a custom domain using your own certificate, see Custom domain names and certificates in Azure Container Apps.

Note

If you configure a custom environment DNS suffix, you cannot add a custom domain that contains this suffix to your Container App.

Free certificate requirements

Azure Container Apps provides a free managed certificate for your custom domain. Without any action required from you, this TLS/SSL server certificate is automatically renewed as long as your app continues to meet the requirements for managed certificates.

The requirements are:

• Enable HTTP ingress and ensure your container app is publicly accessible.

• Must have an A record for apex domains that points to your Container Apps environment's IP address.

• Establish a CNAME record for subdomains that maps directly to the container app's automatically generated domain name. Mapping to an intermediate CNAME value blocks certificate issuance and renewal. Examples of CNAME values are traffic managers, Cloudflare, and similar services.

Note

To ensure the certificate issuance and subsequent renewals proceed successfully, all requirements must be met at all times when the managed certificate is assigned.

Add a custom domain and managed certificate

1. Navigate to your container app in the Azure portal

2. Verify that your app has HTTP ingress enabled by selecting Ingress in the Settings section. If ingress isn't enabled, enable it with these steps:

   1. Set HTTP Ingress to Enabled.
   2. Select the desired Ingress traffic setting.
   3. Enter the Target port.
   4. Select Save.

3. Under the Settings section, select Custom domains.

4. Select Add custom domain.

5. In the Add custom domain and certificate window, in TLS/SSL certificate, select Managed certificate.

6. In domain, enter the domain you want to add.

7. Select the Hostname record type based on the type of your domain.

   Domain type	Record type	Notes
   Apex domain	A record	An apex domain is a domain at the root level of your domain. For example, if your DNS zone is contoso.com, then contoso.com is the apex domain.
   Subdomain	CNAME	A subdomain is a domain that is part of another domain. For example, if your DNS zone is contoso.com, then www.contoso.com is an example of a subdomain that can be configured in the zone.

8. Using the DNS provider that is hosting your domain, create DNS records based on the Hostname record type you selected using the values shown in the Domain validation section. The records point the domain to your container app and verify that you're the owner. The setup depends on whether you are using custom domains with the private endpoint (preview) feature:

   General

   • If you selected A record, create the following DNS records:

     Record type	Host	Value
     A	@	The IP address of your Container Apps environment.
     TXT	asuid	The domain verification code.

   • If you selected CNAME, create the following DNS records:

     Record type	Host	Value
     CNAME	The subdomain (for example, www)	The generated domain of your container app.
     TXT	asuid. followed by the subdomain (for example, asuid.www)	The domain verification code.

   Private endpoint

   • If you selected A record, you need to have a private DNS zone which has the same DNS zone name as your public DNS. Create the following DNS records on your private DNS zone:

     Record type	Host	Value
     A	@	The Private IP of your private endpoint on your container apps environment.
     TXT	asuid	The domain verification code.

   • If you selected CNAME, create the following DNS records:

     Record type	Host	Value
     CNAME	The subdomain (for example, www)	The generated domain of your container app.
     TXT	asuid. followed by the subdomain (for example, asuid.www)	The domain verification code.

9. Select Validate.

10. Once validation succeeds, select Add.

    It might take several minutes to issue the certificate and add the domain to your container app.

11. Once the operation is complete, you see your domain name in the list of custom domains with a status of Secured. Navigate to your domain to verify that it's accessible.

Container Apps supports apex domains and subdomains. Each domain type requires a different DNS record type and validation method.

Domain type	Record type	Validation method	Notes
Apex domain	A record	HTTP	An apex domain is a domain at the root level of your domain. For example, if your DNS zone is contoso.com, then contoso.com is the apex domain.
Subdomain	CNAME	CNAME	A subdomain is a domain that is part of another domain. For example, if your DNS zone is contoso.com, then www.contoso.com is an example of a subdomain that can be configured in the zone.

1. Log in to Azure with the Azure CLI.

   az login
   

2. Next, install the Azure Container Apps extension for the CLI.

   az extension add --name containerapp --upgrade
   

3. Verify that your container app has HTTP ingress enabled.

   az containerapp ingress show -n <CONTAINER_APP_NAME> -g <RESOURCE_GROUP_NAME>
   

   If ingress isn't enabled, enable it with these steps:

   az containerapp ingress enable -n <CONTAINER_APP_NAME> -g <RESOURCE_GROUP_NAME> \
           --type external --target-port <TARGET_PORT> --transport auto
   

   Replace <CONTAINER_APP_NAME> with the name of your container app, <RESOURCE_GROUP_NAME> with the name of the resource group that contains your container app, and <TARGET_PORT> with the port that your container app is listening on.

4. If you're configuring an apex domain, get the IP address of your Container Apps environment.

   az containerapp env show -n <ENVIRONMENT_NAME> -g <RESOURCE_GROUP_NAME> -o tsv --query "properties.staticIp"
   

   Replace <ENVIRONMENT_NAME> with the name of your environment, and <RESOURCE_GROUP_NAME> with the name of the resource group that contains your environment.

5. If you're configuring a subdomain, get the automatically generated domain of your container app.

   az containerapp show -n <CONTAINER_APP_NAME> -g <RESOURCE_GROUP_NAME> -o tsv --query "properties.configuration.ingress.fqdn"
   

   Replace <CONTAINER_APP_NAME> with the name of your container app, and <RESOURCE_GROUP_NAME> with the name of the resource group that contains your container app.

6. Get the domain verification code.

   az containerapp show -n <CONTAINER_APP_NAME> -g <RESOURCE_GROUP_NAME> -o tsv --query "properties.customDomainVerificationId"
   

   Replace <CONTAINER_APP_NAME> with the name of your container app, and <RESOURCE_GROUP_NAME> with the name of the resource group that contains your container app.

7. Using the DNS provider that is hosting your domain, create DNS records based on the record type you selected using the values shown in the Domain validation section. The records point the domain to your container app and verify that you own it. The setup depends on whether you are using custom domains with the private endpoint (preview) feature:

   General

   • If you selected A record, create the following DNS records:

     Record type	Host	Value
     A	@	The IP address of your Container Apps environment.
     TXT	asuid	The domain verification code.

   • If you selected CNAME, create the following DNS records:

     Record type	Host	Value
     CNAME	The subdomain (for example, www)	The generated domain of your container app.
     TXT	asuid. followed by the subdomain (for example, asuid.www)	The domain verification code.

   Private endpoint

   When using a private endpoint for your incoming traffic, you need to create a private DNS zone.

   • If you selected A record, create the following DNS records:

     Record type	Host	Value
     A	@	The Private IP of your private endpoint on your container apps environment.
     TXT	asuid	The domain verification code.

   • If you selected CNAME, create the following DNS records:

     Record type	Host	Value
     CNAME	The subdomain (for example, www)	The generated domain of your container app.
     TXT	asuid. followed by the subdomain (for example, asuid.www)	The domain verification code.

8. Add the domain to your container app.

   az containerapp hostname add --hostname <DOMAIN_NAME> -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME>
   

   Replace <DOMAIN_NAME> with the domain name you want to add, <RESOURCE_GROUP_NAME> with the name of the resource group that contains your container app, and <CONTAINER_APP_NAME> with the name of your container app.

9. Configure the managed certificate and bind the domain to your container app.

   az containerapp hostname bind --hostname <DOMAIN_NAME> -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --environment <ENVIRONMENT_NAME> --validation-method <VALIDATION_METHOD>
   

   Replace <DOMAIN_NAME> with the domain name you want to add, <RESOURCE_GROUP_NAME> with the name of the resource group that contains your container app, <CONTAINER_APP_NAME> with the name of your container app, and <ENVIRONMENT_NAME> with the name of your environment.

   • If you're configuring an A record, replace <VALIDATION_METHOD> with HTTP.
   • If you're configuring a CNAME, replace <VALIDATION_METHOD> with CNAME.

   It might take several minutes to issue the certificate and add the domain to your container app.

10. Once the operation is complete, navigate to your domain to verify that it's accessible.

Next steps

Authentication in Azure Container Apps