Networks API

The NetworkService (pivirt.network.v1) provides centralized management of software-defined networks, Linux/OVS bridges, 802.1Q VLAN tags, multi-host VXLAN overlays, and network security policies.

Service Definition

package pivirt.network.v1;

service NetworkService {
  // Network operations
  rpc CreateNetwork(CreateNetworkRequest) returns (Network);
  rpc GetNetwork(GetNetworkRequest) returns (Network);
  rpc ListNetworks(ListNetworksRequest) returns (stream Network);
  rpc DeleteNetwork(DeleteNetworkRequest) returns (google.protobuf.Empty);
  rpc UpdateNetwork(UpdateNetworkRequest) returns (Network);

  // VLAN operations
  rpc CreateVLAN(CreateVLANRequest) returns (VLAN);
  rpc ListVLANs(ListVLANsRequest) returns (stream VLAN);
  rpc DeleteVLAN(DeleteVLANRequest) returns (google.protobuf.Empty);

  // VXLAN operations
  rpc CreateVXLAN(CreateVXLANRequest) returns (VXLAN);
  rpc ListVXLANS(ListVXLANSRequest) returns (stream VXLAN);
  rpc DeleteVXLAN(DeleteVXLANRequest) returns (google.protobuf.Empty);

  // Network policy operations
  rpc CreateNetworkPolicy(CreateNetworkPolicyRequest) returns (NetworkPolicy);
  rpc GetNetworkPolicy(GetNetworkPolicyRequest) returns (NetworkPolicy);
  rpc ListNetworkPolicies(ListNetworkPoliciesRequest) returns (stream NetworkPolicy);
  rpc DeleteNetworkPolicy(DeleteNetworkPolicyRequest) returns (google.protobuf.Empty);
}

Messages

Network

message Network {
  string id = 1;
  string name = 2;
  NetworkType type = 3;
  NetworkStatus status = 4;
  string cidr = 5;
  string gateway = 6;
  repeated string dns_servers = 7;
  map<string, string> config = 8;
  map<string, string> labels = 9;
  google.protobuf.Timestamp created_at = 10;
  google.protobuf.Timestamp updated_at = 11;
}

enum NetworkType {
  NETWORK_TYPE_UNSPECIFIED = 0;
  NETWORK_TYPE_BRIDGE = 1;
  NETWORK_TYPE_VLAN = 2;
  NETWORK_TYPE_VXLAN = 3;
  NETWORK_TYPE_SRIOV = 4;
}

enum NetworkStatus {
  NETWORK_STATUS_UNSPECIFIED = 0;
  NETWORK_STATUS_ACTIVE = 1;
  NETWORK_STATUS_INACTIVE = 2;
  NETWORK_STATUS_ERROR = 3;
}

VLAN

message VLAN {
  string id = 1;
  string name = 2;
  string bridge = 3;
  int32 vlan_id = 4;
  bool tagged = 5;
  VLANStatus status = 6;
  google.protobuf.Timestamp created_at = 7;
}

enum VLANStatus {
  VLAN_STATUS_UNSPECIFIED = 0;
  VLAN_STATUS_ACTIVE = 1;
  VLAN_STATUS_INACTIVE = 2;
  VLAN_STATUS_ERROR = 3;
}

VXLAN

message VXLAN {
  string id = 1;
  string name = 2;
  int32 vni = 3;
  string local_ip = 4;
  repeated string remote_ips = 5;
  int32 port = 6;
  int32 ttl = 7;
  bool learning = 8;
  VXLANStatus status = 9;
  google.protobuf.Timestamp created_at = 10;
}

enum VXLANStatus {
  VXLAN_STATUS_UNSPECIFIED = 0;
  VXLAN_STATUS_ACTIVE = 1;
  VXLAN_STATUS_INACTIVE = 2;
  VXLAN_STATUS_ERROR = 3;
}

NetworkPolicy

