Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Layer 2 Networking

Use Layer 2 Networks in Private Cloud Director to create networks that connect VMs without managed IP, DHCP, or routing services.

Layer 2 Network is a GA feature in the 2026.8 release

A Layer 2 Network (L2 Network) is an L2-only physical network that provides basic Layer 2 connectivity between virtual machines, without managed IP addressing, routing, or security services. Layer 2 Networks are available only when creating Physical Networks. Virtual Networks are always Managed Networks and do not have an L2 option.

Use a Layer 2 Network when your infrastructure already handles IP management externally, or when you are migrating workloads from VMware and want equivalent L2 behaviour without adopting managed networking. If you need subnets, DHCP, routers, or security groups, use a managed Virtual Network or Physical Network instead.

How Layer 2 Networks Work

Layer 2 Networks provide pure Layer 2 connectivity between VMs. This means:

  • No managed IP addressing. You configure IP addresses directly inside the guest OS using static assignment or an external DHCP server.

  • No routing. VMs on the same Layer 2 Network communicate at Layer 2. Cross-network traffic requires external routing infrastructure.

  • No security groups. Port-level security is managed outside of Private Cloud Director.

  • No subnet configuration. Layer 2 Networks operate only at the data link layer

Create a Layer 2 Network

Prerequisites

  • A physical network must be configured in your cluster blueprint. See Cluster Blueprint

  • The VLAN ID you specify must exist on your physical network infrastructure.

Perform the following steps.

  1. On the Private Cloud Director UI , navigate to Networks and Security > Networks.

  2. Select Create Network and then select Physical Network.

  3. Under Basic Information, enter the following details.

Field
Description

Name

Enter a name for the network.

Description

Optionally, enter a description.

Admin State

Select Up to make the network available for VM provisioning immediately, or Down to defer availability.

MTU

Optionally, set the maximum transmission unit. Minimum value is 68 for IPv4 and 1280 for IPv6.

  1. Under Network Type, select Layer 2 Network.

NOTE Selecting Layer 2 Network hides all subnets, DHCP, router, security groups, and public IP fields. These are not applicable to Layer 2 Networks. If you choose to configure these instances, configure the Network Type to Managed Network.

  1. Enter the following details.

Field
Description

Network Label

Select the network label that maps this network to the corresponding physical network on your hypervisors.

Network Type

Select Flat (Untagged) for a network with no VLAN tags, or VLAN (Tagged) for a network that uses VLAN tagging.

  1. Optionally, select Make Shared (Across All Tenants) to make the network type available to every tenant. Only the tenant that creates the network can change this setting later.

  2. Select Create Physical Network.

The network appears in Networks and Security > Networks with a Layer 2 Network tag corresponding to the network name.

Using pcdctl CLI

Parameter
Description

PHYSICAL_NETWORK_LABEL

The label configured in the blueprint.

NETWORK_TYPE

Either vlan or flat.

VLAN_TAG

The VLAN tag. Only required if NETWORK_TYPE is vlan.

NETWORK_NAME

The name you want to assign to the network.

The --disable-port-security option is required for L2-only networks because port security is a Layer 3 feature and does not apply to L2-only networks.

On a successful network creation, you should see a similar output.

Using API:

Create network

post

Creates a network.

Authorizations
X-Auth-TokenstringRequired

PCD Identity Service token authentication

Body
Responses
201

Network created successfully

application/json
post/v2.0/networks
POST /neutron/v2.0/networks HTTP/1.1
Host: example.platform9.com
X-Auth-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 236

{
  "network": {
    "name": "test-flat-l2",
    "description": "l2-vlan",
    "mtu": 1500,
    "admin_state_up": true,
    "provider:network_type": "flat",
    "provider:physical_network": "phy-simple-nw",
    "shared": false,
    "port_security_enabled": false,
    "router:external": false
  }
}
{
  "network": {
    "id": "02e0247e-328a-4460-b82d-56ea99d639a8",
    "name": "test-flat-l2",
    "tenant_id": "68fbc006f13c4598a47dffe6576f1d47",
    "admin_state_up": true,
    "mtu": 1500,
    "status": "ACTIVE",
    "subnets": [],
    "shared": false,
    "project_id": "68fbc006f13c4598a47dffe6576f1d47",
    "port_security_enabled": false,
    "qos_policy_id": null,
    "dns_domain": "",
    "router:external": false,
    "provider:network_type": "flat",
    "provider:physical_network": "phy-simple-nw",
    "provider:segmentation_id": null,
    "availability_zone_hints": [],
    "availability_zones": [],
    "ipv4_address_scope": null,
    "ipv6_address_scope": null,
    "description": "l2-vlan",
    "tags": [],
    "created_at": "2026-06-03T01:40:03Z",
    "updated_at": "2026-06-03T01:40:03Z",
    "revision_number": 1
  }
}

