Skip to content

Commit a7742ae

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #293039 from craigshoemaker/aca/jason/cli-instructions
[Container Apps] Add CLI instructions for custom domain certificates
2 parents b2a6582 + d6652a9 commit a7742ae

File tree

2 files changed

+229
-33
lines changed

2 files changed

+229
-33
lines changed

‎articles/container-apps/custom-domains-certificates.md

Lines changed: 169 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ author: craigshoemaker
66
ms.service: azure-container-apps
77
ms.custom: build-2023, ignite-2024
88
ms.topic: how-to
9-
ms.date: 05/28/2024
9+
ms.date: 1/14/2025
1010
ms.author: cshoe
11+
zone_pivot_groups: azure-cli-or-portal
1112
---
1213

1314
# Custom domain names and bring your own certificates in Azure Container Apps
@@ -20,12 +21,14 @@ Azure Container Apps allows you to bind one or more custom domains to a containe
2021
- Ingress must be enabled for the container app.
2122

2223
> [!NOTE]
23-
> If you configure a [custom environment DNS (Domain Name System) suffix](environment-custom-dns-suffix.md), you cannot add a custom domain that contains this suffix to your Container App.
24+
> If you configure a [custom environment DNS (Domain Name System) suffix](environment-custom-dns-suffix.md), you can't add a custom domain that contains this suffix to your Container App.
2425
2526
## Add a custom domain and certificate
2627

