Edit

Share via

Custom ___domain names and free managed certificates in Azure Container Apps

  • Article

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 can't 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 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.

    • 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.

  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. Set the following environment variables. Replace the <PLACEHOLDERS> with your values.

    RESOURCE_GROUP = "<RESOURCE_GROUP>"
CONTAINER_APP = "<CONTAINER_APP>"
ENVIRONMENT = "<ENVIRONMENT>"
TARGET_PORT = "<TARGET_PORT>"
DOMAIN_NAME = "<DOMAIN_NAME>"
CERTIFICATE_LOWERCASE_NAME = "<CERTIFICATE_LOWERCASE_NAME>"
CERTIFICATE_LOCAL_PATH = "<CERTIFICATE_LOCAL_PATH>"
CERTIFICATE_PASSWORD = "<CERTIFICATE_PASSWORD>"
    • Replace <CERTIFICATE_LOCAL_PATH> with the local path of your certificate file.
    • Replace <CERTIFICATE_LOWERCASE_NAME> with a lowercase certificate name that is unique within the environment.
    • Replace <TARGET_PORT> with the port that your container app is listening on.

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

    az containerapp ingress show \
    -n $CONTAINER_APP \
    -g $RESOURCE_GROUP

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

    az containerapp ingress enable \
    -n $CONTAINER_APP \
    -g $RESOURCE_GROUP \
    --type external \
    --target-port $TARGET_PORT \
    --transport auto

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

    az containerapp env show \
    -n $ENVIRONMENT \
    -g $RESOURCE_GROUP \
    -o tsv \
    --query "properties.staticIp"

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

    az containerapp show \
    -n $CONTAINER_APP \
    -g $RESOURCE_GROUP \
    -o tsv \
    --query "properties.configuration.ingress.fqdn"

  7. Get the ___domain verification code.

    az containerapp show \
    -n $CONTAINER_APP \
    -g $RESOURCE_GROUP \
    -o tsv \
    --query "properties.customDomainVerificationId"

  8. 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're using custom domains with the private endpoint (preview) feature:

    • 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.

  9. Add the ___domain to your container app.

    az containerapp hostname add \
    --hostname $DOMAIN_NAME \
    -g $RESOURCE_GROUP \
    -n $CONTAINER_APP

  10. Configure the managed certificate and bind the ___domain to your container app.

    az containerapp hostname bind \
    --hostname $DOMAIN_NAME \
    -g $RESOURCE_GROUP \
    -n $CONTAINER_APP \
    --environment $ENVIRONMENT \
    --validation-method <VALIDATION_METHOD>

    • 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.

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

Next steps

Authentication in Azure Container Apps