Skip to main content

​
Overview

This guide covers the most common networking issues encountered in Polystack Cloud Platform and provides step-by-step resolution procedures. Each scenario includes diagnostic commands and remediation steps that you can apply from the Dashboard or CLI.
Prerequisites
  • CLI configured with valid credentials
  • Access to the Polystack Dashboard for instance console access

​
Diagnostic Quick Reference

Before working through individual scenarios, run these commands to gather a complete picture of your networking state:
Check overall network resource status
Check instance network attachment

​
Common Issues

Cause: Missing router interface, DHCP failure, or security group blocking traffic.Resolution:
  1. Verify the instance received a DHCP-assigned IP:
    Check instance IP assignments
  2. Confirm the subnet has a router interface:
    List router interfaces
  3. Check the security group allows the expected traffic:
    List ingress rules for security group
  4. Verify the DHCP agent is alive:
    Check DHCP agent status
Use the Dashboard console (VNC) under Compute > Instances and use the Console action to check whether the instance received an IP from inside the guest OS. A valid IP confirms DHCP is working and the issue is at the network or security group layer.
Cause: Missing association, router has no external gateway, or the security group is missing an ingress rule for the required port.Resolution:
  1. Confirm the floating IP is associated:
    Show floating IP status
    The port_id field must be non-empty and status must be ACTIVE.
  2. Verify the router has an external gateway:
    Show router gateway
  3. Check the security group assigned to the instance allows the port you are connecting on (e.g., TCP 22 for SSH, TCP 80 for HTTP):
    List security group rules
  4. Ping the floating IP from outside to confirm basic reachability:
    Test ICMP reachability
Cause: DHCP agent is down, DHCP is disabled on the subnet, or the allocation pool is exhausted.Resolution:
  1. Confirm DHCP is enabled on the subnet:
    Check subnet DHCP status
  2. Check the allocation pool is not exhausted:
    List ports consuming addresses
    Compare the count against your pool size (a /24 provides 253 usable addresses).
  3. Verify the DHCP agent is alive:
    List DHCP agents
    If the agent shows Alive: False, contact your administrator to restart the agent service. See the Network Agent Management guide.
Cause: VXLAN encapsulation adds a 50-byte overhead. If instances use the default MTU of 1500, large packets are fragmented silently, degrading throughput and causing application-level timeouts.Resolution:Update the network MTU to account for encapsulation overhead:
Set VXLAN-appropriate MTU on network
Instances receive the updated MTU via DHCP option 26 on next renewal. For immediate effect, set the MTU manually on the guest OS:
Set MTU on Linux guest
For VXLAN networks, Polystack recommends an MTU of 1450. For VLAN networks backed by jumbo-frame-capable switches, you may use up to 9000.
Cause: The security group is not assigned to the instance, or the rule was added to the wrong group.Resolution:
  1. List security groups assigned to the instance:
    Show instance security groups
  2. List rules in the expected group:
    Show all rules in group
  3. If the group is not assigned, add it:
    Assign security group to instance
Rules take effect immediately without a restart — re-test connectivity after adding the group.
Cause: HA router VRRP failover completed but the new master has not programmed floating IP NAT rules correctly.Resolution:
  1. Check the router HA state:
    Show router HA fields
  2. List L3 agents for the router and confirm exactly one is active:
    List L3 agents handling the router
  3. Trigger rescheduling by toggling the router admin state:
    Reschedule router

​
Useful Diagnostic Commands

Show all ports on a network
Show port details including fixed IP and security groups
List all floating IPs in the project
Show network agent heartbeat timestamps

​
Next Steps

Network Agent Management

Monitor and manage SDN agents when diagnostic commands show agent failures

Network Security Groups

Review and update firewall rules to resolve connectivity issues

Routers and Gateways

Verify and correct router configuration for floating IP and NAT issues

DHCP Configuration

Administer DHCP agents for IP assignment troubleshooting