Virtual network injection in Azure Chaos Studio

Azure Virtual Network is the fundamental building block for your private network in Azure. A virtual network enables many types of Azure resources to securely communicate with each other, the internet, and on-premises networks. A virtual network is similar to a traditional network that you operate in your own datacenter. It brings other benefits of Azure's infrastructure, such as scale, availability, and isolation.

Virtual network injection allows an Azure Chaos Studio resource provider to inject containerized workloads into your virtual network so that resources without public endpoints can be accessed via a private IP address on the virtual network. After you've configured virtual network injection for a resource in a virtual network and enabled the resource as a target, you can use it in multiple experiments. An experiment can target a mix of private and nonprivate resources if the private resources are configured according to the instructions in this article.

Chaos Studio also supports running agent-based experiments using Private Endpoints. Find detailed instructions at Setup private link for agent-based experiments.

Resource type support

Currently, you can only enable certain resource types for Chaos Studio virtual network injection:

• Azure Kubernetes Service (AKS) targets can be enabled with virtual network injection through the Azure portal and the Azure CLI. All AKS Chaos Mesh faults can be used.
• Azure Key Vault targets can be enabled with virtual network injection through the Azure portal and the Azure CLI. The faults that can be used with virtual network injection are Disable Certificate, Increment Certificate Version, and Update Certificate Policy.

Enable virtual network injection

To use Chaos Studio with virtual network injection, you must meet the following requirements.

1. The Microsoft.ContainerInstance and Microsoft.Relay resource providers must be registered with your subscription.
2. The virtual network where Chaos Studio resources will be injected must have two subnets: a container subnet and a relay subnet. A container subnet is used for the Chaos Studio containers that will be injected into your private network. A relay subnet is used to forward communication from Chaos Studio to the containers inside the private network.
   1. Both subnets need at least /28 for the size of the address space (in this case /27 is larger than /28, for example). An example is an address prefix of 10.0.0.0/28 or 10.0.0.0/24.
   2. The container subnet must be delegated to Microsoft.ContainerInstance/containerGroups.
   3. The subnets can be arbitrarily named, but we recommend ChaosStudioContainerSubnet and ChaosStudioRelaySubnet.
   4. Network Security Groups (NSG): If using NSGs to control traffic, ensure both subnets allow port 443 for inbound and outbound traffic. See the Permissions and security section for detailed port requirements.
3. When you enable the desired resource as a target so that you can use it in Chaos Studio experiments, the following properties must be set:
   1. Set properties.subnets.containerSubnetId to the ID for the container subnet.
   2. Set properties.subnets.relaySubnetId to the ID for the relay subnet.

If you're using the Azure portal to enable a private resource as a Chaos Studio target, Chaos Studio currently only recognizes subnets named ChaosStudioContainerSubnet and ChaosStudioRelaySubnet. If these subnets don't exist, the portal workflow can create them automatically.

If you're using the CLI, the container and relay subnets can have any name (subject to the resource naming guidelines). Specify the appropriate IDs when you enable the resource as a target.

Auto-Tagging of Experiment Resources

When a Chaos Studio experiment is configured to run with private networking enabled, Chaos Studio automatically provisions two key resources in your subscription:

1. An Azure container instance that facilitates secure communication.
2. An Azure relay that manages network routing for the experiment to the Chaos Studio backend.

Previously, these created on behalf of resources did not inherit the tags applied to the experiment, which could cause Azure Policy enforcement conflicts in environments that require resource tagging.

With this update, Chaos Studio now automatically applies the same tags from your experiment to the container and relay resources it creates. This improvement enhances resource visibility, compliance, and governance within your Azure environment.

How It Works

• Pre-requisite: You are creating an experiment that targets resources that are within a virtual network.
• When an experiment is tagged, those same tags are automatically propagated to any resources Chaos Studio provisions for private networking.
• These tags will be visible in the Azure portal, Azure CLI, and ARM API queries, just like any other Azure resource.
• No additional configuration is required—simply applying tags to your experiment ensures they are inherited by all related resources.

Benefits

✅ Ensures Compliance – Resources now meet Azure Policy tagging requirements.
✅ Improves Resource Tracking – All experiment-associated resources carry the same tags for easy identification.
✅ No Extra Setup Required – Works automatically when an experiment is tagged.

Example: Use Chaos Studio with a private AKS cluster

This example shows how to configure a private AKS cluster to use with Chaos Studio. It assumes you already have a private AKS cluster within your Azure subscription. To create one, see Create a private Azure Kubernetes Service cluster.

Azure portal

1. In the Azure portal, go to Subscriptions > Resource providers in your subscription.

2. Register the Microsoft.ContainerInstance and Microsoft.Relay resource providers, if they aren't already registered, by selecting the provider and then selecting Register. Reregister the Microsoft.Chaos resource provider.

   

3. Go to Chaos Studio and select Targets. Find your desired AKS cluster and select Enable targets > Enable service-direct targets.

   

4. Select the cluster's virtual network. If the virtual network already includes subnets named ChaosStudioContainerSubnet and ChaosStudioRelaySubnet, select them. If they don't already exist, they're automatically created for you.

   

5. Select Review + Enable > Enable.

   

Now you can use your private AKS cluster with Chaos Studio. To learn how to install Chaos Mesh and run the experiment, see Create a chaos experiment that uses a Chaos Mesh fault with the Azure portal.

Azure CLI

1. Register the Microsoft.ContainerInstance and Microsoft.Relay resource providers with your subscription by running the following commands. If they're both already registered, you can skip this step. For more information, see the Register resource provider instructions.

   az provider register --namespace 'Microsoft.ContainerInstance' --wait
   

   az provider register --namespace 'Microsoft.Relay' --wait
   

   Verify the registration by running the following commands:

   az provider show --namespace 'Microsoft.ContainerInstance' | grep registrationState
   

   az provider show --namespace 'Microsoft.Relay' | grep registrationState
   

   In the output, you should see something similar to:

   "registrationState": "Registered",
   

2. Reregister the Microsoft.Chaos resource provider with your subscription.

   az provider register --namespace 'Microsoft.Chaos' --wait
   

   Verify the registration by running the following command:

   az provider show --namespace 'Microsoft.Chaos' | grep registrationState
   

   In the output, you should see something similar to:

   "registrationState": "Registered",
   

