Menu ⌃

Go SDK — Network

NetworkServiceClient in SDK v1.3.0 manages VPCs and subnets, reserved public IPs, firewall rules, L4 load balancers, security groups and per-VM internet access. Examples use github.com/google/uuid for request IDs.

VPCs, subnets and networks

net := networkv1connect.NewNetworkServiceClient(httpClient, base)
project := "projects/my-app"

vpc, err := net.CreateVpc(ctx, connect.NewRequest(&networkv1.CreateVpcRequest{
    ProjectName: project, DisplayName: "staging", RequestId: uuid.NewString(),
}))
subnet, err := net.CreateVpcSubnet(ctx, connect.NewRequest(&networkv1.CreateVpcSubnetRequest{
    VpcName: vpc.Msg.GetVpc().GetName(), DisplayName: "app",
    Ipv4Range: "10.20.0.0/24", RequestId: uuid.NewString(),
}))

// Enable the subnet in a datacenter and wait for the returned operation...
attach, err := net.AttachVpcSubnet(ctx, connect.NewRequest(&networkv1.AttachVpcSubnetRequest{
    SubnetName: subnet.Msg.GetSubnet().GetName(), DatacenterName: "datacenters/us-dal-1",
    RequestId: uuid.NewString(),
}))
// ...then publish a network VMs can join.
network, err := net.CreateNetwork(ctx, connect.NewRequest(&networkv1.CreateNetworkRequest{
    ProjectName: project, DatacenterName: "datacenters/us-dal-1",
    SubnetName: subnet.Msg.GetSubnet().GetName(), RequestId: uuid.NewString(),
}))

Subnet ranges are RFC 1918 and may not overlap within one VPC. Up to three CustomDnsIpv4 resolvers can be set when a subnet is created; empty uses Metalhost's private DNS. Delete subnets before their VPC, after anything connected to them is gone.

Reserved public IPs

ip, err := net.ReservePublicIp(ctx, connect.NewRequest(&networkv1.ReservePublicIpRequest{
    ProjectName: project, DatacenterName: "datacenters/us-dal-1",
    DisplayName: "web", RequestId: uuid.NewString(),
}))

res, err := net.AttachPublicIp(ctx, connect.NewRequest(&networkv1.AttachPublicIpRequest{
    Name:               ip.Msg.GetPublicIp().GetName(),
    TargetVm:           "projects/my-app/virtual-machines/web-01",
    PrivateIpv4:        "10.20.0.5", // an address already assigned to the VM
    ExpectedGeneration: ip.Msg.GetPublicIp().GetGeneration(),
    RequestId:          uuid.NewString(),
}))
// Wait for res.Msg.GetOperationName() before relying on the mapping.
  • Detach with DetachPublicIp, passing the binding's ID and generation. When the address is the VM's default outbound IPv4 and others remain, set ReplacementDefaultPublicIpName.
  • Release with ReleasePublicIp once detached. This is permanent and stops billing.
  • At VM create, set PublicIpName and ExpectedPublicIpGeneration in the VM's network options to attach an existing reservation.
  • SetVmDefaultPublicIp picks which attached address new outbound connections use.

Firewall rules

New VMs have no inbound rules. Rules take a Direction (ingress or egress), Action (allow or deny), Priority (lower nonzero values win; deny wins ties), IpFamily and up to 32 source CIDRs.

vm := "projects/my-app/virtual-machines/web-01"

// Allow HTTPS from anywhere, over IPv4 and IPv6.
net.CreateFirewallRule(ctx, connect.NewRequest(&networkv1.CreateFirewallRuleRequest{
    ProjectName: project, DatacenterName: "datacenters/us-dal-1", TargetVm: vm,
    Direction: "ingress", Action: "allow", IpFamily: "both",
    Sources:   []string{"0.0.0.0/0", "::/0"},
    Ports:     []*networkv1.PortMapping{{Protocol: "tcp", Port: 443}},
    RequestId: uuid.NewString(),
}))

// Forward public port 2222 on an attached address to port 22 on the VM.
net.CreateFirewallRule(ctx, connect.NewRequest(&networkv1.CreateFirewallRuleRequest{
    ProjectName: project, DatacenterName: "datacenters/us-dal-1", TargetVm: vm,
    ForwardingPublicIp: ip.Msg.GetPublicIp().GetName(),
    Ports:     []*networkv1.PortMapping{{Protocol: "tcp", Port: 2222, TargetPort: 22}},
    RequestId: uuid.NewString(),
}))

Load balancers

Regional L4 TCP, including TLS passthrough. Backends receive the client's real source IP. GetLoadBalancer reports per-backend health; UpdateLoadBalancer and DeleteLoadBalancer take the current ExpectedGeneration.

ifaces, err := net.GetVmNetworkInterfaces(ctx, connect.NewRequest(&networkv1.GetVmNetworkInterfacesRequest{
    ProjectName: project, TargetVm: vm,
}))
var backends []string
for _, i := range ifaces.Msg.GetInterfaces() {
    backends = append(backends, i.GetId())
}

lb, err := net.CreateLoadBalancer(ctx, connect.NewRequest(&networkv1.CreateLoadBalancerRequest{
    ProjectName: project, DatacenterName: "datacenters/us-dal-1",
    NetworkName: network.Msg.GetNetwork().GetName(), DisplayName: "web",
    Listeners: []*networkv1.LoadBalancerListener{{
        Port: 443, BackendPort: 443, Protocol: "TCP",
        HealthCheck: &networkv1.LoadBalancerHealthCheck{
            Port: 443, IntervalSeconds: 10, TimeoutMilliseconds: 2000,
            HealthyThreshold: 2, UnhealthyThreshold: 3,
        },
    }},
    BackendInterfaceIds: backends, DrainTimeoutSeconds: 30, RequestId: uuid.NewString(),
}))

Security groups

CreateSecurityGroup, AddVmToSecurityGroup and RemoveVmFromSecurityGroup manage private-network policy. Each SecurityGroupRule has a direction, protocol, port range, a peer (Cidr or another SecurityGroup), and optionally an action, priority and IP family. See Security groups.

VM internet access

pol, err := net.GetVmInternetPolicy(ctx, connect.NewRequest(&networkv1.GetVmInternetPolicyRequest{
    ProjectName: project, TargetVm: vm,
}))

// Both settings are required: omission is not read as false.
allowOut, allowV6 := false, true
net.UpdateVmInternetPolicy(ctx, connect.NewRequest(&networkv1.UpdateVmInternetPolicyRequest{
    ProjectName: project, TargetVm: vm,
    AllowOutboundInternet: &allowOut, AllowIpv6Internet: &allowV6,
    ExpectedGeneration: pol.Msg.GetPolicy().GetGeneration(),
    RequestId:          uuid.NewString(),
}))

The change applies asynchronously: the policy's ObservedGeneration catches up with Generation once it is enforced.

What's next