Deploy a container group with custom DNS settings
In Azure Virtual Network, you can deploy container groups using the
az container create command in the Azure CLI. You can also provide advanced configuration settings to the
az container create command using a YAML configuration file.
This article demonstrates how to deploy a container group with custom DNS settings using a YAML configuration file.
For more information on deploying container groups to a virtual network, see the Deploy in a virtual network article.
Previously, the process of deploying container groups on virtual networks used network profiles for configuration. However, network profiles have been retired as of the
2021-07-01 API version. We recommend you use the latest API version, which relies on subnet IDs instead.
An active Azure subscription. If you don't have an active Azure subscription, create a free account before you begin.
A resource group to manage all the resources you use in this how-to guide. We use the example resource group name ACIResourceGroup throughout this article.
az group create --name ACIResourceGroup --location westus
For networking scenarios and limitations, see Virtual network scenarios and resources for Azure Container Instances.
Container group deployment to a virtual network is available for Linux containers in most regions where Azure Container Instances is available. For details, see Regions and resource availability. Examples in this article are formatted for the Bash shell. For PowerShell or command prompt, adjust the line continuation characters accordingly.
Create your virtual network
You'll need a virtual network to deploy a container group with a custom DNS configuration. This virtual network will require a subnet with permissions to create Azure Container Instances resources and a linked private DNS zone to test name resolution.
This guide uses a virtual network named
aci-vnet, a subnet named
aci-subnet, and a private DNS zone named
private.contoso.com. We use Azure Private DNS Zones, which you can learn about in the Private DNS Overview.
If you have an existing virtual network that meets these criteria, you can skip to Deploy your container group.
You can modify the following commands with your own information as needed.
Create the virtual network using the az network vnet create command. Enter address prefixes in Classless Inter-Domain Routing (CIDR) format (for example:
az network vnet create \ --name aci-vnet \ --resource-group ACIResourceGroup \ --location westus \ --address-prefix 10.0.0.0/16
Create the subnet using the az network vnet subnet create command. The following command creates a subnet in your virtual network with a delegation that permits it to create container groups. For more information about working with subnets, see the Add, change, or delete a virtual network subnet. For more information about subnet delegation, see the Virtual Network Scenarios and Resources article section on delegated subnets.
az network vnet subnet create \ --name aci-subnet \ --resource-group ACIResourceGroup \ --vnet-name aci-vnet \ --address-prefixes 10.0.0.0/24 \ --delegations Microsoft.ContainerInstance/containerGroups
Record the subnet ID key-value pair from the output of this command. You'll use this in your YAML configuration file later. It will take the form
Create the private DNS Zone using the az network private-dns zone create command.
az network private-dns zone create -g ACIResourceGroup -n private.contoso.com
Link the DNS zone to your virtual network using the az network private-dns link vnet create command. The DNS server is only required to test name resolution. The
-eflag enables automatic hostname registration, which is unneeded, so we set it to
az network private-dns link vnet create \ -g ACIResourceGroup \ -n aciDNSLink \ -z private.contoso.com \ -v aci-vnet \ -e false
Once you've completed the steps above, you should see an output with a final key-value pair that reads
Deploy your container group
Copy the following YAML into a new file named custom-dns-deploy-aci.yaml. Edit the following configurations with your values:
dnsConfig: DNS settings for your containers within your container group.
nameServers: A list of name servers to be used for DNS lookups.
searchDomains: DNS suffixes to be appended for DNS lookups.
ipAddress: The private IP address settings for the container group.
ports: The ports to open, if any.
protocol: The protocol (TCP or UDP) for the opened port.
subnetIDs: Network settings for the subnet(s) in the virtual network.
id: The full Resource Manager resource ID of the subnet, which you obtained earlier.
The DNS config fields aren't automatically queried at this time, so these fields must be explicitly filled out.
apiVersion: '2021-07-01' location: westus name: pwsh-vnet-dns properties: containers: - name: pwsh-vnet-dns properties: command: - /bin/bash - -c - echo hello; sleep 10000 environmentVariables:  image: mcr.microsoft.com/powershell:latest ports: - port: 80 resources: requests: cpu: 1.0 memoryInGB: 2.0 dnsConfig: nameServers: - 10.0.0.10 # DNS Server 1 - 10.0.0.11 # DNS Server 2 searchDomains: contoso.com # DNS search suffix ipAddress: type: Private ports: - port: 80 subnetIds: - id: /subscriptions/<subscription-ID>/resourceGroups/ACIResourceGroup/providers/Microsoft.Network/virtualNetworks/aci-vnet/subnets/aci-subnet osType: Linux tags: null type: Microsoft.ContainerInstance/containerGroups
Deploy the container group with the az container create command, specifying the YAML file name with the
az container create --resource-group ACIResourceGroup \ --file custom-dns-deploy-aci.yaml
Once the deployment is complete, run the az container show command to display its status. Sample output:
az container show --resource-group ACIResourceGroup --name pwsh-vnet-dns -o table
Name ResourceGroup Status Image IP:ports Network CPU/Memory OsType Location ---------------- --------------- -------- ------------------------------------------ ----------- --------- --------------- -------- ---------- pwsh-vnet-dns ACIResourceGroup Running mcr.microsoft.com/powershell 10.0.0.5:80 Private 1.0 core/2.0 gb Linux westus
After the status shows
Running, execute the az container exec command to obtain bash access within the container.
az container exec --resource-group ACIResourceGroup --name pwsh-vnet-dns --exec-command "/bin/bash"
Validate that DNS is working as expected from within your container. For example, read the
/etc/resolv.conf file to ensure it's configured with the DNS settings provided in the YAML file.
root@wk-caas-81d609b206c541589e11058a6d260b38-90b0aff460a737f346b3b0:/# cat /etc/resolv.conf nameserver 10.0.0.10 nameserver 10.0.0.11 search contoso.com
Clean up resources
Delete container instances
When you're finished with the container instance you created, delete it with the az container delete command:
az container delete --resource-group ACIResourceGroup --name pwsh-vnet-dns -y
Delete network resources
If you don't plan to use this virtual network again, you can delete it with the az network vnet delete command:
az network vnet delete --resource-group ACIResourceGroup --name aci-vnet
Delete resource group
If you don't plan to use this resource group outside of this guide, you can delete it with az group delete command:
az group delete --name ACIResourceGroup
y when prompted if you're sure you wish to perform the operation.
See the Azure quickstart template Create an Azure container group with VNet, to deploy a container group within a virtual network.