We need to add a tag to the network for functionality to work correctly. This tag is immutable and L2 network functionality will not work as expected without it.

Update network

put

Updates a network.

Authorizations
X-Auth-TokenstringRequired

PCD Identity Service token authentication

Path parameters
network_idstring · uuidRequired

The ID of the network.

Body
Responses
200

Network updated successfully

application/json
put/v2.0/networks/{network_id}
PUT /neutron/v2.0/networks/{network_id} HTTP/1.1
Host: example.platform9.com
X-Auth-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "network": {
    "tags": [
      "simple_network"
    ]
  }
}
{
  "network": {
    "id": "675590d2-4e9f-49cb-b7f9-83cf1b65bcca",
    "name": "vlan-l2",
    "tenant_id": "68fbc006f13c4598a47dffe6576f1d47",
    "admin_state_up": true,
    "mtu": 1500,
    "status": "ACTIVE",
    "subnets": [],
    "shared": false,
    "project_id": "68fbc006f13c4598a47dffe6576f1d47",
    "port_security_enabled": false,
    "qos_policy_id": null,
    "dns_domain": "",
    "router:external": false,
    "provider:network_type": "vlan",
    "provider:physical_network": "phy-simple-nw",
    "provider:segmentation_id": 1000,
    "availability_zone_hints": [],
    "availability_zones": [],
    "ipv4_address_scope": null,
    "ipv6_address_scope": null,
    "description": "",
    "tags": [
      "simple_network"
    ],
    "created_at": "2026-06-03T01:46:51Z",
    "updated_at": "2026-06-03T01:48:12Z",
    "revision_number": 2
  }
}

IPAM for Layer 2 Network VMs:

Configure a static IP with cloud-init

The network: block in a cloud-init user_data payload is not applied to VMs on a Layer 2 Network. To assign a static IP, default gateway, and DNS servers, use the write_files and runcmd cloud-init modules instead. This is a known platform behavior and cannot be changed by configuration.

Ports on a Layer 2 Network are created without a fixed IP. As a result, Nova builds the VM's Config Drive with an empty network configuration. On first boot, cloud-init reads the Config Drive as its network data source and applies that empty configuration. When cloud-init then processes your user_data, it treats network configuration as already handled and ignores the network:

Before you begin, confirm the following:

  • You have a Layer 2 Network in your project. See

  • You have the static IP address (in CIDR notation), default gateway, and DNS server addresses for your environment.

  • Your VM image includes cloud-init and the network configuration tool referenced in your write_files target. The example in this section targets an Ubuntu image, where Netplan is the default.

  • You know the primary network interface name inside the guest. On Ubuntu cloud images, this is typically ens3. To confirm your image, run ip link on a booted VM from the same image.

Apply the configuration

Supply the following cloud-init payload as the user data when you deploy the VM. The example uses sample values. Replace the IP address, subnet, gateway, and DNS server values with the ones for your environment.

The write_files module creates /etc/netplan/99-custom-static.yaml on the VM during the cloud-init final stage. The runcmd module then runs netplan apply to load the configuration. The static IP, routes, and DNS servers persist across reboots.

NOTE

The password and ssh_pwauth lines in this example are inherited from the underlying test payload and are not required for the static IP workaround. Avoid placing plaintext passwords in user_data for production VMs. Use SSH keys or your standard credential delivery mechanism instead.

Verify the configuration

After the VM boots, connect to it and run the following commands to confirm that cloud-init applied the configuration:

The ip addr show output should list the static IP you configured. The cloud-init status output should show status: done. If cloud-init status reports an error, inspect /var/log/cloud-init.log and /var/log/cloud-init-output.log for details.

Adapt the example for other operating systems

The example targets Ubuntu and Netplan. For other guest operating systems, change the write_files path and the runcmd command to match the distribution's network configuration tool. For example, on a RHEL-based image, write a NetworkManager keyfile or ifcfg file and reload it with nmcli connection reload followed by nmcli connection up <CONNECTION_NAME>.

Integrate with an external IPAM or DHCP provider

Because Layer 2 Networks do not provide managed IP addressing, you can plug in any external IP Address Management (IPAM) or DHCP system to assign addresses to VMs. Private Cloud Director does not communicate with the IPAM or DHCP server directly; the integration happens entirely at Layer 2. VMs broadcast standard DHCP discovery on the L2 segment, and your existing IPAM/DHCP infrastructure responds.

Requirements

  • Reachability. The DHCP server, or a DHCP relay configured to forward to it, must be reachable in the same Layer 2 broadcast domain as the Layer 2 Network. If the server lives on a different subnet, configure a DHCP relay (ip helper-address or equivalent) on the upstream switch or router so DISCOVER and REQUEST packets reach it.

  • VLAN alignment. The VLAN ID configured on the Layer 2 Network must match the VLAN that your DHCP server or relay listens on.

  • MAC addresses (reservations only). Dynamic leases work without any prior coordination; the DHCP server learns each VM's MAC address from the DISCOVER packet. You only need to share MAC addresses with your IPAM in advance if you are pre-creating MAC-to-IP reservations. Retrieve a port's MAC address from the Ports view in the UI, or via pcdctl port show PORT_ID.

  • Guest support. The guest OS must request a DHCP lease on its primary interface. Most cloud images do this by default, but an image with a static-IP configuration or an overridden cloud-init network config will not.

