Edit

Share via

Custom domain names and bring-your-own certificates in Azure Container Apps

Azure Container Apps allows you to bind one or more custom domains to a container app.

  • Every domain name must be associated with a TLS/SSL certificate. You can upload your own certificate or use a free managed certificate.
  • Certificates are applied to the container app environment and are bound to individual container apps. You must have role-based access to the environment to add certificates.
  • SNI (Server Name Identification) domain certificates are required.
  • Ingress must be enabled for the container app.

Note

If you configure a custom environment DNS (Domain Name System) suffix, you can't add a custom domain that contains this suffix to your container app.

Add a custom domain and certificate

Important

If you're using a new certificate, you must have an existing SNI domain certificate file available to upload to Azure.

  1. Go to your container app in the Azure portal.

  2. Verify that your app has ingress enabled by selecting Ingress in the Networking section in the left pane. If ingress isn't enabled, enable it by completing these steps:

    1. Set HTTP Ingress to Enabled.
    2. Select the Ingress traffic setting that you want.
    3. Set the Ingress type to HTTP.
    4. Enter the Target port.
    5. Select Save.

  3. In the Networking section, select Custom domains.

  4. Select Add custom domain.

  5. In the Add custom domain and certificate pane, under TLS/SSL certificate, select Bring your own certificate.

  6. In Domain box, enter the domain that you want to add.

  7. Select Add a certificate.

  8. In the Add certificate pane, in the Source box, select Upload certificate (.pfx) and browse for the certificate file that you want to upload.

  9. Select Validate.

  10. After validation succeeds, select Add.

  11. In the Add custom domain and certificate pane, in Certificate, select the certificate that you just added.

  12. 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's 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.

  13. Using the DNS provider that hosts your domain, create DNS records based on the Hostname record type you selected by 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 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.

  14. Select Validate.

  15. After validation succeeds, select Add.

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

Note

For container apps in internal Container Apps environments, extra configuration is required for using custom domains with VNET-scope ingress.

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's 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. Sign in to Azure by using the Azure CLI:

    az login

  2. 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's 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:

    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 hosts your domain, create DNS records based on the record type you selected by 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 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. Upload the certificate to your environment:

    az containerapp env certificate upload \
    -g $RESOURCE_GROUP \
    --name $ENVIRONMENT \
    --certificate-file $CERTIFICATE_LOCAL_PATH \
    --password $CERTIFICATE_PASSWORD \
    --certificate-name $CERTIFICATE_LOWERCASE_NAME

  10. Bind the certificate and domain to your container app:

    az containerapp hostname bind \
    --hostname $DOMAIN_NAME \
    -g $RESOURCE_GROUP \
    -n $CONTAINER_APP \
    --environment $ENVIRONMENT \
    --certificate $CERTIFICATE_LOWERCASE_NAME \
    --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. After the operation is complete, go to your domain to verify that it's accessible.

Managing certificates

You can manage certificates via the Container Apps environment or via an individual container app.

Environment

The Certificates pane of the Container Apps environment shows a table that contains all certificates associated with the environment. Go to the environment, and then select Certificates under Settings.

You can manage your certificates by taking the following actions:

Action Description
Add Select Add certificate to add a new certificate.
Delete Select the trash can icon to remove a certificate.
Renew The Health status field of the table indicates that a certificate is expiring soon within 60 days of the expiration date. To renew a certificate, select the Renew certificate link to upload a new certificate.

Container app

The Custom domains pane of the container app shows a list of custom domains that are associated with the container app. In the left pane, under Networking, select Custom domains.

You can manage your certificates for an individual domain name by selecting the ellipsis (...) button, which opens the certificate binding window. From the following window, you can select a certificate to bind to the selected domain name.

Next step

Authentication in Azure Container Apps

  • Last updated on