Deploy container instances into an Azure virtual network
Azure Virtual Network provides secure, private networking for your Azure and on-premises resources. By deploying container groups into an Azure virtual network, your containers can communicate securely with other resources in the virtual network.
Container groups deployed into an Azure virtual network enable scenarios like:
- Direct communication between container groups in the same subnet
- Send task-based workload output from container instances to a database in the virtual network
- Retrieve content for container instances from a service endpoint in the virtual network
- Container communication with virtual machines in the virtual network
- Container communication with on-premises resources through a VPN gateway or ExpressRoute
Virtual network deployment limitations
Certain limitations apply when you deploy container groups to a virtual network.
- To deploy container groups to a subnet, the subnet cannot contain any other resource types. Remove all existing resources from an existing subnet prior to deploying container groups to it, or create a new subnet.
- You cannot use a managed identity in a container group deployed to a virtual network.
- Due to the additional networking resources involved, deploying a container group to a virtual network is typically somewhat slower than deploying a standard container instance.
While this feature is in preview, the following limitations apply when deploying container groups to a virtual network.
Regions and resource availability
|North Europe, Southeast Asia, Central US, East US, East US 2, South Central US, West US 2||Linux||4||16|
|Australia East, West Central US||Linux||1||1.5|
Container resource limits may differ from limits for non-networked container instances in these regions. Currently only Linux containers are supported for this feature. Windows support is planned.
Unsupported networking scenarios
- Azure Load Balancer - Placing an Azure Load Balancer in front of container instances in a networked container group is not supported
- Virtual network peering - You can't peer a virtual network containing a subnet delegated to Azure Container Instances to another virtual network
- Route tables - User-defined routes can't be set up in a subnet delegated to Azure Container Instances
- Network security groups - Outbound security rules in NSGs applied to a subnet delegated to Azure Container Instances aren't currently enforced
- Public IP or DNS label - Container groups deployed to a virtual network don't currently support exposing containers directly to the internet with a public IP address or a fully qualified domain name
- Internal name resolution - Name resolution for Azure resources in the virtual network via the internal Azure DNS is not supported
Network resource deletion requires additional steps once you've deployed container groups to the virtual network.
Required network resources
There are three Azure Virtual Network resources required for deploying container groups to a virtual network: the virtual network itself, a delegated subnet within the virtual network, and a network profile.
A virtual network defines the address space in which you create one or more subnets. You then deploy Azure resources (like container groups) into the subnets in your virtual network.
Subnets segment the virtual network into separate address spaces usable by the Azure resources you place in them. You create one or several subnets within a virtual network.
The subnet that you use for container groups may contain only container groups. When you first deploy a container group to a subnet, Azure delegates that subnet to Azure Container Instances. Once delegated, the subnet can be used only for container groups. If you attempt to deploy resources other than container groups to a delegated subnet, the operation fails.
A network profile is a network configuration template for Azure resources. It specifies certain network properties for the resource, for example, the subnet into which it should be deployed. When you first use the az container create command to deploy a container group to a subnet (and thus a virtual network), Azure creates a network profile for you. You can then use that network profile for future deployments to the subnet.
To use a Resource Manager template, YAML file, or a programmatic method to deploy a container group to a subnet, you need to provide the full Resource Manager resource ID of a network profile. You can use a profile previously created using az container create, or create a profile using a Resource Manager template (see template example and reference). To get the ID of a previously created profile, use the az network profile list command.
In the following diagram, several container groups have been deployed to a subnet delegated to Azure Container Instances. Once you've deployed one container group to a subnet, you can deploy additional container groups to it by specifying the same network profile.
You can use az container create to deploy container groups to a new virtual network and allow Azure to create the required network resources for you, or deploy to an existing virtual network.
New virtual network
To deploy to a new virtual network and have Azure create the network resources for you automatically, specify the following when you execute az container create:
- Virtual network name
- Virtual network address prefix in CIDR format
- Subnet name
- Subnet address prefix in CIDR format
The virtual network and subnet address prefixes specify the address spaces for the virtual network and subnet, respectively. These values are represented in Classless Inter-Domain Routing (CIDR) notation, for example
10.0.0.0/16. For more information about working with subnets, see Add, change, or delete a virtual network subnet.
Once you've deployed your first container group with this method, you can deploy to the same subnet by specifying the virtual network and subnet names, or the network profile that Azure automatically creates for you. Because Azure delegates the subnet to Azure Container Instances, you can deploy only container groups to the subnet.
Existing virtual network
To deploy a container group to an existing virtual network:
- Create a subnet within your existing virtual network, or empty an existing subnet of all other resources
- Deploy a container group with az container create and specify one of the following:
- Virtual network name and subnet name
- Virtual network resource ID and subnet resource ID, which allows using a virtual network from a different resource group
- Network profile name or ID, which you can obtain using az network profile list
Once you deploy your first container group to an existing subnet, Azure delegates that subnet to Azure Container Instances. You can no longer deploy resources other than container groups to that subnet.
The following sections describe how to deploy container groups to a virtual network with the Azure CLI. The command examples are formatted for the Bash shell. If you prefer another shell such as PowerShell or Command Prompt, adjust the line continuation characters accordingly.
Deploy to a new virtual network
First, deploy a container group and specify the parameters for a new virtual network and subnet. When you specify these parameters, Azure creates the virtual network and subnet, delegates the subnet to Azure Container instances, and also creates a network profile. Once these resources are created, your container group is deployed to the subnet.
Run the following az container create command that specifies settings for a new virtual network and subnet. You need to supply the name of a resource group that was created in a region that supports container groups in a virtual network. This command deploys the public Microsoft aci-helloworld container that runs a small Node.js webserver serving a static web page. In the next section, you'll deploy a second container group to the same subnet, and test communication between the two container instances.
az container create \ --name appcontainer \ --resource-group myResourceGroup \ --image mcr.microsoft.com/azuredocs/aci-helloworld \ --vnet aci-vnet \ --vnet-address-prefix 10.0.0.0/16 \ --subnet aci-subnet \ --subnet-address-prefix 10.0.0.0/24
When you deploy to a new virtual network by using this method, the deployment can take a few minutes while the network resources are created. After the initial deployment, additional container group deployments complete more quickly.
Deploy to existing virtual network
Now that you've deployed a container group to a new virtual network, deploy a second container group to the same subnet, and verify communication between the two container instances.
First, get the IP address of the first container group you deployed, the appcontainer:
az container show --resource-group myResourceGroup --name appcontainer --query ipAddress.ip --output tsv
The output should display the IP address of the container group in the private subnet:
$ az container show --resource-group myResourceGroup --name appcontainer --query ipAddress.ip --output tsv 10.0.0.4
CONTAINER_GROUP_IP to the IP you retrieved with the
az container show command, and execute the following
az container create command. This second container, commchecker, runs an Alpine Linux-based image and executes
wget against the first container group's private subnet IP address.
CONTAINER_GROUP_IP=<container-group-IP-here> az container create \ --resource-group myResourceGroup \ --name commchecker \ --image alpine:3.5 \ --command-line "wget $CONTAINER_GROUP_IP" \ --restart-policy never \ --vnet aci-vnet \ --subnet aci-subnet
After this second container deployment has completed, pull its logs so you can see the output of the
wget command it executed:
az container logs --resource-group myResourceGroup --name commchecker
If the second container communicated successfully with the first, output should be similar to:
$ az container logs --resource-group myResourceGroup --name commchecker Connecting to 10.0.0.4 (10.0.0.4:80) index.html 100% |*******************************| 1663 0:00:00 ETA
The log output should show that
wget was able to connect and download the index file from the first container using its private IP address on the local subnet. Network traffic between the two container groups remained within the virtual network.
Deploy to existing virtual network - YAML
You can also deploy a container group to an existing virtual network by using a YAML file. To deploy to a subnet in a virtual network, you specify several additional properties in the YAML:
ipAddress: The IP address settings for the container group.
ports: The ports to open, if any.
protocol: The protocol (TCP or UDP) for the opened port.
networkProfile: Specifies network settings like the virtual network and subnet for an Azure resource.
id: The full Resource Manager resource ID of the
To deploy a container group to a virtual network with a YAML file, you first need to get the ID of the network profile. Execute the az network profile list command, specifying the name of the resource group that contains your virtual network and delegated subnet.
az network profile list --resource-group myResourceGroup --query .id --output tsv
The output of the command displays the full resource ID for the network profile:
$ az network profile list --resource-group myResourceGroup --query .id --output tsv /subscriptions/<Subscription ID>/resourceGroups/myResourceGroup/providers/Microsoft.Network/networkProfiles/aci-network-profile-aci-vnet-aci-subnet
Once you have the network profile ID, copy the following YAML into a new file named vnet-deploy-aci.yaml. Under
networkProfile, replace the
id value with ID you just retrieved, then save the file. This YAML creates a container group named appcontaineryaml in your virtual network.
apiVersion: '2018-09-01' location: westus name: appcontaineryaml properties: containers: - name: appcontaineryaml properties: image: mcr.microsoft.com/azuredocs/aci-helloworld ports: - port: 80 protocol: TCP resources: requests: cpu: 1.0 memoryInGB: 1.5 ipAddress: type: Private ports: - protocol: tcp port: '80' networkProfile: id: /subscriptions/<Subscription ID>/resourceGroups/container/providers/Microsoft.Network/networkProfiles/aci-network-profile-aci-vnet-subnet osType: Linux restartPolicy: Always tags: null type: Microsoft.ContainerInstance/containerGroups
Deploy the container group with the az container create command, specifying the YAML file name for the
az container create --resource-group myResourceGroup --file vnet-deploy-aci.yaml
Once the deployment has completed, run the az container show command to display its status:
$ az container show --resource-group myResourceGroup --name appcontaineryaml --output table Name ResourceGroup Status Image IP:ports Network CPU/Memory OsType Location ---------------- --------------- -------- ------------------------------------------ ----------- --------- --------------- -------- ---------- appcontaineryaml myResourceGroup Running mcr.microsoft.com/azuredocs/aci-helloworld 10.0.0.5:80 Private 1.0 core/1.5 gb Linux westus
Clean up resources
Delete container instances
When you're done working with the container instances you created, delete them with the following commands:
az container delete --resource-group myResourceGroup --name appcontainer -y az container delete --resource-group myResourceGroup --name commchecker -y az container delete --resource-group myResourceGroup --name appcontaineryaml -y
Delete network resources
If you recieve an error while attempting to remove the Network Profile allow 2-3 days for the platform to automatically mitigate the issue and attempt the deletion again. If you still have issues removing the Network Profile open a support reqest.
The initial preview of this feature requires several additional commands to delete the network resources you created earlier. If you used the example commands in previous sections of this article to create your virtual network and subnet, then you can use the following script to delete those network resources.
Before executing the script, set the
RES_GROUP variable to the name of the resource group containing the virtual network and subnet that should be deleted. Update the name of the virtual network if you did not use the
aci-vnet name suggested earlier. The script is formatted for the Bash shell. If you prefer another shell such as PowerShell or Command Prompt, you'll need to adjust variable assignment and accessors accordingly.
This script deletes resources! It deletes the virtual network and all subnets it contains. Be sure that you no longer need any of the resources in the virtual network, including any subnets it contains, prior to running this script. Once deleted, these resources are unrecoverable.
# Replace <my-resource-group> with the name of your resource group RES_GROUP=<my-resource-group> # Get network profile ID NETWORK_PROFILE_ID=$(az network profile list --resource-group $RES_GROUP --query .id --output tsv) # Delete the network profile az network profile delete --id $NETWORK_PROFILE_ID -y # Delete virtual network az network vnet delete --resource-group $RES_GROUP --name aci-vnet
To deploy a new virtual network, subnet, network profile, and container group using a Resource Manager template, see Create an Azure container group with VNet.
Several virtual network resources and features were discussed in this article, though briefly. The Azure Virtual Network documentation covers these topics extensively: