Add Dynamic NICs to an instance

For information about creating new instances, see Create VMs with multiple network interfaces.

Before you begin

Before adding Dynamic NICs to an instance, do the following:

• Make sure you are familiar with the properties and limitations of Dynamic NICs as described in the multiple network interfaces overview.
• If necessary, view your instance's existing network interfaces by following the instructions in View network interfaces for an instance.

Add a Dynamic NIC

This section describes how to add a Dynamic NIC to an instance.

When you add a Dynamic NIC, you might observe a propagation delay. This delay is typically a few seconds, but it can be, in rare cases, up to one minute.

gcloud beta compute instances network-interfaces add INSTANCE_NAME \
   --zone=ZONE \
   --vlan=VLAN_ID \
   --parent-nic-name=PARENT_VNIC_NAME \
   --network=NETWORK \
   --subnetwork=SUBNET

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME/addNetworkInterface
{
  "subnetwork": "regions/REGION/subnetworks/SUBNET",
  "parentNicName": "PARENT_VNIC_NAME",
  "vlan": "VLAN_ID"
}

Configure the guest OS for Dynamic NICs

This section describes how to complete the additional guest OS configuration that is required when you add Dynamic NICs to a new or existing instance.

Choose one of the following configuration options:

Configure automatic management of Dynamic NICs

This section describes how to configure the automatic management of Dynamic NICs by using the Google guest agent.

You only need to complete these steps once per instance. If you added a Dynamic NIC to an instance for which you already completed these steps, then you don't need to repeat them.

To configure the automatic management of Dynamic NICs:

1. Connect to the instance by using SSH.

2. Ensure that the instance is running the Google guest agent at version 20250204.02 or later:

   1. To determine whether the instance is running the Google guest agent, run the appropriate command listed in Installed packages for the guest environment.

      1. If your instance isn't running the Google guest agent, install the guest environment.

      2. If your instance is running the Google guest agent, update the guest environment.

      Installing or updating the guest environment ensures that you have the latest version of the Google guest agent. You can confirm the version by following the steps in Validating the guest environment.

3. Configure the Google guest agent to manage Dynamic NICs:

   1. Open or create your guest environment configuration file.

      edit /etc/default/instance_configs.cfg
      

   2. Add the following to the configuration file, then save your changes and exit the editor.

      [NetworkInterfaces]
      vlan_setup_enabled = true
      manage_primary_nic = true
      

      For information about these settings, see the following:

      • vlan_setup_enabled = true: configures the Google guest agent to install and manage Dynamic NICs
      • manage_primary_nic = true: an additional setting required for the Google guest agent to manage Dynamic NICs created under nic0

      For more information about editing the guest agent configuration file, see Configuration in the Google guest agent documentation.

   3. Restart the guest agent by running the following command. Alternatively, you can restart the instance.

      sudo systemctl restart google-guest-agent.service
      

4. List the network interfaces on your instance to see that the Google guest agent installed your Dynamic NICs.

   For example, the following command displays a name such as a-gcp.ens4.11 for a Dynamic NIC with a VLAN ID of 11 created as a child of the ens4 interface.

   sudo ip -d addr
   

Configure the guest OS manually

To configure Dynamic NICs in the guest OS of an instance manually:

1. Connect to the instance by using SSH.

2. If the instance is running the Google guest agent, disable the automatic management of Dynamic NICs. You can determine whether the instance is running the Google guest agent by using the appropriate command listed in Installed packages for the guest environment.

   To disable the automatic management of Dynamic NICs:

   1. Open or create your guest environment configuration file.

        edit /etc/default/instance_configs.cfg
        

   2. Add the following to the configuration file, then save your changes and exit the editor.

      [NetworkInterfaces]
      vlan_setup_enabled = false
      manage_primary_nic = false
      

      For more information about editing the guest agent configuration file, see Configuration in the Google guest agent documentation.

   3. Restart the guest agent by running the following command. Alternatively, you can restart the instance.

      sudo systemctl restart google-guest-agent.service
      

3. For each Dynamic NIC that you created, do the following:

   1. Get the MAC address of the parent vNIC. To find the MAC address, query the metadata server by running the following command:

      curl http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/VNIC_NUMBER/mac -H "Metadata-Flavor: Google"
      

      Replace VNIC_NUMBER with the number of the parent vNIC. For example, 0 for nic0 or 1 for nic1.

   2. Configure a subinterface in the guest OS of the instance. For example, on a Debian VM, run the following commands:

      sudo modprobe 8021q
      sudo ip link add link VNIC_NAME name VNIC_NAME.VLAN_ID type vlan id VLAN_ID
      sudo ip addr add IP_ADDRESS dev VNIC_NAME.VLAN_ID
      sudo ip link set dev VNIC_NAME.VLAN_ID address MAC_ADDRESS
      sudo ip link set up VNIC_NAME.VLAN_ID
      

      Replace the following:

      • VNIC_NAME: the name of the parent vNIC assigned by the operating system, such as eth1 or ens4
      • IP_ADDRESS: the IP address of the Dynamic NIC that you created
      • VLAN_ID: the VLAN ID that you assigned to the Dynamic NIC
      • MAC_ADDRESS: the MAC address that you got in the previous step