28+
::: zone pivot="azure-portal"
29+
2730
> [!IMPORTANT]
28-
> If you are using a new certificate, you must have an existing [SNI domain certificate](https://wikipedia.org/wiki/Server_Name_Indication) file available to upload to Azure.
31+
> If you're using a new certificate, you must have an existing [SNI domain certificate](https://wikipedia.org/wiki/Server_Name_Indication) file available to upload to Azure.
2932
3033
1. Navigate to your container app in the [Azure portal](https://portal.azure.com)
3134

@@ -63,7 +66,7 @@ Azure Container Apps allows you to bind one or more custom domains to a containe
6366
| Apex domain | A record | An apex domain is a domain at the root level of your domain. For example, if your DNS (Domain Name System) zone is `contoso.com`, then `contoso.com` is the apex domain. |
6467
| 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. |
6568

66-
1. 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 own it. The setup depends on whether you are using custom domains with the private endpoint (preview) feature:
69+
1. 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 own it. The setup depends on whether you're using custom domains with the private endpoint (preview) feature:
6770

6871
# [General](#tab/general)
6972

@@ -89,7 +92,7 @@ Azure Container Apps allows you to bind one or more custom domains to a containe
8992
|--|--|--|
9093
| A | `@` | The Private IP of your private endpoint on your container apps environment. |
9194

92-
In addition, you will need to add the following record to your public DNS zone.
95+
In addition, you'll need to add the following record to your public DNS zone.
9396

9497
| Record type | Host | Value |
9598
|--|--|--|
@@ -111,7 +114,167 @@ Azure Container Apps allows you to bind one or more custom domains to a containe
111114
1. 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.
112115

113116
> [!NOTE]
114-
> For container apps in internal Container Apps environments, [additional configuration](./networking.md#dns) is required to use custom domains with VNET-scope ingress.
117+
> For container apps in internal Container Apps environments, [extra configuration](./networking.md#dns) is required to use custom domains with VNET-scope ingress.
118+
119+
::: zone-end
120+
121+
::: zone pivot="azure-cli"
122+
123+
Container Apps supports apex domains and subdomains. Each domain type requires a different DNS record type and validation method.
124+
125+
| Domain type | Record type | Validation method | Notes |
126+
|--|--|--|--|
127+
| 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. |
128+
| 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. |
129+
130+
1. Log in to Azure with the Azure CLI.
131+
132+
```azurecli
133+
az login
134+
```
135+
136+
1. Next, install the Azure Container Apps extension for the CLI.
137+
138+
```azurecli
139+
az extension add --name containerapp --upgrade
140+
```
141+
142+
1. Set the following environment variables. Replace the `<PLACEHOLDERS>` with your values.
143+
144+
```azurecli
145+
RESOURCE_GROUP = "<RESOURCE_GROUP>"
146+
CONTAINER_APP = "<CONTAINER_APP>"
147+
ENVIRONMENT = "<ENVIRONMENT>"
148+
TARGET_PORT = "<TARGET_PORT>"
149+
DOMAIN_NAME = "<DOMAIN_NAME>"
150+
CERTIFICATE_LOWERCASE_NAME = "<CERTIFICATE_LOWERCASE_NAME>"
151+
CERTIFICATE_LOCAL_PATH = "<CERTIFICATE_LOCAL_PATH>"
152+
CERTIFICATE_PASSWORD = "<CERTIFICATE_PASSWORD>"
153+
```
154+
155+
- Replace `<CERTIFICATE_LOCAL_PATH>` with the local path of your certificate file.
156+
- Replace `<CERTIFICATE_LOWERCASE_NAME>` with a lowercase certificate name that is unique within the environment.
157+
- Replace `<TARGET_PORT>` with the port that your container app is listening on.
158+
159+
1. Verify that your container app has HTTP ingress enabled.
160+
161+
```azurecli
162+
az containerapp ingress show \
163+
-n $CONTAINER_APP \
164+
-g $RESOURCE_GROUP
165+
```
166+
167+
If ingress isn't enabled, enable it with these steps:
168+
169+
```azurecli
170+
az containerapp ingress enable \
171+
-n $CONTAINER_APP \
172+
-g $RESOURCE_GROUP \
173+
--type external \
174+
--target-port $TARGET_PORT \
175+
--transport auto
176+
```
177+
178+
1. If you're configuring an apex domain, get the IP address of your Container Apps environment.
179+
180+
```azurecli
181+
az containerapp env show \
182+
-n $ENVIRONMENT \
183+
-g $RESOURCE_GROUP \
184+
-o tsv \
185+
--query "properties.staticIp"
186+
```
187+
188+
1. If you're configuring a subdomain, get the automatically generated domain of your container app.
189+
190+
```azurecli
191+
az containerapp show \
192+
-n $CONTAINER_APP \
193+
-g $RESOURCE_GROUP \
194+
-o tsv \
195+
--query "properties.configuration.ingress.fqdn"
196+
```
197+
198+
1. Get the domain verification code.
199+
200+
```azurecli
201+
az containerapp show \
202+
-n $CONTAINER_APP \
203+
-g $RESOURCE_GROUP \
204+
-o tsv \
205+
--query "properties.customDomainVerificationId"
206+
```
207+
208+
1. 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:
209+
210+
# [General](#tab/general)
211+
212+
- If you selected *A record*, create the following DNS records:
213+
214+
| Record type | Host | Value |
215+
|--|--|--|
216+
| A | `@` | The IP address of your Container Apps environment. |
217+
| TXT | `asuid` | The domain verification code. |
218+
219+
- If you selected *CNAME*, create the following DNS records:
220+
221+
| Record type | Host | Value |
222+
|--|--|--|
223+
| CNAME | The subdomain (for example, `www`) | The generated domain of your container app. |
224+
| TXT | `asuid.` followed by the subdomain (for example, `asuid.www`) | The domain verification code. |
225+
226+
# [Private endpoint](#tab/private-endpoint)
227+
228+
When using a private endpoint for your incoming traffic, you need to [create a private DNS zone](how-to-use-private-endpoint.md#configure-the-private-dns-zone).
229+
230+
- If you selected *A record*, create the following DNS records:
231+
232+
| Record type | Host | Value |
233+
|--|--|--|
234+
| A | `@` | The Private IP of your private endpoint on your container apps environment. |
235+
| TXT | `asuid` | The domain verification code. |
236+
237+
- If you selected *CNAME*, create the following DNS records:
238+
239+
| Record type | Host | Value |
240+
|--|--|--|
241+
| CNAME | The subdomain (for example, `www`) | The generated domain of your container app. |
242+
| TXT | `asuid.` followed by the subdomain (for example, `asuid.www`) | The domain verification code. |
243+
244+
---
245+
246+
1. Upload the certificate to your environment.
247+
248+
```azurecli
249+
az containerapp env certificate upload \
250+
-g $RESOURCE_GROUP \
251+
--name $ENVIRONMENT \
252+
--certificate-file $CERTIFICATE_LOCAL_PATH \
253+
--password $CERTIFICATE_PASSWORD \
254+
--certificate-name $CERTIFICATE_LOWERCASE_NAME
255+
```
256+
257+
1. Bind the certificate and domain to your container app.
258+
259+
```azurecli
260+
az containerapp hostname bind \
261+
--hostname $DOMAIN_NAME \
262+
-g $RESOURCE_GROUP \
263+
-n $CONTAINER_APP \
264+
--environment $ENVIRONMENT \
265+
--certificate $CERTIFICATE_LOWERCASE_NAME \
266+
--validation-method <VALIDATION_METHOD>
267+
```
268+
269+
- If you're configuring an *A record*, replace `<VALIDATION_METHOD>` with `HTTP`.
270+
271+
- If you're configuring a *CNAME*, replace `<VALIDATION_METHOD>` with `CNAME`.
272+
273+
It might take several minutes to issue the certificate and add the domain to your container app.
274+
275+
1. Once the operation is complete, navigate to your domain to verify that it's accessible.
276+
277+
::: zone-end
115278
116279
## Managing certificates
117280

‎articles/container-apps/custom-domains-managed-certificates.md

Lines changed: 60 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ author: craigshoemaker
66
ms.service: azure-container-apps
77
ms.custom: build-2023, devx-track-azurecli, ignite-2024
88
ms.topic: how-to
9-
ms.date: 09/19/2024
9+
ms.date: 01/14/2025
1010
ms.author: cshoe
1111
zone_pivot_groups: azure-cli-or-portal
1212
---
@@ -18,7 +18,7 @@ Azure Container Apps allows you to bind one or more custom domains to a containe
1818
If you want to set up a custom domain using your own certificate, see [Custom domain names and certificates in Azure Container Apps](custom-domains-certificates.md).
1919

2020
> [!NOTE]
21-
> If you configure a [custom environment DNS suffix](environment-custom-dns-suffix.md), you cannot add a custom domain that contains this suffix to your Container App.
21+
> If you configure a [custom environment DNS suffix](environment-custom-dns-suffix.md), you can't add a custom domain that contains this suffix to your Container App.
2222
2323
## Free certificate requirements
2424

@@ -30,10 +30,11 @@ The requirements are:
3030

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

33-
- 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.
33+
- 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.
3434

3535
> [!NOTE]
3636
> To ensure the certificate issuance and subsequent renewals proceed successfully, all requirements must be met at all times when the managed certificate is assigned.
37+
3738
## Add a custom domain and managed certificate
3839

3940
::: zone pivot="azure-portal"
@@ -98,7 +99,7 @@ Container Apps supports apex domains and subdomains. Each domain type requires a
9899
| 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. |
99100
| 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. |
100101

101-
1. Log in to Azure with the Azure CLI.
102+
1. Log in to Azure with the Azure CLI.
102103

103104
```azurecli
104105
az login
@@ -110,46 +111,73 @@ Container Apps supports apex domains and subdomains. Each domain type requires a
110111
az extension add --name containerapp --upgrade
111112
```
112113
114+
1. Set the following environment variables. Replace the `<PLACEHOLDERS>` with your values.
115+
116+
```azurecli
117+
RESOURCE_GROUP = "<RESOURCE_GROUP>"
118+
CONTAINER_APP = "<CONTAINER_APP>"
119+
ENVIRONMENT = "<ENVIRONMENT>"
120+
TARGET_PORT = "<TARGET_PORT>"
121+
DOMAIN_NAME = "<DOMAIN_NAME>"
122+
CERTIFICATE_LOWERCASE_NAME = "<CERTIFICATE_LOWERCASE_NAME>"
123+
CERTIFICATE_LOCAL_PATH = "<CERTIFICATE_LOCAL_PATH>"
124+
CERTIFICATE_PASSWORD = "<CERTIFICATE_PASSWORD>"
125+
```
126+
127+
- Replace `<CERTIFICATE_LOCAL_PATH>` with the local path of your certificate file.
128+
- Replace `<CERTIFICATE_LOWERCASE_NAME>` with a lowercase certificate name that is unique within the environment.
129+
- Replace `<TARGET_PORT>` with the port that your container app is listening on.
130+
113131
1. Verify that your container app has HTTP ingress enabled.
114132
115133
```azurecli
116-
az containerapp ingress show -n <CONTAINER_APP_NAME> -g <RESOURCE_GROUP_NAME>
134+
az containerapp ingress show \
135+
-n $CONTAINER_APP \
136+
-g $RESOURCE_GROUP
117137
```
118138
119139
If ingress isn't enabled, enable it with these steps:
120140
121141
```azurecli
122-
az containerapp ingress enable -n <CONTAINER_APP_NAME> -g <RESOURCE_GROUP_NAME> \
123-
--type external --target-port <TARGET_PORT> --transport auto
142+
az containerapp ingress enable \
143+
-n $CONTAINER_APP \
144+
-g $RESOURCE_GROUP \
145+
--type external \
146+
--target-port $TARGET_PORT \
147+
--transport auto
124148
```
125149
126-
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.
127-
128150
1. If you're configuring an apex domain, get the IP address of your Container Apps environment.
129151
130152
```azurecli
131-
az containerapp env show -n <ENVIRONMENT_NAME> -g <RESOURCE_GROUP_NAME> -o tsv --query "properties.staticIp"
153+
az containerapp env show \
154+
-n $ENVIRONMENT \
155+
-g $RESOURCE_GROUP \
156+
-o tsv \
157+
--query "properties.staticIp"
132158
```
133159
134-
Replace `<ENVIRONMENT_NAME>` with the name of your environment, and `<RESOURCE_GROUP_NAME>` with the name of the resource group that contains your environment.
135-
136160
1. If you're configuring a subdomain, get the automatically generated domain of your container app.
137161
138162
```azurecli
139-
az containerapp show -n <CONTAINER_APP_NAME> -g <RESOURCE_GROUP_NAME> -o tsv --query "properties.configuration.ingress.fqdn"
163+
az containerapp show \
164+
-n $CONTAINER_APP \
165+
-g $RESOURCE_GROUP \
166+
-o tsv \
167+
--query "properties.configuration.ingress.fqdn"
140168
```
141169
142-
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.
143-
144170
1. Get the domain verification code.
145171
146172
```azurecli
147-
az containerapp show -n <CONTAINER_APP_NAME> -g <RESOURCE_GROUP_NAME> -o tsv --query "properties.customDomainVerificationId"
173+
az containerapp show \
174+
-n $CONTAINER_APP \
175+
-g $RESOURCE_GROUP \
176+
-o tsv \
177+
--query "properties.customDomainVerificationId"
148178
```
149179
150-
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.
151-
152-
1. 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:
180+
1. 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:
153181
154182
# [General](#tab/general)
155183
@@ -166,10 +194,10 @@ Container Apps supports apex domains and subdomains. Each domain type requires a
166194
|--|--|--|
167195
| CNAME | The subdomain (for example, `www`) | The generated domain of your container app. |
168196
| TXT | `asuid.` followed by the subdomain (for example, `asuid.www`) | The domain verification code. |
169-
197+
170198
# [Private endpoint](#tab/private-endpoint)
171199
172-
When using a private endpoint for your incoming traffic, you need to [create a private DNS zone](how-to-use-private-endpoint.md#configure-the-private-dns-zone).
200+
When using a private endpoint for your incoming traffic, you need to [create a private DNS zone](how-to-use-private-endpoint.md#configure-the-private-dns-zone).
173201
174202
- If you selected *A record*, create the following DNS records:
175203
@@ -190,20 +218,25 @@ Container Apps supports apex domains and subdomains. Each domain type requires a
190218
1. Add the domain to your container app.
191219
192220
```azurecli
193-
az containerapp hostname add --hostname <DOMAIN_NAME> -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME>
221+
az containerapp hostname add \
222+
--hostname $DOMAIN_NAME \
223+
-g $RESOURCE_GROUP \
224+
-n $CONTAINER_APP
194225
```
195226
196-
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.
197-
198227
1. Configure the managed certificate and bind the domain to your container app.
199228
200229
```azurecli
201-
az containerapp hostname bind --hostname <DOMAIN_NAME> -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --environment <ENVIRONMENT_NAME> --validation-method <VALIDATION_METHOD>
230+
az containerapp hostname bind \
231+
--hostname $DOMAIN_NAME \
232+
-g $RESOURCE_GROUP \
233+
-n $CONTAINER_APP \
234+
--environment $ENVIRONMENT \
235+
--validation-method <VALIDATION_METHOD>
202236
```
203237
204-
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.
205-
206238
- If you're configuring an *A record*, replace `<VALIDATION_METHOD>` with `HTTP`.
239+
207240
- If you're configuring a *CNAME*, replace `<VALIDATION_METHOD>` with `CNAME`.
208241
209242
It might take several minutes to issue the certificate and add the domain to your container app.

0 commit comments

Comments
 (0)