Allocating custom private addresses to resources

By default, Nebius AI Cloud networks and subnets provide private IP addresses from specific CIDR blocks. These blocks depend on the network’s or subnet’s region. If you need private addresses outside these blocks, add the required CIDR block to one of the network’s pools, or create a new pool and add it to the network. A pool must belong to the network before its addresses can be used in that network’s subnets. Next, create a subnet with that CIDR block in the network. As a result, you can allocate random or specific addresses from this block in the required network or subnet.

Prerequisites

1. Make sure you are in a group that has at least the editor role within your tenant; for example, the default editors group. You can check this in the Administration → IAM section of the web console.

2. Install and initialize the Nebius AI Cloud CLI.

3. Install jq to extract IDs and tokens from the JSON data returned by the Nebius AI Cloud CLI:

   Ubuntu

   sudo apt-get install jq
   

How to allocate addresses

1. Determine what CIDR block you need and save it to an environment variable. The block must fall within the RFC 1918 private address ranges: 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16, and must not overlap with CIDR blocks already used by other pools or subnets in the network, or with external networks the VM reaches over a Nebius VPN Gateway.

   export CUSTOM_SUBNET_CIDR=<CIDR_block>
   
   When you choose a custom CIDR block, do not use 172.17.0.0/16. It conflicts with the Docker default bridge network and can make virtual machines unreachable. For more information, see Virtual machine is unreachable due to a Docker subnet conflict.

2. Get the ID of the required network and save it to an environment variable:

   export NETWORK_ID=$(nebius vpc network get-by-name \
     --name <network_name> \
     --format json | jq -r ".metadata.id")
   

3. Get the ID of this network’s private pool and save it to an environment variable:

   export PRIVATE_POOL_ID=$(nebius vpc network get \
     --id $NETWORK_ID \
     --format json | jq -r ".spec.ipv4_private_pools.pools[0].id")
   

   As this command contains pools[0], it saves the ID of the private pool that goes first in the network specification. If you need a different pool, specify its index in pools[<index>]. To check the order of pools, run nebius vpc network list.

4. Add the CUSTOM_SUBNET_CIDR block to the private pool with PRIVATE_POOL_ID:

   echo $(nebius vpc pool get --id $PRIVATE_POOL_ID --format json | \
     jq '.spec.cidrs += [{"cidr":$ENV.CUSTOM_SUBNET_CIDR}] |
     {metadata: .metadata, spec: .spec}') | \
     nebius vpc pool update -
   

5. Create a new subnet with this private pool and save the subnet ID to an environment variable:

   export SUBNET_ID=$(nebius vpc subnet create \
     --name private_subnet \
     --network-id $NETWORK_ID \
     --ipv4-private-pools-pools "[{\"cidrs\":[{\"cidr\":\"$CUSTOM_SUBNET_CIDR\"}]}]" \
     --format json | jq -r ".metadata.id")
   

6. (Optional) To assign the VM a specific IP address, create an allocation within this subnet and save its ID to an environment variable:

   export ALLOCATION_ID=$(nebius vpc allocation create \
     --name private_allocation \
     --ipv4-private-subnet-id $SUBNET_ID \
     --ipv4-private-cidr <IP_address> \
     --format json | jq -r ".metadata.id")
   

   The --ipv4-private-cidr parameter sets the IP address for the allocation. Make sure that this address is within the subnet’s CIDR block. Without this parameter, the command creates an allocation with a random IP address from the subnet.

7. Create a VM in the new subnet:

   nebius compute instance create \
     --name <VM_name> \
     --stopped <true|false> \
     --resources-platform <platform> \
     --resources-preset <preset> \
     --boot-disk-existing-disk-id <boot_disk_ID> \
     --boot-disk-attach-mode READ_WRITE \
     --network-interfaces '[{"name": "<network_interface_name>", "subnet_id": "<subnet_ID>", "ip_address": {}, "public_ip_address": {}}]'
   

   The VM is assigned a private IP address from the subnet’s pool. To assign the specific address from the allocation instead, set ip_address to {"allocation_id": "$ALLOCATION_ID"} inside the --network-interfaces parameter. If you later delete the VM, you can reuse the allocation for another VM.