CLI — Network
CLI v1.3.0 manages VPCs and subnets, reserved public IPs, firewall rules, L4 load balancers, security groups and per-VM internet access. Concepts are in the dashboard guides: VPCs, public IPs and firewall rules.
How these commands take input
Most networking commands send one API request, read as JSON from
--file PATH or --file - (stdin). Field names
match the API reference. Flags such as
--project, --name, --vm,
--vpc and --datacenter fill the matching
fields when the file leaves them out. Unknown fields are rejected.
VPCs and subnets
A default VPC is created with your first VM. Create your own to choose address ranges and keep environments apart:
metalhost vpc create --file - <<'EOF'
{ "project_name": "projects/my-app", "display_name": "staging" }
EOF
metalhost vpc subnet create --vpc projects/my-app/vpcs/VPC_ID --file - <<'EOF'
{ "display_name": "app", "ipv4_range": "10.20.0.0/24" }
EOF
# Enable the subnet in a datacenter, then publish a network VMs can join.
metalhost vpc subnet attach --datacenter datacenters/us-dal-1 --wait --file - <<'EOF'
{ "subnet_name": "projects/my-app/vpcs/VPC_ID/subnets/SUBNET_ID" }
EOF
metalhost network create --project projects/my-app --region datacenters/us-dal-1 \
--subnet projects/my-app/vpcs/VPC_ID/subnets/SUBNET_ID | Command | What it does |
|---|---|
vpc list | get | create | update | delete | VPC definitions. Update changes the display name only. |
vpc subnet list | get | create | update | delete | Subnets. Ranges and DNS resolvers are fixed at creation. |
vpc subnet attach | Enable a subnet in a datacenter. |
vpc detach-datacenter | Remove a VPC's unused subnets from one datacenter. |
network list | create --subnet | Networks that VMs join. |
Subnets take an RFC 1918 range that does not overlap another subnet in
the same VPC, and optionally up to three custom_dns_ipv4
resolvers. Delete subnets before their VPC; anything still connected
must be removed first.
Each project includes three networks by default, and the default VPC
uses one. Beyond that, network create --subnet fails with
QUOTA_EXCEEDED until you raise the
network.network.count quota with metalhost quota request.
Reserved public IPs
A reserved IPv4 belongs to your project until you release it. Attach it to a private IPv4 on any VM in the same datacenter, detach it, and attach it elsewhere without restarting either VM.
metalhost public-ip reserve --project projects/my-app --file - <<'EOF'
{ "display_name": "web" }
EOF
# Attach: name the VM's private IPv4 and the reservation's current generation.
metalhost public-ip get --name projects/my-app/public-ips/IP_ID -o json # read "generation"
metalhost public-ip attach --name projects/my-app/public-ips/IP_ID \
--vm projects/my-app/virtual-machines/web-01 --wait --file - <<'EOF'
{ "private_ipv4": "10.20.0.5", "expected_generation": 1 }
EOF public-ip detach takes the binding's ID and generation from
the get output (binding.id,
binding.generation). If you detach a VM's default outbound
address while it has others, name the replacement with
replacement_default_public_ip_name.
public-ip release is permanent: billing stops and the
address may go to another customer.
You can also attach a reservation when creating a VM:
metalhost vm create ... --public-ip projects/my-app/public-ips/IP_ID --public-ip-generation 1
metalhost vm create ... --assign-public-ipv4 # allocate a new address
metalhost vm create ... --private-only # no public IPv4 Firewall rules
New VMs start with no inbound rules, so nothing reaches them from the internet until you add one, including SSH:
metalhost firewall create --vm projects/my-app/virtual-machines/web-01 \
--port 22/tcp --source 203.0.113.7/32 --display-name "ssh from office"
metalhost firewall create --vm projects/my-app/virtual-machines/web-01 \
--port 443/tcp --source 0.0.0.0/0 --ip-family both --display-name https
# Deny wins ties; lower priorities are evaluated first.
metalhost firewall create --vm projects/my-app/virtual-machines/web-01 \
--action deny --priority 10 --port 443/tcp --source 198.51.100.0/24
# Outbound rule: restrict what the VM may reach.
metalhost firewall create --vm projects/my-app/virtual-machines/web-01 \
--direction egress --port 443/tcp --destination 0.0.0.0/0 --ip-family ipv4
# Forward public port 2222 on an attached address to port 22 on the VM.
metalhost firewall create --vm projects/my-app/virtual-machines/web-01 \
--forward-public-ip projects/my-app/public-ips/IP_ID --port 2222:22/tcp | Command | What it does |
|---|---|
firewall list --vm NAME | List a VM's rules. |
firewall create | Add a rule. Flags: --direction, --action, --priority, --ip-family, --port, --source, --destination, --forward-public-ip. |
firewall delete NAME | Delete a rule. |
Load balancers
A regional L4 TCP load balancer puts one public IPv4 in front of VM
interfaces on a network. Backends are interface IDs from
vm network interfaces. Clients' source IPs reach the
backends unchanged.
metalhost vm network interfaces --file - <<'EOF'
{ "project_name": "projects/my-app", "target_vm": "projects/my-app/virtual-machines/web-01" }
EOF
metalhost load-balancer create --project projects/my-app --wait --file - <<'EOF'
{
"network_name": "projects/my-app/networks/NETWORK_ID",
"display_name": "web",
"listeners": [{
"port": 443, "backend_port": 443, "protocol": "TCP",
"health_check": { "port": 443, "interval_seconds": 10, "timeout_milliseconds": 2000,
"healthy_threshold": 2, "unhealthy_threshold": 3 }
}],
"backend_interface_ids": ["IFACE_ID_1", "IFACE_ID_2"],
"drain_timeout_seconds": 30
}
EOF load-balancer get shows per-backend health.
update replaces listeners and backends and needs the current
expected_generation; so does delete.
Security groups
Security groups filter traffic between VMs on the private network. Membership changes need no restart.
metalhost security-group create --project projects/my-app --file - <<'EOF'
{
"display_name": "db",
"rules": [{ "direction": "ingress", "protocol": "tcp", "port": 5432,
"security_group": "projects/my-app/security-groups/APP_GROUP_ID" }]
}
EOF
metalhost security-group add-vm --file - <<'EOF'
{ "security_group": "projects/my-app/security-groups/DB_GROUP_ID",
"vm": "projects/my-app/virtual-machines/db-01" }
EOF
Rules take action (allow or deny),
priority (1–1000), ip_family and an optional
client source-port range. See
Security groups for
how rules combine.
VM internet access and addresses
metalhost vm network internet-policy get --vm projects/my-app/virtual-machines/web-01
# Both settings are required; pass the current generation from "get".
metalhost vm network internet-policy set --vm projects/my-app/virtual-machines/web-01 --wait --file - <<'EOF'
{ "project_name": "projects/my-app", "allow_outbound_internet": false,
"allow_ipv6_internet": true, "expected_generation": 3 }
EOF | Command | What it does |
|---|---|
vm network interfaces | Interfaces, addresses and the default outbound IPv4. |
vm network internet-policy get | set | Allow outbound internet; allow IPv6 internet access. |
vm network alias add | remove | Extra private IPv4 addresses on an interface. |
vm network set-default-public-ip | Choose which attached public IPv4 new outbound connections use. |