Add Dynamic Network Interfaces to an instance

This page describes how to add a Dynamic Network Interface (NIC) to an existingCompute Engine instance.

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

Before you begin

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

Add a Dynamic NIC

The following sections describe how to add a Dynamic NIC to anindividual instance or instances that are part of a managed instance group (MIG).

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

Add a Dynamic NIC to an instance

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

Console

  1. In the Google Cloud console, go to theVM instances page.

    Go to VM instances

  2. Click the name of the instance for which you want to add a Dynamic NIC.

  3. On the instance details page, clickEdit.

  4. In theDynamic Network Interfaces section, clickAdd a Dynamic Network Interface and do the following:

    1. In theInterface type field, selectVPC.

    2. In theParent network interface field, select the parent vNIC forwhich to create the Dynamic NIC.

    3. In theVLAN ID field, enter the VLAN ID of the Dynamic NIC.

    4. ForNetwork andSubnetwork, select the networkand subnetwork that you want to use.

    5. Select one of the following options for theIP stack type for theDynamic NIC:

      • IPv4 (single-stack)
      • IPv4 and IPv6 (dual-stack)
      • IPv6 (single-stack)

    6. For Dynamic NICs with IPv4 addresses, do the following:

      1. ForPrimary internal IPv4 address, select one of the following:

        • Ephemeral (Automatic) to automatically assign a newephemeral IPv4 address
        • Ephemeral (Custom) to manually specify a new ephemeral IPv4 address
        • A reserved static internal IPv4 address from the list
        • Reserve static internal IPv4 address to reserve and assign a new static internal IPv4 address

      2. ForExternal IPv4 address, select one of the following:

        • Ephemeral to assign a new ephemeral IPv4 address
        • None to not assign an external IPv4 address
        • A reserved static IPv4 address from the list
        • Reserve static external IP address to reserve and assign a new static external IPv4 address

      3. You can optionally assign one or morealias IP ranges to thenetwork interface. To assign an alias IP range, do the following:

        1. InAlias IP ranges, clickAdd IP range.
        2. InSubnet range, select a subnet primary IPv4 address rangeor a subnet secondary IPv4 address range to use.
        3. ForAlias IP range, enter an IP range in CIDR notation.This range must be an unused range of the subnet IP range thatyou selected.

        For more information about assigning alias IP ranges to VM networkinterfaces, seeConfigure alias IP ranges.

    7. For Dynamic NICs with IPv6 addresses, configure an internalor external IPv6 address range, depending on the access type of theconnected subnet. For thePrimary internal IPv6 address orExternal IPv6 address, select from the following:

      • Ephemeral (Automatic) to automatically assign a new ephemeral IPv6 address range
      • Ephemeral (Custom) to manually specify a new ephemeral IPv6 address range
      • A reserved static IPv6 address range from the list
      • Reserve static internal IPv6 address orReserve static external IPv6 address to reserve and assign a new static IPv6 address range

    8. To finish editing the properties of the Dynamic NIC, clickDone.

  5. To save your configuration, clickSave.

gcloud

To add a Dynamic NIC to an existing instance, use thegcloud compute instances network-interfaces add command.

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

Replace the following:

  • INSTANCE_NAME: the name of the instance to addthe Dynamic NIC to
  • ZONE: the zone of the instance
  • VLAN_ID: the VLAN ID of the Dynamic NIC
  • PARENT_VNIC_NAME: the name of the parent vNIC,such asnic0
  • NETWORK: the network where the Dynamic NIC attaches
  • SUBNET: the subnet where the Dynamic NIC attaches

Alternatively, you can add a Dynamic NIC to an instance whenupdating instance properties. For more information, seeUpdate instance properties.

API

To add a Dynamic NIC to an existing instance, use theinstances.addNetworkInterface method.

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

Replace the following:

  • PROJECT_ID: the ID of the project that containsthe instance
  • ZONE: the zone that contains the instance
  • INSTANCE_NAME: the name of the instance to add aDynamic NIC to
  • REGION: the region that contains the instance
  • SUBNET: the subnet where the Dynamic NICattaches
  • PARENT_VNIC_NAME: the name of the parent vNIC,such asnic0
  • VLAN_ID: the VLAN ID of the Dynamic NIC

Alternatively, you can add a Dynamic NIC to an instance whenupdating instance properties. For more information, seeUpdate instance properties.

Add a Dynamic NIC to instances in a MIG

This section describes how to add a Dynamic NIC to instancesin a MIG by creating a new instance template and applying the configurationto the MIG. Updating an existing instance template is not supported.

For more information about creating instance templates, seeCreate instance templates.To view existing instance templates, seeGet, list, and delete instance templates.