message NetworkPolicy {
  string id = 1;
  string name = 2;
  string namespace = 3;
  PodSelector pod_selector = 4;
  repeated NetworkPolicyRule ingress = 5;
  repeated NetworkPolicyRule egress = 6;
  google.protobuf.Timestamp created_at = 7;
  google.protobuf.Timestamp updated_at = 8;
}

message PodSelector {
  map<string, string> match_labels = 1;
  repeated LabelSelectorRequirement match_expressions = 2;
}

message NetworkPolicyRule {
  repeated NetworkPolicyPeer from = 1;
  repeated NetworkPolicyPeer to = 2;
  repeated NetworkPolicyPort ports = 3;
}

message NetworkPolicyPeer {
  PodSelector pod_selector = 1;
  NamespaceSelector namespace_selector = 2;
  IPBlock ip_block = 3;
}

message NetworkPolicyPort {
  string protocol = 1;
  int32 port = 2;
  int32 end_port = 3;
}

Methods

CreateNetwork

message CreateNetworkRequest {
  string name = 1;
  NetworkType type = 2;
  string cidr = 3;
  string gateway = 4;
  repeated string dns_servers = 5;
  map<string, string> config = 6;
  map<string, string> labels = 7;
}

Example:

grpcurl -plaintext -d '{
  "name": "vxlan-net",
  "type": "NETWORK_TYPE_VXLAN",
  "cidr": "10.10.0.0/16",
  "gateway": "10.10.0.1",
  "dns_servers": ["8.8.8.8", "8.8.4.4"],
  "config": {
    "vni": "1000",
    "local_ip": "10.0.1.10",
    "remote_ips": "10.0.1.11,10.0.1.12"
  }
}' localhost:9001 pivirt.network.v1.NetworkService/CreateNetwork

CreateVLAN

message CreateVLANRequest {
  string name = 1;
  string bridge = 2;
  int32 vlan_id = 3;
  bool tagged = 4;
}

Example:

grpcurl -plaintext -d '{
  "name": "vlan10",
  "bridge": "virbr0",
  "vlan_id": 10,
  "tagged": true
}' localhost:9001 pivirt.network.v1.NetworkService/CreateVLAN

CreateVXLAN

message CreateVXLANRequest {
  string name = 1;
  int32 vni = 2;
  string local_ip = 3;
  repeated string remote_ips = 4;
  int32 port = 5;
  int32 ttl = 6;
  bool learning = 7;
}

Example:

grpcurl -plaintext -d '{
  "name": "vxlan100",
  "vni": 100,
  "local_ip": "10.0.1.10",
  "remote_ips": ["10.0.1.11", "10.0.1.12"],
  "port": 4789,
  "ttl": 64,
  "learning": true
}' localhost:9001 pivirt.network.v1.NetworkService/CreateVXLAN

CreateNetworkPolicy

message CreateNetworkPolicyRequest {
  string name = 1;
  string namespace = 2;
  PodSelector pod_selector = 3;
  repeated NetworkPolicyRule ingress = 4;
  repeated NetworkPolicyRule egress = 5;
}

Example:

grpcurl -plaintext -d '{
  "name": "web-isolation",
  "namespace": "production",
  "pod_selector": {
    "match_labels": {
      "app": "web"
    }
  },
  "ingress": [{
    "from": [{
      "namespace_selector": {
        "match_labels": {
          "name": "monitoring"
        }
      }
    }],
    "ports": [{
      "protocol": "TCP",
      "port": 80
    }]
  }]
}' localhost:9001 pivirt.network.v1.NetworkService/CreateNetworkPolicy

Error Codes

Code	Description
`NOT_FOUND`	Network or policy not found
`ALREADY_EXISTS`	Network or policy with same name exists
`INVALID_ARGUMENT`	Invalid network configuration
`RESOURCE_EXHAUSTED`	Insufficient network resources
`FAILED_PRECONDITION`	Network in use, cannot delete