3. Create two subnets in the virtual network you want to inject Chaos Studio resources into (in this case, the private AKS cluster's virtual network):

   • Container subnet (example name: ChaosStudioContainerSubnet)
     • Delegate the subnet to the Microsoft.ContainerInstance/containerGroups service.
     • This subnet must have at least /28 in the address space.
   • Relay subnet (example name: ChaosStudioRelaySubnet)
     • This subnet must have at least /28 in the address space.

   az network vnet subnet create -g MyResourceGroup --vnet-name MyVnetName --name ChaosStudioContainerSubnet --address-prefixes "10.0.0.0/28" --delegations "Microsoft.ContainerInstance/containerGroups"
   

   az network vnet subnet create -g MyResourceGroup --vnet-name MyVnetName --name ChaosStudioRelaySubnet --address-prefixes "10.0.0.0/28"
   

4. When you enable targets for the AKS cluster so that you can use it in chaos experiments, set the properties.subnets.containerSubnetId and properties.subnets.relaySubnetId properties by using the new subnets you created in step 3.

   Replace $SUBSCRIPTION_ID with your Azure subscription ID. Replace $RESOURCE_GROUP and $AKS_CLUSTER with the resource group name and your AKS cluster resource name. Also, replace $AKS_INFRA_RESOURCE_GROUP and $AKS_VNET with your AKS infrastructure resource group name and virtual network name. Replace $URL with the corresponding URL used for onboarding the target resource. To find this URL, reference Onboarding a resource as a Chaos Studio target.

   CONTAINER_SUBNET_ID=/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$AKS_INFRA_RESOURCE_GROUP/providers/Microsoft.Network/virtualNetworks/$AKS_VNET/subnets/ChaosStudioContainerSubnet
   RELAY_SUBNET_ID=/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$AKS_INFRA_RESOURCE_GROUP/providers/Microsoft.Network/virtualNetworks/$AKS_VNET/subnets/ChaosStudioRelaySubnet
   BODY="{ \"properties\": { \"subnets\": { \"containerSubnetId\": \"$CONTAINER_SUBNET_ID\", \"relaySubnetId\": \"$RELAY_SUBNET_ID\" } } }"
   az rest --method put --url $URL --body "$BODY"
   

Now you can use your private AKS cluster with Chaos Studio. To learn how to install Chaos Mesh and run the experiment, see Create a chaos experiment that uses a Chaos Mesh fault with the Azure CLI.

Permissions and security

Required RBAC permissions

When using Chaos Studio with virtual network injection, the managed identity for the experiment must have the following RBAC actions to deploy the necessary resources in your subscription:

• Microsoft.Relay/namespaces/* - To create and manage Azure Relay namespaces
• Microsoft.Relay/namespaces/privateEndpointConnectionProxies/* - To manage private endpoint connections for the relay
• Microsoft.ContainerInstance/containerGroups/* - To deploy container instances for chaos experiments
• Microsoft.Network/privateEndpoints/* - To create private endpoints for secure connectivity
• Microsoft.Relay/namespaces/hybridConnections/* - To manage hybrid connections used for tunneling

Network Security Group (NSG) port requirements

If you're using Network Security Groups to control traffic in your virtual network, you need to configure the following port rules:

Relay subnet requirements

The Relay subnet uses Azure Relay's Hybrid Connection for secure tunneling between Chaos Studio and your private resources. Configure the following rules:

• Inbound traffic: Allow port 443 (HTTPS) - Required for receiving connections from Chaos Studio
• Outbound traffic: Allow port 443 (HTTPS) - Required for establishing connections to Azure Relay service

Container subnet requirements

The Container subnet hosts the containerized workloads that execute chaos experiments. Configure the following rules:

• Inbound traffic: Allow port 443 (HTTPS) - Required for the container to accept hybrid connection traffic
• Outbound traffic: Allow port 443 (HTTPS) - Required for communicating with target resource data planes (for example, Kubernetes API endpoints for Chaos Mesh faults)

Note

All communication uses standard HTTPS port 443, as documented in Azure Relay port settings.

Limitations

• Virtual network injection is currently only possible in subscriptions/regions where Azure Container Instances and Azure Relay are available.

• When you create a Target resource that you enable with virtual network injection, you need Microsoft.Network/virtualNetworks/subnets/write access to the virtual network. For example, if the AKS cluster is deployed to virtualNetwork_A, then you must have permissions to create subnets in virtualNetwork_A to enable virtual network injection for the AKS cluster.

• Subscription scoping limitation for virtual network injection
  When using Chaos Studio with private networking (virtual network injection), the virtual network (VNet) that contains the target resource (e.g., an AKS cluster) must reside in the same Azure subscription as the Chaos Studio experiment.

  While Chaos Studio generally supports targeting resources across subscriptions, this capability does not apply when private networking is enabled. This is because the private endpoint and other supporting resources required for VNet injection are deployed by Chaos Studio into the same subscription as the experiment. If the target VNet resides in a different subscription, private endpoint creation will fail due to cross-subscription restrictions.

  Workaround: To use private networking successfully, ensure that the target VNet and the Chaos Studio experiment are created within the same Azure subscription.

Next steps

Now that you understand how virtual network injection can be achieved for Chaos Studio, you're ready to:

• Create and run your first experiment
• Create and run your first Azure Kubernetes Service experiment