Console

  1. Go to theInstance templates page.

    Go to Instance templates

  2. Click the instance template that you want to copy and update.

  3. ClickCreate similar.

  4. Expand theAdvanced options section, and then expand theNetworking section.

  5. In theDynamic Network Interfaces section, clickAdd a Dynamic Network Interface and do the following:

    1. In theInterface type field, selectVPC.

    2. In theParent network interface field, select the parent vNIC forwhich to create the Dynamic NIC.

    3. In theVLAN ID field, enter the VLAN ID of the Dynamic NIC.

    4. ForNetwork andSubnetwork, select the networkand subnetwork that you want to use.

    5. Select one of the following options for theIP stack type for theDynamic NIC:

      • IPv4 (single-stack)
      • IPv4 and IPv6 (dual-stack)
      • IPv6 (single-stack)

    6. For Dynamic NICs with IPv4 addresses, do the following:

      1. ForPrimary internal IPv4 address, select one of the following:

        • Ephemeral (Automatic) to automatically assign a newephemeral IPv4 address
        • Ephemeral (Custom) to manually specify a new ephemeral IPv4 address
        • A reserved static internal IPv4 address from the list
        • Reserve static internal IPv4 address to reserve and assign a new static internal IPv4 address

      2. ForExternal IPv4 address, select one of the following:

        • Ephemeral to assign a new ephemeral IPv4 address
        • None to not assign an external IPv4 address
        • A reserved static IPv4 address from the list
        • Reserve static external IP address to reserve and assign a new static external IPv4 address

      3. You can optionally assign one or morealias IP ranges to thenetwork interface. To assign an alias IP range, do the following:

        1. InAlias IP ranges, clickAdd IP range.
        2. InSubnet range, select a subnet primary IPv4 address rangeor a subnet secondary IPv4 address range to use.
        3. ForAlias IP range, enter an IP range in CIDR notation.This range must be an unused range of the subnet IP range thatyou selected.

        For more information about assigning alias IP ranges to VM networkinterfaces, seeConfigure alias IP ranges.

    7. For Dynamic NICs with IPv6 addresses, configure an internalor external IPv6 address range, depending on the access type of theconnected subnet. For thePrimary internal IPv6 address orExternal IPv6 address, select from the following:

      • Ephemeral (Automatic) to automatically assign a new ephemeral IPv6 address range
      • Ephemeral (Custom) to manually specify a new ephemeral IPv6 address range
      • A reserved static IPv6 address range from the list
      • Reserve static internal IPv6 address orReserve static external IPv6 address to reserve and assign a new static IPv6 address range

    8. To finish editing the properties of the Dynamic NIC, clickDone.

  6. To create the instance template, clickCreate.

  7. Follow the steps toapply new VM configurations in a MIG.

    If you want to update the instances without restarting or recreating them,set the minimal action toREFRESH. For more information, see the following:

gcloud

  1. To create a new instance template that adds a Dynamic NIC,use thegcloud compute instance-templates create command.

    Include the--network-interface flag for each network interface fromyour existing instance template and add a new network interface thatspecifies thevlan key to create a Dynamic NIC.

    The following example adds a Dynamic NIC undernic0. Youcan specify additional network interfaces andproperties as needed. For more examples of how to create instances withmultiple network interfaces, seeCreate VMs with multiple network interfaces.

    gcloud compute instance-templates createINSTANCE_TEMPLATE_NAME \   --network-interface=network=NETWORK_A,subnet=SUBNET_A \   --network-interface=network=NETWORK_B,subnet=SUBNET_B,vlan=VLAN_ID

    Replace the following:

    • INSTANCE_TEMPLATE_NAME: a name for the new instance template.
    • NETWORK_A,NETWORK_B: the network where the interfaceattaches.
    • SUBNET_A,SUBNET_B: the subnet where the interface attaches.
    • VLAN_ID: a VLAN ID. Specifying a VLAN ID configuresthe network interface as a Dynamic NIC. You must place aDynamic NIC after its parent vNIC in the command.

  2. Follow the steps toapply new VM configurations in a MIG.

    If you want to update the instances without restarting or recreating them,set the minimal action toREFRESH. For more information, see the following:

API

  1. To create a new instance template that adds a Dynamic NIC,use theinstanceTemplates.insert method to create a global instance template or theregionInstanceTemplates.insert method to create a regional instance template.

    In thenetworkInterfaces field, specify each network interface from yourexisting instance template and add a new network interfacethat includes thevlan field to create a Dynamic NIC.

    The following example adds a Dynamic NIC undernic0. Youcan specify additional network interfaces andproperties as needed. For more examples of how to create instances withmultiple network interfaces, seeCreate VMs with multiple network interfaces.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/instanceTemplates{   ....   "networkInterfaces": [     {       "subnetwork": "regions/REGION/subnetworks/SUBNET_A"     },     {       "subnetwork": "regions/REGION/subnetworks/SUBNET_B",       "vlan": "VLAN_ID"     },       additional network interfaces...   ],   other instance settings... }

    Replace the following:

    • PROJECT_ID: the ID of the project that contains theinstance template.
    • REGION: the region that contains the instances.
    • SUBNET_A,SUBNET_B: the subnets where each network interfaceis located.
    • VLAN_ID: a VLAN ID. Specifying a VLAN ID configuresthe network interface as a Dynamic NIC. You must place aDynamic NIC after its parent vNIC the request.

  2. Follow the steps toapply new VM configurations in a MIG.

    If you want to update the instances without restarting or recreating them,set the minimal action toREFRESH. For more information, see the following:

Configure the guest OS for Dynamic NICs

This section describes how to complete the additional guest OS configurationthat is required when you add Dynamic NICs to a new or existinginstance.

Choose one of the following configuration options:

Configuration optionDescription
Configure automatic management of Dynamic NICs (Recommended)

Use the guest agent for the automatic management of Dynamic NICs.

Theguest environment includes theguest agent, which automates the installation and management of VLAN interfaces in the root namespace on Linux distributions of Google Cloud OS images.

If you configure the automatic management of Dynamic NICs, use guest agent version20251205.00 or later. While support for this functionality was introduced in guest agent version20250204.02, there areknown issues with the installation and management of Dynamic NICs in some subsequent guest agent versions.

Configure the guest OS manually

Run commands in the guest OS to install the Dynamic NICs.

If you use this option, your configuration doesn't automatically persist after a restart of the instance. To cause the configurations to persist after a restart, use the recommended method for configuring persistent network interfaces for your Linux distribution. For example, seeNetworkConfiguration for Debian andinterfaces for Ubuntu.

Configure automatic management of Dynamic NICs

This section describes how to configure the automatic management ofDynamic NICs by using the guest agent.

You only need to complete these steps once per instance.If you added a Dynamic NIC to an instance forwhich 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 instanceby using SSH.

  2. Ensure that the instance is running guest agent version20251205.00 or later:

    1. To determine whether the instance is running the guest agent, runthe appropriate command listed inInstalled packages for the guestenvironment.

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

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

      Installing or updating the guest environment ensures that you have thelatest version of the guest agent. You can confirm the version byfollowing the steps inValidating the guestenvironment.

  3. Configure the 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 theeditor.

      [NetworkInterfaces]vlan_setup_enabled = truemanage_primary_nic = true

      For information about these settings, see the following:

      • vlan_setup_enabled = true: configures the guest agent toinstall and manage Dynamic NICs
      • manage_primary_nic = true: an additional setting required for theguest agent to manage Dynamic NICs created undernic0

      For more information about editing the guest agent configuration file, seeConfigurationin the 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 seethat the guest agent installed your Dynamic NICs.

    For example, the following command displays a name such asa-gcp.ens4.11 for aDynamic NIC with a VLAN ID of11 created as a child of theens4 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 instanceby using SSH.

  2. If the instance is running the guest agent, disable the automaticmanagement of Dynamic NICs. You can determine whether theinstance is running the guest agent by using the appropriate commandlisted inInstalled packages for the guestenvironment.

    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 theeditor.

      [NetworkInterfaces]vlan_setup_enabled = falsemanage_primary_nic = false

      For more information about editing the guest agent configuration file, seeConfigurationin the 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 Dynamic NIC. To find the MACaddress, query the metadata server by running the following command:

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

      ReplaceVNIC_NUMBER/VLAN_ID with thenumber of the parent vNIC and the VLAN ID of the Dynamic NIC.For example,0/2 fornic0.2 or1/4 fornic1.4.

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

      sudo modprobe 8021qsudo ip link add linkVNIC_NAME nameVNIC_NAME.VLAN_ID type vlan idVLAN_IDsudo ip addr addIP_ADDRESS devVNIC_NAME.VLAN_IDsudo ip link set devVNIC_NAME.VLAN_ID addressMAC_ADDRESSsudo ip link set upVNIC_NAME.VLAN_ID

      Replace the following:

      • VNIC_NAME: the name of the parent vNIC assigned by theoperating system, such aseth1 orens4
      • IP_ADDRESS: the IP address of the Dynamic NICthat you created
      • VLAN_ID: the VLAN ID that you assigned to theDynamic NIC
      • MAC_ADDRESS: the MAC address that you got in theprevious step

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.