Provider setup

Refer to your IPAM/DHCP vendor's own documentation for the configuration steps. The following providers are commonly used with Layer 2 Networks:

If the DHCP server is on a different subnet from the Layer 2 Network's broadcast domain, you will also need a relay agent; for example, see Install DHCP relay agent for Windows Server.

If your guest OS cannot use DHCP, or you need an address assigned before the first network packet leaves the VM, use the static-IP cloud-init workflow described next instead.

IP Address Discovery and Reporting

Private Cloud Director does not provide IP Address Management (IPAM) for Layer 2 Networks and does not assign or track the addresses that VMs use. It does, however, report the addresses it observes. Once a VM begins sending IP traffic on a Layer 2 Network, Private Cloud Director automatically detects the IP address on each of the VM's interfaces and displays it in the VM's IP Addresses information in the UI. No configuration is required. An interface shows an address only after the VM starts using one, so a VM that has not yet sent traffic appears without a discovered IP until traffic is seen.

Multi-interface IP discovery was added in the 2026.8 release. A VM with multiple interfaces on Layer 2 Networks now reports a discovered IP address for each interface. Before 2026.8, IP discovery reported only a single IP address for a VM, even when it had multiple Layer 2 interfaces.

Operations on Layer 2 Network VMs:

Deploy a VM on a Layer 2 Network

You can configure a VM for a Layer 2 Network when deploying a new VM from the Virtual Machines section.

  1. Navigate to Virtual Machines > Virtual Machines.

  2. Select Deploy New VM and proceed through the VM creation wizard.

  3. On Select Network Type, choose Layer 2 Network.

  4. Select the Layer 2 Network you want to use from the list. Managed Network options show IP configuration fields. Layer 2 Network selection hides all IP configuration fields.

  5. Select Next Step to continue creating the VM.

NOTE

When deploying a VM on a Layer 2 Network:

  • The security group field is disabled and cannot be changed.

  • You can only create one VM at a time. To create multiple VMs on the same Layer 2 Network, repeat the deployment process for each VM.

  1. Complete the remaining VM configuration and select Deploy.

After deployment, the VM instance details the following for the network attachment:

  • Network: [Network Name] (Layer 2)

  • IP Address: N/A - Configure in guest OS

NOTE

  • External DHCP configuration: If using an external DHCP server for IP assignment, ensure the DHCP server is reachable in the L2 network's broadcast domain.

  • Cloud-init workaround for network configuration: There is a known issue with setting network configurations in cloud-init. As a workaround, use the runcmd section of cloud-init to configure static IP or DHCP as shown above.

Here is an example for an Ubuntu VM.

NOTE

You may need to make changes to make this work for other operating systems.

Clone a VM on a Layer 2 Network

When cloning a VM, you can select a Layer 2 Network during the clone workflow.

The network selection page that appears during cloning follows the same workflow as the VM deployment process.

  1. Navigate to Virtual Machines > Virtual Machines.

  2. Select the VM you want to clone.

  3. Select Clone.

  4. On the network selection page, choose Layer 2 Network as the network type.

  5. Select the Layer 2 Network from the list and complete the clone process.

The same limitations apply: security groups are disabled, and only one VM can be cloned at a time.

View Layer 2 Network details

To view details and connected VMs for a Layer 2 Network:

  1. Navigate to Networks and Security > Networks.

  2. Identify Layer 2 Networks by the Layer 2 Network tag displayed next to each network name. Select the specific Layer 2 Network you want to inspect.

The network details page displays the network type as Physical. You will not be able to view details on Subnets, Router Attachments, and DHCP Configuration.

Edit a Layer 2 Network

You can update the name and description of a Layer 2 Network after it is created. The VLAN ID and physical network cannot be changed.

  1. Navigate to Networks and Security > Networks.

  2. Select the Layer 2 Network you want to edit.

  3. Select Edit.

  4. Update the Name or Description as needed.

  5. Select Save.

Delete a Layer 2 Network

Deleting a Layer 2 Network detaches all VMs connected to it. Ensure no active workloads depend on the network before proceeding.

  1. Navigate to Networks and Security > Networks.

  2. Select the Layer 2 Network you want to delete.

  3. Select Delete.

  4. Confirm the deletion when prompted.

Related Pages

After creating a Layer 2 Network and configuring IP addresses in your guest OS, you can continue managing your VMs:

PreviousVirtual Network
NextSet Up PXE Boot for VMs

Last updated

Was this helpful?